Skip to content

docs: document msgctxt handling in PO format page #1111

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Anty0 wants to merge 2 commits into
base: main
Choose a base branch
from
+33 −3
Open

docs: document msgctxt handling in PO format page #1111

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9cf32fb
docs: document msgctxt handling in PO format page
Anty0 May 26, 2026
cf49a29
docs: add explicit anchor id for msgctxt section
Anty0 May 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 33 additions & 3 deletions platform/formats/po.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,8 +49,9 @@ Tolgee converts the placeholders to the [Tolgee Universal ICU placeholders](/pla
when enabled.

## Feature support
Tolgee supports importing of basic `msgid` and `msgstr` fields, the plural `msgid_plural` and `msgstr[..]` arrays and it
imports the `extracted comments` (`#.`) as the key descriptions. No other fields are supported.
Tolgee supports importing of basic `msgid` and `msgstr` fields, the plural `msgid_plural` and `msgstr[..]` arrays,
the optional `msgctxt` (see [msgctxt and key names](#msgctxt-and-key-names) below), and it imports the
`extracted comments` (`#.`) as the key descriptions. No other fields are supported.

## The message format and placeholder conversion
import {
Expand All @@ -63,10 +64,39 @@ import {
## Exporting
When exporting the data back to the .po file, the placeholders are converted back to the original format.

## Message context (`msgctxt`) and key names {#msgctxt-and-key-names}

In Gettext, the optional `msgctxt` field disambiguates entries that share the same `msgid` but have different meanings
in different parts of an application. The pair `(msgctxt, msgid)` together identifies a single translatable entry, so
two entries with the same `msgid` but different `msgctxt` are distinct keys.

```po
msgctxt "navigation"
msgid "Open"
msgstr "Öffnen"

msgctxt "file"
msgid "Open"
msgstr "Öffnen"
```

Tolgee keys are identified by their name, so to keep both entries distinct on import, Tolgee stores the key as
`"<msgctxt>\u0004<msgid>"` — the same `EOT` separator that the GNU Gettext MO format uses internally. The platform UI
renders the `msgctxt` portion as a chip in front of the `msgid`, so a key named `"navigation\u0004Open"` is
shown as:

> `[navigation]` Open

The separator stays part of the stored key name; on export Tolgee splits it back into a real `msgctxt` line. Keys
imported without a `msgctxt` are stored as plain `msgid` and exported without the field.

For background on the `msgctxt` field itself, see the
[GNU Gettext documentation on contexts](https://www.gnu.org/software/gettext/manual/html_node/Contexts.html).

## Plural import and `msgid_plural` field
When importing the `.po` file, Tolgee always imports the `msgid` as the key. When `msgid_plural` is present, Tolgee
imports the field as a `_poFileMsgIdPlural` custom value, so it is able to export the plural of the
the same way it was imported.
same way it was imported.

import SeeCustom from "./components/_see_custom_values.mdx";

Expand Down
Loading