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
+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
base-commit: faa0e82b409362ba022f6872cea9677e9dd42f0c
--
2.39.3
