gettext and PO Localization
Localize an application that uses gettext: mark the strings, extract them into a template with xgettext, translate it in Soluling, and deploy the localized .po and .mo files.
gettext is used especially in Python, PHP, Lazarus, and Linux applications, and the process is the same in each. Soluling reads the .po or .pot file, shows plurals in a pattern editor, checks the placeholders, and writes a localized file for each language. Translate in Soluling Desktop or in a browser with Soluling Cloud. The guide follows the Python Driving sample, a small driving time calculator that runs in a console.
.mo files. Keep the .po files in your project. The output folders depend on the output pattern; see Build.- Input
- The template that
xgettextwrites (.potor.po) - Output
- Localized
.pofiles, and compiled.mofiles by default - Runtime
- gettext loads the
.mofile of the active language - Cloud
- Upload the template to Soluling Cloud directly; no desktop step needed
On this page
- Tutorial: localize a gettext application step by step
- How gettext works
- Plurals
- Fallback
- PO files that use keys as msgid
- Translate in Soluling Cloud
- Do and don't
- Troubleshooting
- Samples
- FAQ
Localize a gettext application, step by step
Six steps take the application from English only to localized language files.
Prepare: mark the strings
gettext uses the English text itself as the key. Wrap each string in gettext, which is usually shortened to _, and use ngettext for counts. The Driving sample starts like this:
import gettext
gettext.bindtextdomain('Driving', 'locale')
gettext.textdomain('Driving')
_ = gettext.gettext
print(_("Driving Time"))
textdomain names the file, and bindtextdomain says where the files are. A comment right before the string goes to the translator, if you extract with --add-comments. Describe each placeholder in it:
Extract: create the template and a Soluling project
Run xgettext, as the sample's Extract.bat does:
xgettext --from-code="UTF-8" --add-comments -d Driving Driving.py
It writes the marked strings to Driving.po, the template. With --output=Driving.pot you get the usual .pot name; Soluling reads both. Then drag and drop the file on Soluling.
- On the Options sheet, check what Soluling reads from the file, such as comments and string locations. It detects the programming language from the file.
- Select the original language and the target languages, and complete the wizard.
Translate: texts, placeholders, and plurals
Each string is a row in the grid, with the comment from xgettext. A placeholder such as {hours} or %d stays in the translation, and the translator can move it. The file has only the strings and not your user interface, so you translate in the grid, without a visual editor. See Plurals for plural messages.
- Machine translation and translation memory. Click Use Machine Translation to translate with Amazon, Claude, DeepL, Google, Microsoft, ModernMT, or MyMemory, and reuse earlier translations from translation memory and terminology.
- External translators. Send a translation package, an Excel file, or XLIFF to a translator, and import the results back. See teamwork.
- Translators in a browser. Upload the project to Soluling Cloud and let translators work in Translate.
Check: find problems before release
- Pseudo translation. Click Translate | Pseudo Translations | Fill, build, and run the application. Pseudo translations are longer and use accented characters, so texts that don't fit and strings still in the code (shown in plain English) stand out. See pseudo translation.
- Validation. Soluling validates translations while you type and in batch (Validation | Validate Translations): missing translations, inconsistent placeholders and patterns, duplicate hotkeys, and more. See validation.
Build: create the PO and MO files
Choose Home | Build All. Soluling writes a localized .po file for each language, with the language and the plural rule in its header, and by default compiles it into a .mo file. You don't need the gettext tools for this. If you set the gettext tools directory in the gettext options, Soluling compiles with msgfmt. The write options control compiling and the byte order.
The output pattern says where the files go. Python and PHP use the folder layout that gettext looks for, and other programming languages use a language code in the file name:
<leg>\LC_MESSAGES\<body>.po.Update: translate only what changed
When the application changes, run xgettext again and click Home | Scan. Soluling keeps the existing translations and adds the new strings. The text is the key, so a changed text is a new row that needs a translation. Translate the new rows and build. Add the extract, scan, and build steps to your build pipeline with SoluMake or, with Soluling Cloud, SoluCLI.
Three file types: POT, PO, and MO
A .pot file is the template with the original strings. A .po file has the translations of one language, and a .mo file is its compiled binary version, which gettext reads at runtime. Each entry has the string in msgid and the translation in msgstr, with comments and flags before them:
#. drivingTime: Driving time string in format of "x hours y minutes" or "x hours" or "y minutes"
#: Driving.py:29
#, python-brace-format
msgid "Driving time is{drivingTime}"
msgstr "Ajoaika on{drivingTime}"
#. is the comment from the code, #: the location, and #, the format of the placeholders. The empty msgid at the start of the file is the header, with the language, the character set, and the plural rule.
Plurals
ngettext takes the English singular and plural and the count. A .po file has one msgstr for each plural form of the language, so the number of forms depends on the target language. Soluling shows the forms each language needs, and writes that number of them to the localized file:
See the Samples\PO\Plural sample and patterns.
Fallback
gettext gets the language from environment variables, such as LANGUAGE, which the sample's Run.bat sets. If a language has a region, gettext also tries it without the region. If there is no file or no translation, it returns the msgid, so the application shows English.
PO files that use keys as msgid
Some projects use a key as the msgid and keep the English text in msgstr. On the Options sheet, set Original value to msgstr, so that translators see the English text. If msgstr is empty, Soluling uses the msgid.
Translate in Soluling Cloud
With Soluling Cloud, translators use Translate in a browser. How you start depends on what you localize:
- PO and POT files. On the dashboard, add a project, select the template, and choose gettext/po file (.po, .pot) as the source type. Translators work in Translate; click Build localized files, and save each download where your application expects it. Soluling Cloud gives you the
.pofiles, so compile them withmsgfmt Driving.po -o Driving.mo. When the application changes, runxgettextand upload the new template; the existing translations are kept. No desktop step is needed.
To run the scan, upload, import, and build steps in your build pipeline, use SoluMake. See the Cloud tutorial and workflows.
Do and don't
Do
- Wrap every string the user sees in
gettextor_. - Use
ngettextfor counts. - Describe placeholders in comments, and extract with
--add-comments. - Use UTF-8, so that every language fits in one character set.
- Deploy the
.mofiles with the application. - Pseudo-translate before the first real translation.
Don't
- Pass a variable to
gettext;xgettextcan't read it. - Choose plural forms with
ifstatements; other languages have other rules. - Edit the template by hand; extract it again instead.
- Change the original text without need; the text is the key, so the row needs a new translation.
- Forget to compile: gettext reads the
.mofile and not the.pofile.
Troubleshooting
| Symptom | Likely cause | What to do |
|---|---|---|
| The application stays in English | The language isn't set, or gettext doesn't find the .mo file |
Check LANGUAGE or your application's locale, the bindtextdomain path, and the folder layout. |
| A translation doesn't show | The .mo file wasn't compiled again, or the original text has changed |
Build again, or compile with msgfmt. |
| A text is missing from the template | It isn't marked, or xgettext wasn't run |
Mark it, and run xgettext again. |
| Comments are missing in Soluling | xgettext ran without --add-comments, or reading comments is off |
Extract with the option, and check the Options sheet. |
| Files are in the wrong folder | The output pattern doesn't match what your application expects | Change it on the Output sheet of the source. |
| Characters are garbled in a console | The console doesn't use UTF-8 | The sample's Run.bat runs chcp 65001 and sets PYTHONIOENCODING. |
Samples
-
Python\Driving: the driving time calculator of this guide, with the Soluling project
Driving.ntpand Finnish translations. To try it, install Python and runRun.bat fi. See Python localization. - PO\Simple: a simple C++ source with one string, the template, and the Finnish files. These show the extraction and aren't complete applications.
- PO\Features: a multi-line string.
- PO\Plural: plural messages in Finnish and Polish.
- PHP\DrivingGetText and Lazarus\Simple: gettext in PHP and Lazarus.
The samples are in Samples of the Soluling installation and on GitHub. See gettext and PO localization in the Desktop documentation for all the details.
FAQ
xgettext to extract the strings. Soluling Desktop compiles the .mo files itself. With Soluling Cloud, compile them with msgfmt..po files, Soluling can import their translations into the project.Samples\Python\Django sample.Related
- gettext and PO localization - the full Desktop documentation
- Python, PHP, and Lazarus localization
- Patterns - plurals, genders, and selects
- Supported formats - everything else Soluling localizes