docs: document msgctxt handling in PO format page#1111
Merged
Conversation
✅ Deploy Preview for tolgee-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
This was referenced May 26, 2026
Anty0
added a commit
to tolgee/tolgee-js
that referenced
this pull request
May 27, 2026
## Summary - The in-context **KeyDialog** and the **ScreenshotWithLabels** tooltip now use a new `<KeyName>` component that splits the key name on the U+0004 separator (set by tolgee-platform when importing gettext `.po` files with a `msgctxt`) and renders the `msgctxt` portion as a styled chip in front of the `msgid`. - Standalone implementation — no runtime dependency on `@tginternal/editor` to keep this package's bundle independent of release coordination. - The platform-side change introducing the separator and the matching chip visual lives in the companion tolgee-platform PR. ## Companion PRs - tolgee-platform: tolgee/tolgee-platform#3694 - editor: tolgee/editor#8 - documentation: tolgee/documentation#1111 <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **New Features** * Added improved key name rendering with enhanced formatting that visually distinguishes embedded metadata using dedicated styling * Updated the UI across dialogs and tooltips to consistently leverage the new key name display, improving visual clarity and presentation when viewing keys with associated metadata <!-- review_stack_entry_start --> [](https://app.coderabbit.ai/change-stack/tolgee/tolgee-js/pull/3523?utm_source=github_walkthrough&utm_medium=github&utm_campaign=change_stack) <!-- review_stack_entry_end --> <!-- end of auto-generated comment: release notes by coderabbit.ai -->
Barush
approved these changes
May 31, 2026
Comment on lines
+52
to
+54
| 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. |
Member
There was a problem hiding this comment.
Toto by možná mohl být list? Je to trochu messy na čtení ve větě.
Member
Author
There was a problem hiding this comment.
Fixed. Is it better like this? ^^
JanCizmar
pushed a commit
to tolgee/tolgee-platform
that referenced
this pull request
Jun 3, 2026
Supersedes #3459 Fixes #3053 ## Summary - **Import:** the PO parser now captures the optional `msgctxt` field. On import, Tolgee stores the pair `(msgctxt, msgid)` as a single key name using the U+0004 EOT separator — the same convention GNU Gettext uses internally in MO files — so two entries with the same `msgid` but different `msgctxt` remain distinct keys. - **Export:** the PO exporter splits the key name on U+0004 and writes the `msgctxt` line back before `msgid`. Plural fallback now uses the split `msgid` instead of the raw key name. - **Parser cleanup:** header detection now requires both `msgid` and `msgctxt` to be empty, so a malformed msgctxt-only entry can't be misread as the header block. The legacy `PO_MSGCTXT_NOT_SUPPORTED` file issue is no longer emitted (the enum value stays in place for back-compat with previously stored issues). - **UI display:** a new `<KeyName>` component renders the `msgctxt` portion as a styled chip in front of the `msgid` across all key-name display sites (translations grid, simple/list view, single-key page breadcrumb, activity log, import dialogs, translation-memory rows and tooltips, branching/merge header, screenshot label tooltips). The window title intentionally still shows the raw key — the chip cannot render in a `document.title` string. - **UI edit:** the `<Editor>` component gains a `keyName` mode that wires a new CodeMirror plugin (`KeyNamePlugin` from `@tginternal/editor`) decorating the U+0004 with an atomic widget. Display and edit are now visually identical — the previous substitution-based workaround (`keyNameForEditing`/`keyNameFromEdited` + `␄` visible-char) is removed. - **Vite config:** added `@codemirror/state`, `@codemirror/view`, `@codemirror/lint` to `resolve.dedupe` to avoid the "multiple instances of @codemirror/state" runtime error introduced when `preserveSymlinks: true` is combined with the linked `@tginternal/editor` worktree. ## Notes - Re-importing a `.po` file that was imported before this change (when msgctxt was silently dropped) will create new keys for the `(msgctxt, msgid)` pairs instead of updating the existing `msgid`-only keys. Accepted breakage — most users import once. - An empty `msgctxt ""` collapses to a plain key without a chip, matching gettext semantics. ## Companion PRs - editor: tolgee/editor#8 - tolgee-js: tolgee/tolgee-js#3523 - documentation: tolgee/documentation#1111 <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **New Features** * Full PO msgctxt support: import/export preserves and uses context to disambiguate identical strings. * Key display shows visual context indicators with a tooltip linking to docs via a new KeyName component. * Key editor gains a new "keyName" mode for viewing/editing keys with context. * Import ignores stray context-only entries to avoid header mis-parsing. * **Tests** * Added unit and end-to-end tests for msgctxt parsing, escaping, import/export, fixtures and UI behavior. * **Chores** * Editor package updated. <!-- review_stack_entry_start --> [](https://app.coderabbit.ai/change-stack/tolgee/tolgee-platform/pull/3694?utm_source=github_walkthrough&utm_medium=github&utm_campaign=change_stack) <!-- review_stack_entry_end --> <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
](https://app.coderabbit.ai/change-stack/tolgee/tolgee-js/pull/3523?utm_source=github_walkthrough&utm_medium=github&utm_campaign=change_stack){kind=link}
](https://app.coderabbit.ai/change-stack/tolgee/tolgee-platform/pull/3694?utm_source=github_walkthrough&utm_medium=github&utm_campaign=change_stack){kind=link}
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.
Anty0
force-pushed
the
jirikuchynka/po-msgctxt-v2
branch
from
3165b98 to
d32a975
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
platform/formats/po.mdxexplaining how Tolgee encodes the gettextmsgctxtfield into key names using the U+0004 separator.msgctxtin the existing Feature support paragraph.Companion PRs