From 9cf32fb039034547808a42e3d33cb67dc08023f9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ji=C5=99=C3=AD=20Kuchy=C5=88ka=20=28Anty=29?= Date: Tue, 26 May 2026 15:45:53 +0200 Subject: [PATCH 1/2] docs: document msgctxt handling in PO format page Adds a 'msgctxt and key names' section explaining how Tolgee encodes the optional gettext msgctxt field into key names using the U+0004 separator, with an example and a link to the GNU Gettext documentation on contexts. --- platform/formats/po.mdx | 36 +++++++++++++++++++++++++++++++++--- 1 file changed, 33 insertions(+), 3 deletions(-) diff --git a/platform/formats/po.mdx b/platform/formats/po.mdx index 5887660b5..7c0058798 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 + +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"; From cf49a29c2820f1079b149de908b0b293337e3704 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ji=C5=99=C3=AD=20Kuchy=C5=88ka=20=28Anty=29?= Date: Tue, 26 May 2026 16:20:16 +0200 Subject: [PATCH 2/2] docs: add explicit anchor id for msgctxt section --- platform/formats/po.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/platform/formats/po.mdx b/platform/formats/po.mdx index 7c0058798..5881bc812 100644 --- a/platform/formats/po.mdx +++ b/platform/formats/po.mdx @@ -64,7 +64,7 @@ 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 +## 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