diff mbox series

ABOUT-GCC-NLS: add usage guidance

Message ID 20231019151130.1929663-1-jason@redhat.com
State Accepted
Headers
Series ABOUT-GCC-NLS: add usage guidance |

Checks

Context Check Description
snail/gcc-patch-check success Github commit url

Commit Message

Jason Merrill Oct. 19, 2023, 3:11 p.m. UTC 
  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(+)


base-commit: faa0e82b409362ba022f6872cea9677e9dd42f0c

Comments

Jakub Jelinek Oct. 19, 2023, 3:21 p.m. UTC | #1 
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
Jason Merrill Oct. 19, 2023, 4:13 p.m. UTC | #2 
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
Jakub Jelinek Oct. 19, 2023, 4:17 p.m. UTC | #3 
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 mbox series

Patch

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