localize.dev

Docs / Translate / gettext .po

Translate gettext .po files

Fill in empty and fuzzy entries in Django, WordPress, PHP and Python .po files, with msgstr[n] slots from each language’s Plural-Forms and msgctxt and translator comments as context.

How it works

In gettext each language’s .po file holds its own copy of the source text, so localize-dev translate treats every file as a catalog: it fills entries whose msgstr is empty or marked fuzzy and leaves translated ones alone. Obsolete #~ entries are skipped.

Translator comments (#.) and msgctxt go to the model as context, so “Archive” on a button is translated as a verb. A new language (--locales pl) gets its own file beside an existing one, with its Language and Plural-Forms header. Compile as usual afterwards: python manage.py compilemessages for Django, msgfmt elsewhere.

Before and after

Real output of localize-dev translate --locales de,pl on the first file. The German file had two empty entries and a fuzzy one. With --locales de,pl they were filled, and the Polish file below was created with three plural slots.

locale/de/LC_MESSAGES/django.po
msgid ""
msgstr ""
"Language: de\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Plural-Forms: nplurals=2; plural=(n != 1);\n"

#. Heading on the account page
msgid "Your account"
msgstr ""

#, fuzzy
msgid "Signed in as %(email)s"
msgstr "Angemeldet als"

msgctxt "verb, on a button"
msgid "Archive"
msgstr ""

msgid "%(count)s file uploaded"
msgid_plural "%(count)s files uploaded"
msgstr[0] ""
msgstr[1] ""
locale/pl/LC_MESSAGES/django.po · Polish
msgid ""
msgstr ""
"Language: pl\n"
"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"

#. Heading on the account page
msgid "Your account"
msgstr "Twoje konto"

msgid "Signed in as %(email)s"
msgstr "Zalogowano jako %(email)s"

msgctxt "verb, on a button"
msgid "Archive"
msgstr "Archiwizuj"

msgid "%(count)s file uploaded"
msgid_plural "%(count)s files uploaded"
msgstr[0] "%(count)s plik przesłany"
msgstr[1] "%(count)s pliki przesłane"
msgstr[2] "%(count)s plików przesłanych"

What stays intact

  • %(name)s, {name} and printf placeholders, checked
  • One msgstr[n] per slot of the language’s Plural-Forms: 3 for Polish, 6 for Arabic
  • The header, translator comments and entry order
  • msgctxt, so the same msgid can be translated differently by context

Common mistakes, and how they’re avoided

Fuzzy entries left behind

gettext skips fuzzy entries when it compiles, so an outdated translation silently falls back to the source text. Fuzzy entries are translated again and the flag is cleared.

The wrong number of plural slots

A file copied from German has two msgstr[n] slots; Polish needs three. The new file’s Plural-Forms is set for its language, and each slot gets the form for the numbers that land in it.

Reordered placeholders

Unnamed %s placeholders mean something by their position. A translation that reorders them is rejected. Named ones like %(email)s can move wherever the sentence needs them.

Run it

In the folder that holds your locale files. Languages without a file yet get one. --dry-run shows what would change first.

npx localize-dev login

# Preview, then write the missing translations
npx localize-dev translate --dry-run -l es,fr,de
npx localize-dev translate -l es,fr,de

Then keep it complete in CI. This needs no API key and fails when a language is missing translations:

npx localize-dev check --only translations

Free for 1,000 strings a month. A string counts once however many languages it goes into. Create a free account

Guides for apps that use this format

When the copy is still hardcoded in your code, localize-dev run moves it into this format first.