Contributing translations

Community translations are very welcome. This page explains how to add a new language or improve an existing one.

How translations are stored

Starlight Quiz shares its translations verbatim with mkdocs-quiz so the two sibling plugins always read the same way. The source of truth is a set of standard gettext .po files:

packages/starlight-quiz/locales/
  de.po   eo.po   es.po   fr.po   hi.po   id.po
  ja.po   ko.po   no.po   pt-BR.po  sv.po   zh.po

There is no en.po: English is the source text, used as the fallback when a string is untranslated.

A build step, gen:i18n, compiles these .po files into translations.ts (the table the plugin injects into Starlight). Two kinds of string feed into it:

Shared strings (buttons, feedback, score messages) are pulled from the .po files by matching the mkdocs-quiz source text.
A few Starlight-only strings with no mkdocs counterpart (the intro-panel text and a couple of results-panel labels) live in a hand-maintained CURATED map in packages/starlight-quiz/scripts/build-i18n.ts.

Add or improve a language

Edit the .po file for the locale under packages/starlight-quiz/locales/ (create <code>.po from an existing one if the language is new). Fill in each msgstr:
```
msgid "Submit"
msgstr "Vérifier"

msgid "Question {n}"
msgstr "Question {n}"
```
(Optional) For full coverage, add the Starlight-only strings for your locale to the CURATED map in scripts/build-i18n.ts. Locales missing from CURATED simply fall back to English for those few keys.

Regenerate the runtime table:

pnpm --filter starlight-quiz gen:i18n

It rewrites translations.ts and prints a coverage summary, a quick way to see what is still missing:

Coverage (translated / 21 strings):
  de     20/21   95%
  es     20/21   95%
  fr     19/21   90%
  …

Commit the regenerated translations.ts alongside your .po change (and build-i18n.ts if you edited CURATED).
Open a pull request. Because the .po files are shared with mkdocs-quiz, please mention if the same change should land there too, so the two stay in sync.

Test it locally

Configure a locale in the docs site (or your own Starlight site) and view a quiz under it:

starlight({
  locales: { en: { label: 'English' }, fr: { label: 'Français', lang: 'fr' } },
  plugins: [starlightQuiz()],
});

A quiz on a page served under /fr/… should now show your translated buttons and messages. See Translations for the reader-facing side and how labels resolve.

Guidelines

Preserve placeholders. Keep {n} intact: "Question {n}" → "Question {n}", never "Question numéro".
Keep it concise. Buttons and labels need to fit; the intro text has more room.
Match tone. Feedback and score messages should stay friendly and encouraging.
Use UTF-8 for the .po file.
Language codes follow Starlight’s: a 2-letter code, with a region suffix where needed. Note mkdocs-quiz’s pt-BR.po is lower-cased to pt-br in the generated Starlight table.