Translating the product UI
Catalogs are gettext .po files in front/locales/{locale}/<source directory>/messages.po: every
source directory using Lingui has one per entry of CATALOG_LOCALES in front/types/locale.ts. A
message used in several directories appears in each of their catalogs; translate it the same way
everywhere (npm run i18n:check fails otherwise). When the meanings differ, give the messages a
Lingui context in the code instead (see the dust-i18n skill).
The Slack bot has a single catalog per locale, connectors/locales/{locale}/messages.po. Its
msgid is the English text itself: keep the Slack mrkdwn (*bold*, _italic_, `code`,
<url|label>) around the translated text.
en-US is the source locale: its catalogs are generated and never translated by hand. Every other
catalog must have a non-empty msgstr for every message.
Some supported locales reuse another locale's catalog (CATALOG_LOCALE_BY_LOCALE): en-GB renders
the en-US messages and only changes date and number formatting. Never create a catalog or write
translations for them.
Sparkle components have their own catalogs, one per locale entry of SPARKLE_CATALOG_LOCALES, at
sparkle/src/locales/{locale}/messages.po, with the same en-US source-locale rule. Run the
commands below from sparkle/ for them. i18n:check does not compare sparkle and front catalogs:
translate a message they share (Cancel, Loading) the same way in both by hand.
Procedure
- Run
npm run i18n:extractfrom the repository root (orsparkle/) so the catalogs match the code. - For each entry with an empty
msgstr:- Read the
#:file reference and the code around the string: know whether it is a button, a title, a description or a toast, and what it refers to. - Honour the
msgctxtline when present (for exampleverb, button label). - Translate following the locale style guide and the glossary in
references/.
- Read the
- To fix an existing translation, edit its
msgstronly. Never editmsgid,msgctxtor the#:references: they are generated from the code. - Run
npm run i18n:checkfrom the same directory.
Rules for every locale
- Keep placeholders exactly:
{name},{0},<0>…</0>. You may move them, not rename or drop them. Keep ICU structures ({count, plural, one {…} other {…}}) and translate only the text inside each branch; add the plural categories the target language needs. - Keep keyboard symbols (
⌘,↵,⇧) and product names from the glossary unchanged. - Match the tone of the English: short, plain, friendly, no marketing language.
- Keep the length close to the English: UI labels have little room. Prefer the shorter wording when two are equally correct.
- Use sentence case, as in the English source.
Locale style guides
fr-FR: references/fr-FR.md


