Astro i18n

Astro i18n is a lightweight, typed internationalization starter for Astro that gives you a copyable src/i18n module with type-safe translation loading and interpolation.

What is Astro i18n?

Astro i18n is a minimal reference implementation for adding multilingual support to an Astro site. It takes translation dictionaries written as TypeScript objects and exposes typed helper functions so that missing or extra placeholders are caught at compile time. The starter is not a plugin; it is a small, self-contained module that you can copy directly into your own project and extend as needed. It runs on the Astro framework and is built around Astro's file-based routing, using a [lang] dynamic segment to generate one static page per locale.

Key Features

• Typed locale dictionaries — Each locale file must satisfy the Translations interface defined in src/i18n/schema.ts, enforced with TypeScript's satisfies operator so drift between languages is flagged during development.
• Central language registry — src/i18n/config.ts holds the list of available languages and the default language; every other part of the module reads from this single source of truth.
• Type-safe interpolation — The interpolate helper creates strings with named parameters, and TypeScript reports missing or extra placeholders when any locale disagrees; for example, if one locale expects {foo} and {bar} and another adds {asd}, the compiler flags the mismatch at every usage site.
• Default language redirect — Requests to / are redirected to the default language segment, so visitors always land on a locale-prefixed URL.
• Static routes per locale — Using a [lang] dynamic route with getStaticPaths, Astro generates a separate HTML page for each registered language from the same page template.
• Minimal UI — The starter's interface is intentionally bare so the focus stays on translation structure, routing, and interpolation rather than visual design.

Who should use Astro i18n?

• Astro developers starting a multilingual site — You get a working i18n setup (schema, config, locales, redirect, and static paths) without pulling in a heavyweight plugin or service.
• Teams that value type safety — If a translator adds a placeholder in one locale but not another, TypeScript will error at every usage site, keeping all locale files in sync automatically.
• Developers who want a reference implementation — The module is small and well-structured, making it easy to read and learn before writing your own i18n layer.

What can you do with it?

• Add i18n to an existing Astro project: Copy the src/i18n directory, define your Translations schema, and register your locales in config.ts to get typed translations on any page.
• Create localized pages with static generation: Use src/pages/[lang]/index.astro with getStaticPaths to emit a separate HTML file for each language at build time.
• Catch placeholder mismatches during development: Use the interpolate helper so that inconsistent placeholders across locales become compile-time errors instead of runtime breakage.

How does Astro i18n work?

Start by defining the shape of your translations in src/i18n/schema.ts as a TypeScript interface. Create one file per locale inside src/i18n/locales/ (for example en.ts and es.ts), each exporting an object that satisfies the interface and uses interpolate() for any string containing named placeholders. Register these locale objects in src/i18n/config.ts and set a default language. In any Astro page or component, import getTranslations, getLangFromUrl, and translations to load the current language from the URL, or use getStaticPaths with the [lang] dynamic route to generate all locale pages during the build.