Editing Gettext (section)

==Operation==

===Programming===
[[File:Gettext.svg|thumb|Typical gettext workflow.  The de.po instance on the left shows a "renewing" of translations via msgmerge.]]
The basic interface of gettext is the {{code|gettext(const char*)}} function, which accepts a [[string (computer science)|string]] that the user will see in the original language, usually English. To save typing time and reduce code clutter, this function is commonly [[aliasing (computing)|aliased]] to <code>_</code>:<ref>{{Cite web |date= |title=GNU gettext utilities: How Marks Appear in Sources |url=https://www.gnu.org/software/gettext/manual/gettext.html#How-Marks-Appear-in-Sources |url-status=live |archive-url=https://web.archive.org/web/20240325095308/https://www.gnu.org/software/gettext/manual/gettext.html#How-Marks-Appear-in-Sources |archive-date=2024-03-25 |access-date=2024-04-03 |website=www.gnu.org}}</ref>

<syntaxhighlight lang="C">
printf(gettext("My name is %s.\n"), my_name);
printf(_("My name is %s.\n"), my_name); // same, but shorter
</syntaxhighlight>

<code>gettext()</code> then uses the supplied strings as keys for looking up translations, and will return the original string when no translation is available. This is in contrast to [[POSIX]] <code>catgets()</code>,<ref>{{cite web|url=https://www.gnu.org/software/gettext/manual/html_node/catgets.html |website=gnu.org |title=About catgets |access-date=2017-10-24}}</ref> [[AmigaOS]] <code>GetString()</code>,<ref>{{Cite web |title=AmigaOS Manual: Python Modules and Packages - AmigaOS Documentation Wiki |url=https://wiki.amigaos.net/wiki/AmigaOS_Manual:_Python_Modules_and_Packages#GetString.28.29 |access-date=2023-07-09 |website=wiki.amigaos.net}}</ref> or [[Microsoft Windows]] <code>LoadString()</code>  where a programmatic ID (often an integer) is used. To handle the case where the same original-language text can have different meanings, gettext has functions like <code>cgettext()</code> that accept an additional "context" string.

<code>xgettext</code> is run on the sources to produce a <code>.pot</code> (Portable Object Template) file, which contains a list of all the translatable strings extracted from the sources. Comments starting with <code>///</code> are used to give translators hints, although other prefixes are also configurable to further limit the scope. One such common prefix is <code>TRANSLATORS:</code>.

For example, an input file with a comment might look like:

<syntaxhighlight lang="C">
/// TRANSLATORS: %s contains the user's name as specified in Preferences
printf(_("My name is %s.\n"), my_name);
</syntaxhighlight>

<code>xgettext</code> is run using the command:

 xgettext -c /

The resultant .pot file looks like this with the comment (note that xgettext recognizes the string as a [[C (programming language)|C]]-language [[printf]] format string):
<syntaxhighlight lang="po">
#. TRANSLATORS: %s contains the user's name as specified in Preferences
#, c-format
#: src/name.c:36
msgid "My name is %s.\n"
msgstr ""
</syntaxhighlight>

In POSIX [[shell script]], gettext provides a <code>gettext.sh</code> library one can include that provides the many same functions gettext provides in similar languages.<ref>{{cite web |title=GNU gettext utilities: sh |url=https://www.gnu.org/software/gettext/manual/html_node/sh.html}}</ref> [[GNU bash]] also has a simplified construct <code>$"msgid"</code> for the simple gettext function, although it depends on the C library to provide a <code>gettext()</code> function.<ref>{{cite web |title=GNU gettext utilities: bash |url=https://www.gnu.org/software/gettext/manual/html_node/bash.html}}</ref>

===Translating===
The translator derives a <code>.po</code> (Portable Object) file from the template using the <code>msginit</code> program, then fills out the translations.<ref name=msginit>{{cite web|url=https://www.gnu.org/savannah-checkouts/gnu/gettext/manual/html_node/PO-Files.html |title=GNU gettext utilities: PO Files |website=Gnu.org |access-date=2016-04-03}}</ref> <code>msginit</code> initializes the translations so, for instance, for a French language translation, the command to run would be:<ref name=":0">{{cite web|url=http://www.icanlocalize.com/site/tutorials/how-to-translate-with-gettext-po-and-pot-files/ |title=How to Translate With GetText PO and POT Files |website=Icanlocalize.com |access-date=2016-04-03}}</ref>

 msginit --locale=fr --input=name.pot

This will create <code>fr.po</code>. The translator then edits the resultant file, either by hand or with a translation tool like [[Poedit]], or [[Emacs]] with its editing mode for <code>.po</code> files. An edited entry will look like:
<syntaxhighlight lang="po">
#: src/name.c:36
msgid "My name is %s.\n"
msgstr "Je m'appelle %s.\n"
</syntaxhighlight>

Finally, the .po files are compiled with <code>msgfmt</code> into binary <code>.mo</code> (Machine Object) files.  GNU gettext may use its own file name extension <code>.gmo</code> on systems with another gettext implementation.<ref>{{cite web | url=https://www.gnu.org/software/gettext/manual/html_node/Files.html | title=Files Conveying Translations|website=Gnu.org | access-date=2014-04-22}}</ref> These are now ready for distribution with the software package.

GNU <code>msgfmt</code> can also perform some checks relevant to the [[format string]] used by the programming language. It also allows for outputting to language-specific formats other than MO;<ref>{{cite web |title=msgfmt Invocation |url=https://www.gnu.org/software/gettext/manual/html_node/msgfmt-Invocation.html |website=GNU gettext utilities}}</ref> the [[X/Open]] equivalent is <code>gencat</code>.

In later phases of the developmental workflow, <code>msgmerge</code> can be used to "update" an old translation to a newer template. There is also <code>msgunfmt</code> for reverse-compiling <code>.mo</code> files, and many other utilities for batch processing.

===Running===
The user, on [[Unix]]-type systems, sets the [[environment variable]] <code>LC_MESSAGES</code>, and the program will display strings in the selected language, if there is an <code>.mo</code> file for it.

Users on [[GNU variants]] can also use the environment variable <code>LANGUAGE</code> instead. Its main difference from the Unix variable is that it supports multiple languages, separated with a colon, for fallback.<ref>{{cite web|url=https://www.gnu.org/software/gettext/manual/html_node/Locale-Environment-Variables.html#Locale-Environment-Variables |title=GNU gettext utilities: Locale Environment Variables |website=Gnu.org |access-date=2016-04-03}}</ref>