Skip to content

Set the language once, as Starlight’s root locale:

astro.config.mjs
projectSite({
// ...
starlight: { locales: { root: { label: 'Français', lang: 'fr' } } },
});

Every page follows it, the landing page, gallery and blog included:

  • <html lang="fr"> everywhere, and dir="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.

labels sets any of them, by name, in any language. For example, in Portuguese:

astro.config.mjs
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).

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.

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.

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.

astro-project-site

A whole site for your open-source project, from one Astro integration.

© 2026 astro-project-site · v0.1.0-beta.6 · MIT licence. This site is built with itself.