File: gettext.info,  Node: Translator advice,  Next: c-format Flag,  Prev: Marking,  Up: Sources

4.6 Adding advice for translators
=================================

   Sometimes you might want to add advice for the translators to a
particular message.  For example:
   • The translatable string might be decent English but nevertheless
     ambiguous.
   • The translatable string refers to something in English culture
     (such as a film's name) that is different in other cultures.
   • The translator should make an adjustment that is specific to her
     locale.

   The way to do this is to add comments, before the ‘gettext’
invocation or inside the ‘gettext’ invocation but before the string,
that start with the substring ‘TRANSLATORS:’.  These comments will be
extracted into the POT file, so that translators can see them.  For
example, when you write

     /* TRANSLATORS: This is an English idiom,
        meaning not to reveal a secret. */
     puts (gettext ("Don't spill the beans!"));

the POT file will contain:

     #. TRANSLATORS: This is an English idiom,
     #. meaning not to reveal a secret.
     #: source.c:213
     msgid "Don't spill the beans!"
     msgstr ""

and the translators will be shown the advice in a particular place in
their translation tool.

   Only comments that immediately precede the ‘gettext’ invocation or
the translatable string are considered.  Intervening blank lines are OK,
but if there is other code between the comment and the translatable
string, the comment no longer applies.

   Note: The string ‘TRANSLATORS:’ is a convention, enabled by the
‘Makefile.in.in’ file that is part of a package's build system.  It is
not enabled by default in ‘xgettext’.  If you are using ‘xgettext’
without the ‘Makefile.in.in’ infrastructure, you will need to pass the
option ‘--add-comments=TRANSLATORS:’ yourself.