Use comments

Gettext has a nice and very useful feature where any comments in the source code that are immediately preceding a message marked for translation, are being automatically picked up and displayed as comment in the .po file next to the message in question. The gettext manual calls them extracted comments.

For comments to be extracted by xgettext, they have to be on the line right before the first opening quotes of the string. See the xgettext manual, more specifically the --add-comments[=tag] option, for examples of what works and what doesn’t, especially if you need to use line breaks.

Below are further examples, for various languages.

C / C++ files

Below is a code example from line 42 in a file called foo.c:

   /* This is the verb, not the noun */
   g_printf (_("Profile"));

This will automatically turn into this in the .pot and .po files:

   #. This is the verb, not the noun
   #: foo.c:42
   msgid "Profile"
   msgstr ""

Gettext will pick up multi-line comments as well.

As you can see, this feature can be very useful for providing additional and sometimes very much necessary information for translators, so that the message can be translated correctly. As gettext automatically picks up all comments that happen to be immediately preceding a message and places them next to the messages in the pot and po files this way, the comments that are actually intended for translators can be difficult to distinguish sometimes. Thus, making them explicitly address translators usually helps in catching the translators' notice:

   /* Translators: This is the verb, not the noun */
   g_printf (_("Profile"));

Glade / GTKBuilder files

To receive the same results for a Glade or GTKBuilder file, add the "comments" parameter to the markup item:

   <property name="label" translatable="yes" comments="Translators: This is the verb, not the noun">Profile</property>

Note that the order of attributes matters. translatable should come before comments.

GSettings schema files

In .gschema files, comments need to be placed before the opening tag. Example:

   <!-- Translators: This is the verb, not the noun -->
   <summary>Profile</summary>

Scheme (.scm) files

See this post.

Mallard documentation files

   <p xmlns:its="http://www.w3.org/2005/11/its" its:locNote="Translators: Comment about text to translate.">Text to translate</p>