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

Every translated string lives in a standard gettext .po file — there is no second place to look:

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  ru.po   sv.po   zh.po

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

Most of these strings are shared with mkdocs-quiz, the sibling plugin, so the two always read the same way — that part of each file is byte-identical to mkdocs-quiz’s own. A handful belong to UI mkdocs-quiz doesn’t have (the intro panel, the mobile table-of-contents badge, and the page-wide reset button with its confirm prompt); those sit in a clearly marked block at the end of each file. mkdocs-quiz ignores them, so one file serves both projects.

A build step, gen:i18n, compiles the .po files into translations.ts, the table the plugin injects into Starlight.

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}"
```
Translate the marked Starlight-only block at the end of the file too — any msgstr you leave empty simply falls back to English.
Regenerate the runtime table:
Terminal window
```
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 / 22 strings):
  de     22/22  100%
  es     22/22  100%
  fr     22/22  100%
  …
```
Anything short of full coverage is listed by key, so you can see exactly what is still missing.
Commit the regenerated translations.ts alongside your .po change.
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.