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
