diff --git a/platform/formats/po.mdx b/platform/formats/po.mdx index 5887660b5..5881bc812 100644 --- a/platform/formats/po.mdx +++ b/platform/formats/po.mdx @@ -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 { @@ -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 +`"\u0004"` — 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";