Translating the docs

The site is built once per language by Antora, using AsciiDoc generated by po4a from the same English source files every component already publishes. A translated page always exists at the same path as its English counterpart — untranslated strings just render in English until someone fills them in.

Filling in Kurmanji (kmr)

Kurmanji translations live in a single catalog, locale/kmr/docs.po, at the root of this repo. Open it in any PO editor (Poedit, Lokalize, a plain text editor) and fill in the msgstr under any msgid you can translate. Nothing else needs to change — the next site build picks up your edits.

make build and CI always run po4a with --no-update, so routine builds never rewrite the catalog files themselves — they only ever read existing msgid/msgstr pairs and fall back to English for anything not yet in the catalog. If you add a new page or edit existing English content, its strings won’t show up in locale/docs.pot/ locale/kmr/docs.po for translators until someone refreshes the catalog on purpose. po4a.cfg reads six of the seven component trees from .translation-src/, which only exists after make build has cloned them, so run that at least once on a fresh checkout first:

make build
po4a --keep 0 po4a.cfg

Review the diff (it should only ever add or reword entries, never delete translated `msgstr`s for content that still exists) and commit the refreshed catalog files.

Adding a new language

There’s no generic multi-language machinery here on purpose — each language is wired up explicitly, by hand, following the same pattern as kmr. To add locale <code> (an ISO 639 code, e.g. kmr, es, fr):

  1. Extend po4a.cfg. Add <code> to the [po4a_langs] line, and duplicate every [type: asciidoc] line, replacing kmr with <code> in each localized-file path.

    [po4a_langs] kmr <code>
[po4a_paths] locale/docs.pot $lang:locale/$lang/docs.po

[type: asciidoc] docs/modules/ROOT/pages/index.adoc $lang:build/docs/$lang/home/modules/ROOT/pages/index.adoc

    (one [type: asciidoc] line per page + nav.adoc, across every component — see the existing file for the full list).

  2. Generate the initial catalog. From the repo root, with po4a installed (and make build already run at least once, so .translation-src/ exists for po4a.cfg to read from):

    po4a --keep 0 po4a.cfg

    Note there’s no --no-update here: an initial catalog doesn’t exist yet, and --no-update prevents po4a from creating one from scratch, not just from refreshing an existing one.

    This creates locale/<code>/docs.po with every string present and blank `msgstr`s. Commit it.

  3. Add a playbook for the new language. Copy antora-playbook-kmr.yml to antora-playbook-<code>.yml, and in the copy replace every build/docs/kmr/…​ path with build/docs/<code>/…​, and output.dir with ./build/site/<code>.

  4. Add the language to CI. In .github/workflows/deploy.yml, duplicate the "Stage untranslated component trees" and "Build Kurmanji site" steps for <code> (pointing at build/docs/<code> and antora-playbook-<code>.yml respectively).

  5. Add the language to the switcher. In supplemental-ui/partials/page-languages.hbs, add one more <a class="language"> entry (and extend the button-label conditional) for <code>.

  6. Open a PR. Reviewers don’t need to speak the language to merge it — pages render in English until a native speaker fills in msgstr entries in locale/<code>/docs.po over time.

Want to help? Learn how to contribute to the ZirekHQ docs ›