Gettext

Translate PO target values while preserving message context, source identity, and the limits of plural reconstruction.

Gettext keeps source wording and translated wording in the same entry. The po file handler reads msgid and writes the translation to msgstr, leaving the source in place. It also uses msgctxt to distinguish identical words used in different situations.

Context distinguishes messages #

For example, these entries can receive different translations of “Back”:

text
msgctxt "checkout navigation"
msgid "Back"
msgstr ""

msgctxt "product surface"
msgid "Back"
msgstr ""

These are separate units despite their identical msgid. The context is also supplied as a translation hint. Comment and flag lines are retained with entries, but preserving them does not establish that every comment is interpreted as an instruction or that review flags are updated.

The focused parser covers supported quoted PO fields and continuation lines. Use UTF-8 inputs; it does not convert arbitrary legacy encodings. Automatic .pot discovery is outside the CLI's .po inference contract.

Plural reconstruction has limits #

For a plural entry, msgid and msgid_plural become separate singular and plural text units. The handler writes as many target slots as the output header's Plural-Forms field sets in nplurals, and never fewer than two or fewer than the existing target already has. Slots beyond the first two receive the plural value rather than independently generated forms. Unchanged entries keep the accepted forms they already have. A catalog with plural entries is rejected when nplurals is not an integer from 1 to 6.

Review plural output before compiling it. A language requiring several distinct forms needs the correct wording in each slot and a matching Plural-Forms header. Existing target headers are preferred; on a first output, the source header carries forward with Language changed to the target locale. The handler does not rewrite Plural-Forms for the target language.

Updates and serialization #

The previous source identifies changes by context, message identity, and singular/plural unit. Existing target entries supply retained msgstr values. Changing source identity can make a message new even when its accepted target wording would still be useful.

Reconstruction retains source fields, comment lines, and surrounding entry layout while replacing msgstr values and the relevant header. Quoted translation values can be reformatted. Validate message counts and plural metadata in addition to parsing the file.

Configure and compile the catalog #

The CLI infers po from .po. Select source catalogs through CLI configuration or GitHub.

Compile or import the output using the application's Gettext tooling, then exercise plural quantities and context-specific lookup. Inspect repeated plural values and headers even when parsing succeeds: they determine what the application displays for each quantity.