Skip to main content

Translation guide

The site is internationalisation-ready but currently ships English only. This page defines how a locale is added, so that the first translation does not have to invent the process.

Structure​

Docusaurus keeps translated content beside the source, not inside it:

repository root
  • docs/English source — the only editable curriculum
  • i18n/
  • es/
  • docusaurus-plugin-content-docs/mirrors docs/ exactly
  • docusaurus-theme-classic/navbar and footer strings
  • code.jsonUI strings from React components

Adding a locale​

  1. Open an issue first

    A locale needs at least two committed translators. A half-translated locale is worse than none: readers hit English pages with no warning and lose trust in the navigation.

  2. Register the locale

    Add it to i18n.locales and i18n.localeConfigs in docusaurus.config.ts, including direction for right-to-left languages.

  3. Generate the scaffolding

    pnpm write-translations --locale es

    This produces code.json and the theme translation files, pre-filled with the English strings.

  4. Copy the documents

    mkdir -p i18n/es/docusaurus-plugin-content-docs/current
    cp -r docs/* i18n/es/docusaurus-plugin-content-docs/current/

    Directory and file names stay identical to the English source. Only the prose is translated.

  5. Build and check

    pnpm build && pnpm serve

What must not be translated​

Translating any of these breaks the site or, worse, breaks the reader's commands:

  • Git commands, flags, output and error messages. A reader whose terminal is in English must be able to match your text to their screen. Translate the explanation, never the sample.
  • Filenames, directory names and document id values. These are the routing keys; translating one detaches the page from its English counterpart.
  • Code identifiers, configuration keys and branch names.
  • Component names and their props. <Checkpoint verify="..."> stays as-is; the strings passed to it are translated.
  • Anchor ids pinned with {#explicit-anchor}.

Frontmatter in translations​

Translate title, sidebar_label, description and keywords.

Keep id, module, level, duration, status, tags and prerequisites identical to the source. maintainers becomes the translators for that locale — they are who should be asked about that file.

Keeping translations in sync​

English is the source of truth and moves first. When an English document changes:

  1. The i18n-drift workflow opens an issue against each locale whose copy is now behind.
  2. Until it is updated, the translated page keeps serving — a slightly stale translation is better than a missing page.
  3. last_reviewed in the translated file records when the translation was last checked against the source, not when the source was verified.

Never let a translated document's last_reviewed exceed its source's.