A site in another language
Section titled “A site in another language”Set the language once, as Starlight’s root locale:
projectSite({ // ... starlight: { locales: { root: { label: 'Français', lang: 'fr' } } },});Every page follows it, the landing page, gallery and blog included:
<html lang="fr">everywhere, anddir="rtl"for a right-to-left language (dir: 'rtl'in the locale).- Starlight’s own words (search, “On this page”, pagination) in French, from Starlight.
- The template’s own words in French: “Copier”, “Aller au contenu”, the theme switch, the gallery filters,
“Voir toute la galerie”, reading time, dates, “Ada et Grace” for two authors, alert titles (
> [!NOTE]is “Remarque”), the default nav and section headings.
Built-in translations: English, French, German and Spanish. Any other language gets English for the
template’s words until you set them (below); a regional tag (pt-BR, fr-CA) uses its language’s translation.
Your own text (options, docs, posts, gallery entries) is whatever language you write it in.
Change the template’s words
Section titled “Change the template’s words”labels sets any of them, by name, in any language. For example, in Portuguese:
projectSite({ // ... starlight: { locales: { root: { label: 'Português', lang: 'pt' } } }, labels: { copy: 'Copiar', skipToContent: 'Ir para o conteúdo', // Counted words take plural forms (Intl.PluralRules categories; `other` is required). pageCount: { one: '{n} página', other: '{n} páginas' }, },});It works in English too, to change a word you would rather not use (labels: { galleryAll: 'More demos' }).
Every name, with its English text, is in src/labels.mjs;
an unknown name is a build error, so a typo does not go unnoticed. {n}, {year}, {name}, {tag} and the other
placeholders are filled in for you.
A few words are options of their own, because they are content rather than interface: section headings
(landing.features.title, landing.docs.title, blog.title, gallery.title), the footer’s copyright line
(footer.copyright, {year} and {name} filled in) and the nav (nav).
Right-to-left languages
Section titled “Right-to-left languages”With dir: 'rtl', the layout mirrors: the header, cards, arrows (“All posts ←”), the theme switch and the margin
notes. Shell commands and code stay left to right. The template’s styles use logical properties only
(margin-inline-start, not margin-left); a test keeps it that way.
Multilingual sites
Section titled “Multilingual sites”Starlight’s multi-locale setup (several locales and src/content/docs/<lang>/ folders) passes through, and
docs pages in a second locale get the template’s words in that language (its built-in translation, or English),
except alert titles, which markdown renders once, in the root language.
The generated sidebar only reads src/content/docs/docs/, though, so translated pages need a hand-written
starlight.sidebar; the landing page, gallery, blog and llms.txt are in the root language only. This is not
tested yet.
How it is checked
Section titled “How it is checked”The repository builds a small site in French and in Arabic (right to left) on every change
(npm run test:i18n): each page must carry the right lang and dir, show the translated words and none of the
English they replace, and pass the same accessibility checks as the template’s own site.