Skip to main content

Documentation site i18n

The Docusaurus site under docs/ ships English and Polish user-facing prose. Repository working language for code, specs and commit messages stays English. Polish documentation is authored manually in the same merge request as the English edit — there is no machine-translation step in CI or production builds.

This page is the workflow for docs-site translations. Admin UI string bundles (each module's own i18n/ directory, at its package root) are a separate system — see Admin UI Translations.

What must be translated​

pnpm --filter backend run check:docs-translations enumerates every English source and expects a translation pin plus a materialised markdown file for each locale in docs/locales.config.json → translateLocales (v1: pl only):

LayerEnglish sourcePin sourcePath key
Hand-authored site pagesdocs/docs/**/*.md (excluding generated categories)repo-relative path, e.g. docs/docs/intro.md
Module reference (generated)docs/docs/module-reference/*.mdgenerated:module-reference/<slug>
Module map (generated)docs/docs/modules/module-map.generated.mdrepo-relative path
Module-owned pagesdocs/**/*.md at each module's package rootrepo-relative path

Paths listed in docs/translation-skip.json are excluded (today: docs/docs/contributing/translations.md, which is the Admin UI glossary).

Chrome — the navbar, the footer and the sidebar category labels declared in docs/sidebars.js and docs/sidebars.modules.generated.js — is translated in the files Docusaurus reads it from, which are not code.json. The next section is that rule; getting it wrong translates nothing and says nothing, which is how a whole Polish chrome once shipped rendering in English.

Where a message id belongs​

Every message id has exactly one file Docusaurus will read it from. Writing it anywhere else is inert: the build succeeds, the page renders, and the string stays in the source language.

Config-derived ids belong in the theme and plugin translation files. These are the ids Docusaurus derives from docs/docusaurus.config.js's themeConfig and from docs/sidebars.js:

IdsFile, under docs/i18n/<locale>/
title, logo.alt, item.label.<Label> — navbardocusaurus-theme-classic/navbar.json
copyright, logo.alt, link.title.<Title>, link.item.label.<Label> — footerdocusaurus-theme-classic/footer.json
sidebar.<name>.category.<key> and its .link.generated-index.title / .description, sidebar.<name>.link.<key>docusaurus-plugin-content-docs/current.json

A category's <key> is category.key ?? category.label, and the navbar and footer ids are keyed plain inside their own file — title, never theme.navbar.title.

Component-emitted ids belong in code.json. Those are the strings theme and plugin components emit — Docusaurus's own theme strings such as theme.navbar.mobileLanguageDropdown.label, and the search plugin's. docs/i18n/<locale>/code.json is their correct home and holds nothing else.

sidebar.<name>.doc.* is inert everywhere. A bare 'some/doc' entry in either sidebar file is normalised by the content-docs plugin with translatable: false, so no such id is read from any file: a Polish sidebar doc label comes from the Polish page's own title — the sidebar_label or title in the materialised page's front matter. Doc entries owe no translation file entry at all.

pnpm --filter backend run check:docs-translations derives the expected id set from the two config files rather than from a list (backend/scripts/lib/docs-chrome-messages.ts), so a new navbar item or category is reported the first time it appears — as chrome-message-missing when its own file lacks it, and as chrome-message-inert when it is parked in code.json instead.

Three-step edit sequence​

Use this sequence when you change one English page and its Polish translation. Steps 1–2 are file edits; step 3 is the local guard.

  1. Edit the English source — hand-authored page under docs/docs/, or the module's own docs/ directory at the package root (not under src/).

  2. Write or update the Polish page in the same merge request, at docs/i18n/pl/docusaurus-plugin-content-docs/current/<docId>.md (e.g. docs/docs/intro.md → .../current/intro.md, the catalog module's own docs/catalog.md → .../current/modules/catalog.md). That page is the translation: it is what Docusaurus builds.

    • If you changed a sidebar category label, or a navbar or footer string, add the matching id to the file named for it in Where a message id belongs above. A sidebar doc entry owes no id.
  3. Re-pin the page, then run the completeness check:

    pnpm --filter backend run docs:translations:pin docs/docs/intro.md
    pnpm --filter backend run check:docs-translations

    The pin command records the hash of the English body the Polish page now matches (Translation pins below). Name the pages you translated, by their English path or their pin key; with no names it re-pins every page whose English body has moved. Pinning tells the check that the translation is up to date, so pin only pages you have actually brought up to date.

    Exit code 0 = every source has a fresh pin, a materialised file from which Docusaurus can resolve a title, and every chrome id in the file that reads it. Exit code 2 lists missing-translation, stale-translation, malformed-pin, missing-sidebar-message, chrome-message-missing, chrome-message-inert or doc-title-unresolvable findings.

Translation pins​

A pin is a small JSON file at docs/translation-cache/<locale>/<sourceKey>.json. Slashes in the source path become --, e.g. docs/docs/intro.md → docs--docs--intro.md.json. It says which English body the translation was made from, and nothing else:

{
"sourcePath": "docs/docs/intro.md",
"sourceHash": "<sha256 of English body>",
"locale": "pl",
"meta": {
"provider": "manual",
"updatedAt": "2026-09-17T12:00:00.000Z"
}
}

sourceHash is the sha256 of the normalised English body, with the YAML front matter stripped (hashSourceBody() in backend/scripts/lib/docs-translation-cache.ts). So a change to the English front matter alone does not make the translation stale. Let docs:translations:pin write pins rather than editing them by hand. It refuses, and writes nothing, when a page it would pin has no Polish page, when the Polish page's body is the English body, or when a name you passed is not a documentation source. A pin that is already fresh is left untouched.

The check reports a pin holding anything else as malformed-pin. That covers an unresolved conflict marker, and the content copy of the whole page that entries carried before issue #671.

Resolving a conflict in a pin. Two branches that both change the same English page conflict on its sourceHash. Take either side, make sure the Polish page is right for the merged English page, and run pnpm --filter backend run docs:translations:pin <page>. The hash is derived, so it is regenerated rather than merged.

Preserve code fences, inline code, URLs, file paths, CLI commands, JSON/YAML literals, HTTP methods/paths and module ids unchanged in Polish prose.

Polish terminology​

Write Polish pages with the terms in Documentation-site terminology — one glossary for the Admin UI and this site, so that an overlay module is a moduł nakładkowy on every page rather than on some. Translate the meaning, not the sentence: Polish word order, no English verb with a Polish ending, and a loanword only where the glossary keeps one. If a term you need is missing, add its row in the same pull request.

Generated English artefacts​

pnpm --filter backend run composer:generate emits English only for:

  • module reference pages under docs/docs/module-reference/,
  • the module map at docs/docs/modules/module-map.generated.md,
  • the generated sidebar fragment docs/sidebars.modules.generated.js.

After regeneration, manually mirror Polish under docs/i18n/pl/:

  • materialised files under docs/i18n/pl/docusaurus-plugin-content-docs/current/module-reference/ and .../modules/,
  • a sidebar.main.category.<key> id in docs/i18n/pl/docusaurus-plugin-content-docs/current.json for every new category the regenerated docs/sidebars.modules.generated.js declares. New doc entries owe nothing — their Polish label is the materialised page's own title.

Then run docs:translations:pin for the regenerated pages. They are pinned as generated:module-reference/<slug> and under the module map's repo-relative path.

Do not edit generated English files for Polish. Update the i18n tree and re-pin instead.

pnpm --filter backend run docs:collect (English copies into docs/docs/modules/) does not write Polish; committed i18n files supply the Polish locale at build time.

Optional verification​

After check:docs-translations passes, confirm both locales build:

pnpm --filter docs run build

onBrokenLinks: 'throw' must pass for English and Polish.

Adding a future locale​

Additional locales are additive — no pipeline rearchitecture. To add, for example, German:

  1. Append "de" to locales and translateLocales in docs/locales.config.json.
  2. Add label (and related theme strings) for de in docs/docusaurus.config.js → i18n.localeConfigs.
  3. Scaffold the chrome translation files by copying the pl ones and translating them — docs/i18n/de/docusaurus-theme-classic/navbar.json and footer.json, docs/i18n/de/docusaurus-plugin-content-docs/current.json, and docs/i18n/de/code.json for component-emitted ids only (Where a message id belongs above).
  4. Manually author the materialised markdown under docs/i18n/de/docusaurus-plugin-content-docs/current/ for every English source (same layers as Polish), then run pnpm --filter backend run docs:translations:pin to write the pins under docs/translation-cache/de/.
  5. Run pnpm --filter backend run check:docs-translations and pnpm --filter docs run build — both must exit 0.

All consumers (check-docs-translations.ts, pin-docs-translations.ts, Docusaurus config, future hooks) read loadDocsLocales() from docs/locales.config.json — do not hard-code locale codes in scripts.

See also​