Message ID | 87r1vxfmcm.fsf@mid.deneb.enyo.de |
---|---|
State | New |
Headers | show |
Series | Document the internal _ and N_ macros | expand |
On 5/6/20 5:23 AM, Florian Weimer wrote: > ----- > Tested by building glibc on x86_64-linux-gnu. > Your comment indicates that N_ is deprecated, but doesn't list what we have switched to. This doesn't follow your recommendation to Andreas, which is to use some new macro? I think this patch should include such a new macro, and switch all of the N_ entries which we won't translate to that new macro, and mention the use of the new macro in the comment below (leaving N_ for the actual intended use). > include/libintl.h | 33 +++++++++++++++++++++++++-------- > 1 file changed, 25 insertions(+), 8 deletions(-) > > diff --git a/include/libintl.h b/include/libintl.h > index 9a11367ec6..4b0a0e8674 100644 > --- a/include/libintl.h > +++ b/include/libintl.h > @@ -37,17 +37,34 @@ extern char *__bind_textdomain_codeset (const char *__domainname, > extern const char _libc_intl_domainname[]; > libc_hidden_proto (_libc_intl_domainname) > > -/* Define the macros `_' and `N_' for conveniently marking translatable > - strings in the libc source code. We have to make sure we get the > - correct definitions so we undefine the macros first. */ > +/* _ marks its argument, a string literal, for translation, and > + performs translation at run time if the LC_MESSAGES locale category > + has been set. The MSGID argument is extracted, added to the > + translation database, and eventually submitted to the translation > + team for processing. New translations are periodically > + incorporated into the glibc source tree as part of translation > + updates. */ > +# undef _ > +# define _(msgid) __dcgettext (_libc_intl_domainname, msgid, LC_MESSAGES) > > +/* N_ marks its argument, a string literal, for translation, so that > + it is extracted and added to the translation database (similar to > + the _ macro above). It does not translate the string at run time. > + The first, primary use case for N_ is a context in which a string > + literal is required, such as an initializer. Translation will > + happen later, for example using the __gettext function. > + > + The second, historic, use case involves strings which may be > + translated in a future version of the library, but cannot be > + translated in current releases due to some technical limitation > + (e.g., gettext not being available in the dynamic loader). No > + translation at run time happens in such cases. This usage is > + deprecated because using N_ for strings which are not translated > + after all creates unnecessary work for the translation team: glibc > + does not currently use those translations, and that may never > + change. */ > # undef N_ > # define N_(msgid) msgid > > -# undef _ > -/* This is defined as an optimizing macro, so use it. */ > -# define _(msgid) \ > - __dcgettext (_libc_intl_domainname, msgid, LC_MESSAGES) > - > # endif /* !_ISOMAC */ > #endif >
* Carlos O'Donell: > On 5/6/20 5:23 AM, Florian Weimer wrote: >> ----- >> Tested by building glibc on x86_64-linux-gnu. >> > > Your comment indicates that N_ is deprecated, but doesn't list what we > have switched to. This doesn't follow your recommendation to Andreas, > which is to use some new macro? We don't have consensus on what to do instead. I think there is consensus that it's deprecated, though. > I think this patch should include such a new macro, and switch all of > the N_ entries which we won't translate to that new macro, and mention > the use of the new macro in the comment below (leaving N_ for the > actual intended use). I think we should document what we have today, so that someone who encounters these macros is less confused by them.
On 5/6/20 5:23 AM, Florian Weimer wrote: > ----- > Tested by building glibc on x86_64-linux-gnu. > Please post v2 for review. > include/libintl.h | 33 +++++++++++++++++++++++++-------- > 1 file changed, 25 insertions(+), 8 deletions(-) > > diff --git a/include/libintl.h b/include/libintl.h > index 9a11367ec6..4b0a0e8674 100644 > --- a/include/libintl.h > +++ b/include/libintl.h > @@ -37,17 +37,34 @@ extern char *__bind_textdomain_codeset (const char *__domainname, > extern const char _libc_intl_domainname[]; > libc_hidden_proto (_libc_intl_domainname) > > -/* Define the macros `_' and `N_' for conveniently marking translatable > - strings in the libc source code. We have to make sure we get the > - correct definitions so we undefine the macros first. */ > +/* _ marks its argument, a string literal, for translation, and > + performs translation at run time if the LC_MESSAGES locale category > + has been set. The MSGID argument is extracted, added to the > + translation database, and eventually submitted to the translation > + team for processing. New translations are periodically > + incorporated into the glibc source tree as part of translation > + updates. */ OK. > +# undef _ > +# define _(msgid) __dcgettext (_libc_intl_domainname, msgid, LC_MESSAGES) > > +/* N_ marks its argument, a string literal, for translation, so that > + it is extracted and added to the translation database (similar to > + the _ macro above). It does not translate the string at run time. > + The first, primary use case for N_ is a context in which a string > + literal is required, such as an initializer. Translation will > + happen later, for example using the __gettext function. > + > + The second, historic, use case involves strings which may be > + translated in a future version of the library, but cannot be > + translated in current releases due to some technical limitation > + (e.g., gettext not being available in the dynamic loader). No > + translation at run time happens in such cases. OK up to here. This usage is > + deprecated because using N_ for strings which are not translated > + after all creates unnecessary work for the translation team: glibc > + does not currently use those translations, and that may never > + change. */ Suggest: In the future this historic usage of N_ may become deprecated. Strings which are not translated create unnecessary work for the translation team. We continue to use N_ because it helps mark translatable strings. > # undef N_ > # define N_(msgid) msgid > > -# undef _ > -/* This is defined as an optimizing macro, so use it. */ > -# define _(msgid) \ > - __dcgettext (_libc_intl_domainname, msgid, LC_MESSAGES) > - > # endif /* !_ISOMAC */ > #endif >
* Carlos O'Donell: > On 5/6/20 5:23 AM, Florian Weimer wrote: >> ----- >> Tested by building glibc on x86_64-linux-gnu. >> > > Please post v2 for review. >> + deprecated because using N_ for strings which are not translated >> + after all creates unnecessary work for the translation team: glibc >> + does not currently use those translations, and that may never >> + change. */ > > Suggest: > > In the future this historic usage of N_ may become deprecated. Strings > which are not translated create unnecessary work for the translation > team. We continue to use N_ because it helps mark translatable strings. Thanks, v2 posted: <https://sourceware.org/pipermail/libc-alpha/2020-May/113667.html>
diff --git a/include/libintl.h b/include/libintl.h index 9a11367ec6..4b0a0e8674 100644 --- a/include/libintl.h +++ b/include/libintl.h @@ -37,17 +37,34 @@ extern char *__bind_textdomain_codeset (const char *__domainname, extern const char _libc_intl_domainname[]; libc_hidden_proto (_libc_intl_domainname) -/* Define the macros `_' and `N_' for conveniently marking translatable - strings in the libc source code. We have to make sure we get the - correct definitions so we undefine the macros first. */ +/* _ marks its argument, a string literal, for translation, and + performs translation at run time if the LC_MESSAGES locale category + has been set. The MSGID argument is extracted, added to the + translation database, and eventually submitted to the translation + team for processing. New translations are periodically + incorporated into the glibc source tree as part of translation + updates. */ +# undef _ +# define _(msgid) __dcgettext (_libc_intl_domainname, msgid, LC_MESSAGES) +/* N_ marks its argument, a string literal, for translation, so that + it is extracted and added to the translation database (similar to + the _ macro above). It does not translate the string at run time. + The first, primary use case for N_ is a context in which a string + literal is required, such as an initializer. Translation will + happen later, for example using the __gettext function. + + The second, historic, use case involves strings which may be + translated in a future version of the library, but cannot be + translated in current releases due to some technical limitation + (e.g., gettext not being available in the dynamic loader). No + translation at run time happens in such cases. This usage is + deprecated because using N_ for strings which are not translated + after all creates unnecessary work for the translation team: glibc + does not currently use those translations, and that may never + change. */ # undef N_ # define N_(msgid) msgid -# undef _ -/* This is defined as an optimizing macro, so use it. */ -# define _(msgid) \ - __dcgettext (_libc_intl_domainname, msgid, LC_MESSAGES) - # endif /* !_ISOMAC */ #endif