| Message ID | 20231019151130.1929663-1-jason@redhat.com |
|---|---|
| State | New |
| Headers | show |
| Series | ABOUT-GCC-NLS: add usage guidance | expand |
On Thu, Oct 19, 2023 at 11:11:30AM -0400, Jason Merrill wrote: > A recent question led me to look at this file again, and it occurred to me that > it could use to offer more guidance. OK for trunk? > > -- 8< -- > > gcc/ChangeLog: > > * ABOUT-GCC-NLS: Add usage guidance. > --- > gcc/ABOUT-GCC-NLS | 13 +++++++++++++ > 1 file changed, 13 insertions(+) > > diff --git a/gcc/ABOUT-GCC-NLS b/gcc/ABOUT-GCC-NLS > index e90a67144e3..4c8b94d0811 100644 > --- a/gcc/ABOUT-GCC-NLS > +++ b/gcc/ABOUT-GCC-NLS > @@ -23,6 +23,19 @@ For example, GCC source code should not contain calls like `error > ("unterminated comment")' instead, as it is the `error' function's > responsibility to translate the message before the user sees it. > > +In general, use no markup for strings that are the immediate format string > +argument of a diagnostic function. Use G_("str") for strings that will be > +used as the format string for a diagnostic but are e.g. assigned to a > +variable first. Use N_("str") for other strings, particularly in a > +statically allocated array, that will be translated later by > +e.g. _(msgs[idx]). Use _("str") for strings that will not be translated The difference between G_ and N_ is whether they are GCC internal diagnostic format strings or printf family format strings (gcc-internal-format vs. c-format in po/gcc.pot), not anything else, so G_ can be used in statically allocated array as well and both for diagnostic routines and printf* family when translation is desirable it is eventually translated through _() or other gettext invocations, either inside of diagnostics.cc or elsewhere. So, the note about statically allocated array should move to G_ as well, and N_ should be described as similarly, but for strings which after translation are passed to printf family functions or so. ANd the translated later by e.g. note should be again for both and said that it is done automatically for GCC diagnostic routines. Jakub
On 10/19/23 11:21, Jakub Jelinek wrote: > On Thu, Oct 19, 2023 at 11:11:30AM -0400, Jason Merrill wrote: >> A recent question led me to look at this file again, and it occurred to me that >> it could use to offer more guidance. OK for trunk? >> >> -- 8< -- >> >> gcc/ChangeLog: >> >> * ABOUT-GCC-NLS: Add usage guidance. >> --- >> gcc/ABOUT-GCC-NLS | 13 +++++++++++++ >> 1 file changed, 13 insertions(+) >> >> diff --git a/gcc/ABOUT-GCC-NLS b/gcc/ABOUT-GCC-NLS >> index e90a67144e3..4c8b94d0811 100644 >> --- a/gcc/ABOUT-GCC-NLS >> +++ b/gcc/ABOUT-GCC-NLS >> @@ -23,6 +23,19 @@ For example, GCC source code should not contain calls like `error >> ("unterminated comment")' instead, as it is the `error' function's >> responsibility to translate the message before the user sees it. >> >> +In general, use no markup for strings that are the immediate format string >> +argument of a diagnostic function. Use G_("str") for strings that will be >> +used as the format string for a diagnostic but are e.g. assigned to a >> +variable first. Use N_("str") for other strings, particularly in a >> +statically allocated array, that will be translated later by >> +e.g. _(msgs[idx]). Use _("str") for strings that will not be translated > > The difference between G_ and N_ is whether they are GCC internal diagnostic > format strings or printf family format strings (gcc-internal-format vs. > c-format in po/gcc.pot), not anything else, so G_ can be used in statically > allocated array as well and both for diagnostic routines and printf* family > when translation is desirable it is eventually translated through _() or > other gettext invocations, either inside of diagnostics.cc or elsewhere. > So, the note about statically allocated array should move to G_ as well, and > N_ should be described as similarly, but for strings which after translation > are passed to printf family functions or so. ANd the translated later by > e.g. note should be again for both and said that it is done automatically > for GCC diagnostic routines. How about this? In general, use no markup for strings that are the immediate format string argument of a diagnostic function. Use G_("str") for strings that will be used as the format string for a diagnostic but are e.g. assigned to a variable first. Use N_("str") for strings that are not diagnostic format strings, but will still be translated later. Use _("str") for strings that will not be translated elsewhere. It's important not to use _("str") in the initializer of a statically allocated variable; use one of the others instead and make sure that uses of that variable translate the string, whether directly with _(msg) or by passing it to a diagnostic or other function that performs the translation. Jason
On Thu, Oct 19, 2023 at 12:13:55PM -0400, Jason Merrill wrote: > How about this? > > In general, use no markup for strings that are the immediate format string > argument of a diagnostic function. Use G_("str") for strings that will be > used as the format string for a diagnostic but are e.g. assigned to a > variable first. Use N_("str") for strings that are not diagnostic format > strings, but will still be translated later. Use _("str") for strings that > will not be translated elsewhere. It's important not to use _("str") in > the initializer of a statically allocated variable; use one of the others > instead and make sure that uses of that variable translate the string, > whether directly with _(msg) or by passing it to a diagnostic or other > function that performs the translation. LGTM. Jakub
diff --git a/gcc/ABOUT-GCC-NLS b/gcc/ABOUT-GCC-NLS index e90a67144e3..4c8b94d0811 100644 --- a/gcc/ABOUT-GCC-NLS +++ b/gcc/ABOUT-GCC-NLS @@ -23,6 +23,19 @@ For example, GCC source code should not contain calls like `error ("unterminated comment")' instead, as it is the `error' function's responsibility to translate the message before the user sees it. +In general, use no markup for strings that are the immediate format string +argument of a diagnostic function. Use G_("str") for strings that will be +used as the format string for a diagnostic but are e.g. assigned to a +variable first. Use N_("str") for other strings, particularly in a +statically allocated array, that will be translated later by +e.g. _(msgs[idx]). Use _("str") for strings that will not be translated +elsewhere. + +Avoid using %s to compose a diagnostic message from multiple translateable +strings; instead, write out the full diagnostic message for each variant. +Only use %s for message components that do not need translation, such as +keywords. + By convention, any function parameter in the GCC sources whose name ends in `msgid' is expected to be a message requiring translation. If the parameter name ends with `gmsgid', it is assumed to be a GCC