Gettext - PO/POT

Last updated: November 28, 2024
po-pot
File format value
po-pot
List of supported file formats

PO files (Portable Object) are plain-text files used by the Gettext system for software localization and internationalization. PO file format was released initially in 1990, and it's still widely used in many Unix-like systems, and modern frameworks like Django, Ruby on Rails, WordPress, and many others.

PO files are used to store translations for a single language. They contain message ids (translation key), comments, and contexts, and translated messages. We can distinguish two different file formats:

  • POT file format (Portable Object Template) is used as a template for translating text, it does not contain translated messages, only message ids, comments, and contexts. You can treat it as a template.
  • PO file format is a translation record that contains the same values as a POT file, but it also contains translated strings for a single language.

File format example

Each translation unit consists of a message id, a message string, and optional metadata like comments, contexts, and plural forms.

msgid ""
msgstr ""
"Content-Type: text/plain; charset=UTF-8\n"
"Plural-Forms: nplurals=3; plural=(n == 1 ? 0 : (n % 10 >= 2 && n % 10 <= 4 && (n % 100 < 10 || n % 100 >= 20) ? 1 : 2));\n"
"Language: pl\n"

# Single line
msgctxt "Translation context"
msgid "Translation key"
msgstr "Translation message"

# Multiple lines
msgid ""
"The input text "
"split to several "
"lines"
msgstr ""
"Translation "
"can also be splitted."

Many PO files contain metadata at the beginning of the file, which is used to describe the file format, language, and plural forms. The metadata is stored in the form of key-value pairs, separated by colons.

In the example above, the metadata contains the following keys:

  • Content-Type - specifies the content type of the file
  • Plural-Forms - specifies the plural forms used in the file
  • Language - specifies the language of the translations

Some frameworks and tools require the metadata to be present in the file, for example, the Plural-Forms and Content-Type headers are required by the Gettext library.

Message id

The message id is the original text that needs to be translated.

msgid "Hello, world!"

Message string

The message string is the translated text that corresponds to the message id.

msgstr "Witaj, świecie!"

Context

The context is used to provide additional information about the translation. It is used to distinguish between different meanings of the same word.

msgctxt "Greeting"
msgid "Hello"
msgstr "Witaj"

Plural forms

Plural forms are used to handle different grammatical forms of the same word. The plural form is defined in the Plural-Forms header, which contains a formula that determines the correct plural form based on the number of items.

msgid "There is one apple"
msgid_plural "There are %d apples"
msgstr[0] "Jest jedno jabłko"
msgstr[1] "Są %d jabłka"
msgstr[2] "Są %d jabłek"

SimpleLocalize fills the Plural-Forms header automatically for the language for which the translations are exported.

Comments

Comments in PO files can be single-line or multi-line. They can be used to describe the context of the translation, provide additional information. Comments are prefixed with a hash sign #, #. or #:.

# This is a single-line comment
#. Translators: This message appears on the home page only
#: mysite/views.py:7
  • # - default comment
  • #. - translator comment, used to provide additional information about the message
  • #: - reference comment, used to specify the location of the message in the code

Example gettext usage

printf(gettext("Hello world! I'm %s.\n"), application_title);
printf(_("Hello world! I'm %s.\n"), application_title);

Upload with CLI

Upload source language translations to SimpleLocalize using CLI.

simplelocalize upload --apiKey PROJECT_API_KEY \
  --uploadFormat po-pot \
  --uploadLanguageKey en \
  --uploadPath ./messages_en.po

Learn more about SimpleLocalize CLI and translations upload feature.

Download with CLI

simplelocalize download --apiKey <PROJECT_KEY> \
  --downloadFormat po-pot \
  --downloadLanguageKeys pl,fr,de \
  --downloadPath ./messages_{lang}.po

Learn more about SimpleLocalize CLI and translations download feature.

References

Was this helpful?