Internationalization
How-toMultilanguage-ready i18n engine and how to add new locales.
The starter ships English-only out of the box, but the i18n engine is fully wired so you can add languages without re-architecting anything.
How It Works
Section titled “How It Works”The i18n system is built on three layers:
- Astro’s built-in i18n — locale routing configured in
astro.config.ts - Content collection locale fields — each content entry declares its
locale - Translation files — UI strings live in
src/i18n/<locale>.json
The single source of truth for active locales is src/config/i18n.config.ts.
Astro’s routing, the sitemap, the content locale enum, SITE_CONFIG and the
Locale type are all derived from it.
UI Translations
Section titled “UI Translations”UI strings live in src/i18n/en.json and are read through the t() helper:
---import { t } from "../i18n/ui";const locale = (Astro.currentLocale || "en") as "en";---<p>{t(locale, "nav.home")}</p>t() falls back to the key itself when a string is missing, so dev builds fail
loudly when a translation is absent.
Adding a New Locale
Section titled “Adding a New Locale”-
Register the locale in
src/config/i18n.config.ts:export const locales = ["en", "id"] as const;// …localeLabels: { en: "English", id: "Bahasa Indonesia" },localeTags: { en: "en-US", id: "id-ID" },That’s the only config change: the
Localetype, Astro’si18nrouting, the sitemap hreflang tags and the contentlocaleschema all follow. -
Add a translations file
src/i18n/id.jsonand register it insrc/i18n/ui.ts:import id from "./id.json";export const translations = { en, id };pnpm validate:i18nfails until every key fromen.jsonexists inid.json. -
Add localized content by setting
locale: idon a copy of each entry (e.g.about.mdforen,about.id.mdforid). The content-validation test catches duplicate slugs or translation keys within a locale. -
Add prefixed routes under
src/pages/[locale]/for the non-default locales (the default locale is served at the root with no prefix), and useresolveRoute(locale, path)for every internal link. -
Optional: translate Starlight’s UI by adding
src/content/i18n/id.jsonand configuringlocalesin the Starlight integration.
Once a second locale is registered, the header language switcher shows up automatically.
Was this helpful?