# Translations

Every user-facing string (buttons, feedback, the results panel, the score messages) is translatable. Under Starlight
the right locale is chosen automatically; outside Starlight you pass labels as props.

## A quick primer on Starlight i18n

If you have not set up a multilingual Starlight site before, here is the short version. You declare your languages in
the Starlight config:

```js title="astro.config.mjs"
starlight({
  defaultLocale: 'en',
  locales: {
    en: { label: 'English' },
    fr: { label: 'Français', lang: 'fr' },
  },
  plugins: [starlightQuiz()],
});
```

Your content then lives in a folder per language (`src/content/docs/en/…`, `src/content/docs/fr/…`), and Starlight
serves each under its own route (`/fr/…`). For UI strings (navigation, the search box, and plugin strings like the quiz
buttons), Starlight keeps a translation table per locale and exposes the current one to components. Starlight Quiz hooks
into exactly that mechanism, so **a quiz on a French page renders its buttons and messages in French with no extra
work**. For the full picture, see Starlight's [i18n guide](https://starlight.astro.build/guides/i18n/).

## Built-in locales

Starlight Quiz ships translations for **13 languages**, shared verbatim with its sibling
[mkdocs-quiz](https://github.com/ewels/mkdocs-quiz) via the same gettext `.po` files:

| Code    | Language              | Code    | Language               |
| ------- | --------------------- | ------- | ---------------------- |
| `en`    | English (source)      | `ja`    | Japanese               |
| `de`    | German                | `ko`    | Korean                 |
| `eo`    | Esperanto             | `no`    | Norwegian              |
| `es`    | Spanish               | `pt-br` | Portuguese (Brazilian) |
| `fr`    | French                | `sv`    | Swedish                |
| `hi`    | Hindi                 | `zh`    | Chinese (Simplified)   |
| `id`    | Indonesian            |         |                        |

When the plugin is installed, these are injected into Starlight's i18n. A quiz on a page served under a configured
locale (e.g. `/fr/…`) picks up that locale's strings automatically. Strings a locale hasn't translated fall back to
English.

## How a label is resolved

Each label is resolved in this order (the first that exists wins):

1. An **explicit prop** (or, for `<QuizIntro>`, slot content) on the component.
2. The **Starlight translation** for the current locale.
3. The bundled **English** default.

This is what lets the same component work translated inside Starlight and with explicit labels in a plain Astro
project.

## See it translated

Here is a quiz and a results panel with their labels in French. On a real French page you would not pass any of these
props; Starlight would supply them from the locale. They are set here only because this page is served in English:

<Quiz id="fr-demo" submitLabel="Vérifier" correctLabel="Correct !" incorrectLabel="Pas tout à fait…" resetLabel="Recommencer">
Quelle est la capitale de la France ?

- [ ] Londres
- [x] Paris
- [ ] Berlin

Paris est la capitale de la France depuis le Moyen Âge.

</Quiz>

<QuizResults titleLabel="Quiz terminé !" progressLabel="Progression" answeredLabel="répondues" correctLabel="correctes" resetLabel="Réinitialiser toutes les réponses" />

## Overriding text per quiz

Any string can be overridden per instance, handy for custom wording or when you're outside Starlight. See the
[`<Quiz>`](/starlight-quiz/guides/configuration/#quiz-props), [`<QuizResults>`](/starlight-quiz/guides/configuration/#quizresults-props)
and [`<QuizIntro>`](/starlight-quiz/guides/configuration/#quizintro-props) prop tables for every label.

```mdx title="quiz.mdx"
<Quiz submitLabel="Check answer" correctLabel="Spot on!" incorrectLabel="Not quite…">
Is the sky blue?

- [x] Yes
- [ ] No
</Quiz>
```

<Quiz id="translations-demo" submitLabel="Check answer" correctLabel="Spot on!" incorrectLabel="Not quite…" autoSubmit={false}>
Is the sky blue?

- [x] Yes
- [ ] No

</Quiz>

## Override the bundled wording

To change a label everywhere on your site (rather than per quiz), override the key in **your own** Starlight UI
translations. The plugin injects its strings as defaults, and Starlight lets your site's translations take precedence,
so any `starlightQuiz.*` key you define wins. Add the keys to your i18n data, per locale:

```json title="src/content/i18n/en.json"
{
  "starlightQuiz.submit": "Check answer",
  "starlightQuiz.results.title": "Your result"
}
```

Every key lives under the `starlightQuiz.` namespace (e.g. `starlightQuiz.submit`, `starlightQuiz.correct`,
`starlightQuiz.results.excellent`, `starlightQuiz.questionNumber`). This is the equivalent of supplying your own
translation file, and it works for the bundled locales as well as any you add. See Starlight's
[i18n guide](https://starlight.astro.build/guides/i18n/#translate-starlights-ui) for where these files live.

## Outside Starlight

In a plain Astro project there is no translation function, so only steps 1 and 3 above apply: pass label props for any
text you want changed, otherwise you get English. See [Astro installation](/starlight-quiz/guides/vanilla-astro/).

## Adding or updating a language

The translations are shared with mkdocs-quiz through gettext `.po` files. To add a language or improve an existing one,
see [Contributing translations](/starlight-quiz/guides/contributing-translations/).