XLIFF 1.1 Representation Guide for Gettext PO

The msgid and msgstr contains the source and target string of a translation unit.

The actual content of msgid and msgstr is a concatenation of the strings enclosed by quotes (U+0022 characters) on each line. For example:

msgid ""
"My name is "
""
"%s. \n"
"What is"
" "
"your name?"

is exactly the same as:

msgid "My name is %s. \nWhat is your name?"

# This is a comment line
# This is another comment line

Translator comments are lines starting with "# " (U+0023 + U+0020). These comments are added by translators, and are not present in POT files.

#. This is an extracted comment
#. This is another extracted comment

Extracted comments are lines starting with "#." (U+0023 + U+002E). These comments are extracted from the source code. Source-code comments are normally extracted if they are on the same line as the source string, or on the line immediately preceding it, as in the following c-example:

/* This comment will be extracted */
gettext("Hello World");

This would become:

#. This comment will be extracted 
msgid "Hello World"
msgstr ""

When updating a PO file from a new POT file, existing extracted comments in the language specific PO file are discarded, and the extracted comments present in the POT file are inserted in the existing PO file.

#: myfile.c:1 myfile.c:23 otherfile.c:1
#: otherfile.c:34

References are identified by lines starting with "#:" (U+0023 + U+003A). References are space separated lists of locations (sourcefile:linenumber) specifying where the translation unit is found in a source file.

As each msgid has to be unique within a PO domain, a single translation unit can contain multiple references; one for each location where the string is found in the source code.

Similar to extracted comments, when updating a PO file from a new POT file, existing references in the language specific PO file are discarded, and the references present in the POT file are inserted in the existing PO file.

Flags are identified by lines starting with "#," (U+0023 + U+002C). Multiple flags are separated by commas.

Flags are used both as processing instructions by the Gettext tools, and by translators to indicate that a translation unit is unfinished or "fuzzy".

Flags (except fuzzy) are inserted and overridden by developers in source code, by adding them to a comment immediately preceding the call to gettext, as in the following example:

/* xgettext:no-c-format */
printf(_("Hello World"));

Since the Gettext call here is inside a printf function call, the gettext tools will automatically assume this is a c-format string. But in this example the developer overrides that, and specifies it is not so, which would generate the following PO translation unit:

#, no-c-format
msgid "Hello World"
msgstr ""

Gettext, in addition to supporting normal translation units with a single msgid and msgstr, support plural form translation units. These translation units contain the singular English form in the msgid field, and the plural form in the msgid_plural. As the target, these translation units have an array of msgstr, representing the number of forms in the target language:

msgid "You have %d file"
msgid_plural "You have %d files"
msgstr[0] "Du har %d fil"
msgstr[1] "Du har %d filer"

The target language may have one or more forms (Japanese has one form, while Polish has 3 forms), and the logic for selecting which form to use for a parameter is defined in a PO header field, where nplurals defines the number of forms and plural contains a c-expression for evaluating which item in the msgstr array to use at run time:

"Plural-Forms: nplurals=2; plural=(n != 1);\n"

This is a typical example for a Germanic language, which has a special case when n is 1. A more complex example is Polish, which has special cases for when n is 1, and in addition some numbers ending in 2, 3 or 4:

"Plural-Forms: nplurals=3; "
"plural=n==1 ? 0 : n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;"

C-expressions are defined as condition ? true_value : false_value where condition is an expression evaluating to true/false. In the above example, the first condition is n==1 which if true gives the result 0, and if false gives the result of a second c-expression. For the second expression, the condition is n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20), which if true gives the result 1, and if false gives the result 2. At run time, Gettext will use the msgstr with the index returned from this expression.

Obsolete entries are translation units that are no longer present in the source-files, and are therefore commented out when a PO file is updated. These entries are re-used by Gettext only if the translation-unit re-appears in the project, and are also used for fuzzy matching by the 'msgmerge' tool. Obsolete entries are marked with "#~" (U+0023 + U+007E), as in the following example:

#  This is a translator comment
#~ msgid ""
#~ "Please enter the following details:\n"
#~ "   - First Name\n"
#~ "   - Last Name\n"
#~ msgstr ""
#~ "Venligst fyll inn følgende data:\n"
#~ "   - Fornavn\n"
#~ "   - Etternavn\n"

The information contained in the PO header is not needed in the localisation process, and can be left out of the XLIFF file.

When converting POT files, it is possible to completely ignore the PO header, as described in Section 3.6, “Extracting from POT files”.

This approach involves storing the whole PO header as a XLIFF <trans-unit> element; with the restype attribute set to x-gettext-domain-header. In PO the header is identified by a empty source field (msgid), and the header is stored in the target field (msgstr). In converting to XLIFF, we copy the value of msgstr to both <source> and <target>, ensuring that translators can modify the header without loosing track of the original content. Translator comments and the fuzzy flag is handled the same way as other translation units.

For example:

# French Translation for MyApplication.
# Copyright (C) 2005 John Developer
# This file is distributed under the same license as the MyApp package.
# John Developer <john@example.com>, 2005.
# Joe Translator <joe@example.com>, 2005.
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: MyApp 1.0\n"
"Report-Msgid-Bugs-To: MyApp List <myapp-list@example.com>\n"
"POT-Creation-Date: 2005-04-27 13:15+0900\n"
"PO-Revision-Date: 2005-04-27 13:45+0900\n"
"Last-Translator: Joe Translator <joe@example.com>\n"
"Language-Team: French Team <fr-list@example.com>\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Plural-Forms: nplurals=2; plural=(n!=1);\n"
"X-Generator: KBabel 1.9\n"

would be mapped to:

<trans-unit id="1" restype="x-gettext-domain-header" approved="no" xml:space="preserve">
  <source>Project-Id-Version: MyApp 1.0
Report-Msgid-Bugs-To: MyApp List <myapp-list@example.com>
POT-Creation-Date: 2005-04-27 13:15+0900
PO-Revision-Date: 2005-04-27 13:45+0900
Last-Translator: Joe Translator <joe@example.com>
Language-Team: French Team <fr-list@example.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Plural-Forms: nplurals=2; plural=(n!=1)
X-Generator: KBabel 1.9
</source>
  <target>Project-Id-Version: MyApp 1.0
Report-Msgid-Bugs-To: MyApp List <myapp-list@example.com>
POT-Creation-Date: 2005-04-27 13:15+0900
PO-Revision-Date: 2005-04-27 13:45+0900
Last-Translator: Joe Translator <joe@example.com>
Language-Team: French Team <fr-list@example.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Plural-Forms: nplurals=2; plural=(n!=1)
X-Generator: KBabel 1.9
</target>
  <note from="po-translator">Copyright (C) 2005 John Developer
This file is distributed under the same license as the MyApp package.
John Developer <john@example.com>, 2005.
Joe Translator <joe@example.com>, 2005.</note>
</trans-unit>

The content of the PO header can hardly be seen as translatable data, hence this approach is not fully faithful to the XLIFF specification. However, this approach is recommended as a "lesser-of-evils" approach in that it allows translators to modify PO header information - which is necessary in many Gettext based localisation processes.

Each PO entry maps to a XLIFF <trans-unit> element, and contains the source string (msgid) in the <source> element, and the translation (msgstr) in the <target> element. White space and formatting should be preserved by setting the xml:space attribute to preserve.

For example:

msgid "hello world"
msgstr "hei verden"

would be mapped to:

<trans-unit id="1" xml:space="preserve">
  <source>hello world</source>
  <target>hei verden</target>
</trans-unit>

Each plural PO entry maps to a XLIFF <group> element with the restype attribute set to x-gettext-plurals, and contains one <trans-unit> element for each plural form in the target language.

For example:

msgid "%d file deleted"
msgid_plural "%d files deleted"
msgstr[0] "%d fil slettet"
msgstr[1] "%d filer slettet"

would be mapped to:

<group restype="x-gettext-plurals">
  <trans-unit id="1[0]" xml:space="preserve">
    <source>%d file deleted</source>
    <target>%d fil slettet</target>
  </trans-unit>
  <trans-unit id="1[1]" xml:space="preserve">
    <source>%d files deleted</source>
    <target>%d filer slettet</target>
  </trans-unit>
</group>

When the target language has more than two plural forms, the plural source (msgid_plural) should be used in the <source> element for all translation units except the first.

For example:

msgid "untranslated-singular"
msgid_plural "untranslated-plural"
msgstr[0] "translated-form-0"
msgstr[1] "translated-form-0"
...
msgstr[n] "translated-form-n"

would be mapped to:

<group restype="x-gettext-plurals">
  <trans-unit id="1[0]" xml:space="preserve">
    <source>untranslated-singular</source>
    <target>translated-form-0</target>
  </trans-unit>
  <trans-unit id="1[1]" xml:space="preserve">
    <source>untranslated-plural</source>
    <target>translated-form-1</target>
  </trans-unit>
...
  <trans-unit id="1[n]" xml:space="preserve">
    <source>untranslated-plural</source>
    <target>translated-form-n</target>
  </trans-unit>
</group>

When only one form exists for the target language (For example Japanese, Chinese, Korean), the plural group should include a second <trans-unit> element with the translate attribute set to no. This element should contain the original plural source (msgid_plural) in the <source> element, and is needed when back-converting to PO to create the msgid_plural field.

For example:

msgid "untranslated-singular"
msgid_plural "untranslated-plural"
msgstr[0] "translated-form-0"

would be mapped to:

<group restype="x-gettext-plurals">
  <trans-unit id="1[0]" xml:space="preserve">
    <source>untranslated-singular</source>
    <target>translated-form-0</target>
  </trans-unit>
  <trans-unit id="1[1]" xml:space="preserve" translate="no">
    <source>untranslated-plural</source>
  </trans-unit>
</group>

It is important to be aware of the implications of plural forms when extracting data from language neutral POT files, as described in Section 3.6, “Extracting from POT files”.

Obsolete entries should not be included in the XLIFF file, and can be stored in a skeleton or ignored.

The fuzzy flag in PO maps to the approved attribute of a <trans-unit> element in XLIFF. The approved attribute is set to no if the fuzzy flag is present, and is set to yes if the flag is absent.

For example:

#, fuzzy
msgid "Hello world"
msgstr ""

msgid "Hello world!"
msgstr "Hei verden!"

should be mapped to:

<trans-unit id="1" approved="no">
  <source>hello world</source>
</trans-unit>
<trans-unit id="2" approved="yes">
  <source>Hello world!</source>
  <target>Hei Verden!</target>
</trans-unit>

If the msgstr field is empty and the fuzzy flag is absent, the translation unit is still marked as not approved. When the msgstr field contains data and the fuzzy flag is set, the state attribute of the <target> element is set to needs-review-translation.

For example:

msgid "Hello world"
msgstr ""

#, fuzzy
msgid "Hello world!"
msgstr "Hei verden!"

should be mapped to:

<trans-unit id="1" approved="no">
  <source>hello world</source>
</trans-unit>
<trans-unit id="2" approved="no">
  <source>Hello world!</source>
  <target state="needs-review-translation">Hei Verden!</target>
</trans-unit>

When back-converting to PO, the fuzzy flag is set unless the approved attribute of the translation unit is set to yes.

The no-wrap flag only controls the visual layout of a translation unit in the PO file, and not the actual content. Hence, this flag has no meaning in an XLIFF file and can be ignored by filters.

Note that it is possible, when back-converting to PO, to honour the no-wrap flag. This can be done by implementing the same formatting rules as the Gettext tools:

For example:

<trans-unit id="1" approved="yes">
  <source>As prompted on the following screen, please enter the following details:
   - First Name
   - Last Name
</source>
  <target>Venligst fyll inn følgende data når du kommer til neste skjermbilde:
   - Fornavn
   - Etternavn
</target>
</trans-unit>

would when back-converted be formatted as:

msgid ""
"As prompted on the following screen, please enter the following details:\n"
"   - First Name\n"
"   - Last Name\n"
msgstr ""
"Venligst fyll inn følgende data når du kommer til neste skjermbilde:\n"
"   - Fornavn\n"
"   - Etternavn\n"

in favour of word-wrapping similar to this:

msgid "As prompted on the following screen, please enter "
"the following details:\n"
"   - First Name\n"
"   - Last Name\n"
msgstr "Venligst fyll inn følgende data når du kommer til "
"neste skjermbilde:\n"
"   - Fornavn\n"
"   - Etternavn\n"

How the no-wrap flag is stored (if it is honoured) in the localisation process, is up to the individual filter implementers.

The X-format flag (For example: c-format, java-format, php-format) specifies that the Gettext is to do some format checks before accepting the translation, ensuring that the parameters present in the source string (msgid) is there in the translated entry (msgstr). This format check is done by the Gettext tools after translation, when generating MO files, or when merging a PO file with a newly extracted POT file.

This flag can be honoured by extracting parameters to <ph> elements with the c-type attribute set to the value mapping to the format flag (see the table below). For example:

#, c-format
msgid "Hello %s, your score is %d."
msgstr "Hei %s, du har %d poeng."

Here the parameters %s and %d can be extracted:

<trans-unit id="1" approved="yes">
  <source>Hello <ph id="1" ctype="x-c-param">%s</ph>, your score is <ph id="2" ctype="x-c-param">%d</ph>.</source>
  <target>Hei <ph id="1" ctype="x-c-param">%s</ph>, du har <ph id="2" ctype="x-c-param">%d</ph> poeng.</target>
</trans-unit>

For some source formats special consideration is needed when reordering parameters. For example:

Hello %s, your score is %d.

If we here in the target language wanted to write:

Score: %d. Name: %s

we would have to specify the position of the parameters:

Score is %2$d for %1$s

Most XLIFF editors does not provide a way for translators to edit the content of the <ph> elements, meaning this logic would have to be implemented in the filters.

For example, in the following PO fragment:

#, c-format
msgid "Hello %s, your score is %d."
msgstr ""

the extraction filter could insert necessary ordering-tags when converting to XLIFF:

<trans-unit id="1" approved="no">
  <source>Hello <ph id="1" ctype="x-c-param">%1$s</ph>, your score is <ph id="2" ctype="x-c-param">%2$d</ph>.</source>
</trans-unit>

The translator could then safely re-order the parameters:

<trans-unit id="1" approved="yes">
  <source>Hello <ph id="1" ctype="x-c-param">%1$s</ph>, your score is <ph id="2" ctype="x-c-param">%2$d</ph>.</source>
  <target>Score is <ph id="2" ctype="x-c-param">%2$d</ph> for <ph id="1" ctype="x-c-param">%1$s</ph>.</target>
</trans-unit>

and the back converted PO file would then become:

#, c-format
msgid "Hello %s, your score is %d."
msgstr "Score is %2$d for %1$s"

Take note that the the parameters in msgid are replaced with the original parameters on back-conversion.

It is recommended to implement support for extracting parameters only if support for parameter re-ordering is also implemented.

no-X-format (For example: no-c-format, no-php-format) flags can be ignored as they have no functional use and are ignored by the Gettext tools. These flags are added by developers in source code to override the automatic insertion of x-format flags.