- Docs
- Set up languages
Set up languages
Choose initial languages, add matching dictionary keys later, and activate a completed locale.
Choose the initial languages
The wizard offers en-us, es-mx and es-es, with prepared translations for those presets. You can also enter another locale with its native display name and text direction. A custom language starts with dictionary keys for you to translate.
The project includes only the languages you select. Domain contracts live in the chosen default locale, so a Spanish-only project can keep its complete dictionary structure under es-mx or es-es.
Find the dictionaries
Each domain is a folder inside src/i18n/dictionaries/<locale>. Its index.ts
contains the translated values and types.ts describes the expected keys. The
locale’s own index combines the domains.
Put visitor-facing text here: page copy, metadata, control labels, accessible names, validation messages and loading/error feedback. Keep the same key structure across languages. See the dictionary API for typed access.
Add a language to an existing project
Run one of these from the generated project root:
npm
npx @samline/astro locale add fr-fr --locale-name 'Français (France)'
npx @samline/astro locale add ar --locale-name العربية --direction rtlpnpm
pnpm dlx @samline/astro locale add fr-fr --locale-name 'Français (France)'
pnpm dlx @samline/astro locale add ar --locale-name العربية --direction rtlBun
bunx @samline/astro locale add fr-fr --locale-name 'Français (France)'
bunx @samline/astro locale add ar --locale-name العربية --direction rtlThe installer reads the current project’s dictionaries, including domains and keys added since creation. It creates the same structure for the new locale with empty translation strings. Your existing dictionaries retain their values.
Read dictionary modules as static data so the installer can inspect their shape. If it reports dynamic values, inconsistent types or an index importing another locale’s values, resolve that composition before retrying. Language creation scaffolds UI dictionaries; content entries and translated URLs are handled at their own source.
Translate, then activate
- Fill the new domain values in
src/i18n/dictionaries/<new-locale>. - Complete the language names wherever the LanguagePicker dictionaries need them.
- Check that the site’s routes and content exist in the new language.
- Add the finished code to the existing
localesarray insrc/i18n/config.ts. - Run the generated formatter,
check:i18n, type check and build.
A later addition remains inactive until you edit that array. Once active, empty
required translations fail check:i18n. For RTL languages, use the generated
direction metadata and review the actual layout, controls and icons in RTL.
Match translated pages correctly
Every language has src/i18n/dictionaries/<locale>/routes.ts beside its index.
This is its readable inventory of stable route names and real locale-free paths,
for example 'company.about': '/nosotros'. Declare shared names in
src/config/routes.ts; src/i18n/route-tables.ts only registers the locale tables.
Types require the same declared names across tables. Use null for a page that
has no translation. Keep these structural files separate from UI copy domains.
A minimal project includes home.index; Welcome adds demo.index. Later language
addition scaffolds the current route keys with null, preserves existing URLs and
keeps the language inactive. Complete actual pages/paths before activation.
Use <Link routeName={routeNames.home} currentMatch='descendants'> in a section
and <Main routeName={routeNames.home}> in the page. Main shares the identity with
SEO and its default header, so the language selector uses the same destinations.
Button accepts routeName too. Exact page links receive aria-current=‘page’; parent
links can opt into segment-bounded child matching. Home remains exact-only.
For a CMS item, resolve its actual published translation relation and pass
localizedPaths to Main. Custom headers forward that context to LanguagePicker.
Absent translations are omitted rather than guessed. routeEntries(locale) exposes the active public page inventory for navigation
or an HTML sitemap. XML sitemap discovery and indexability remain separate;
route names never create pages or establish that a URL should be indexed.
See the localized route API for working
catalog examples, typed helpers, Astro route generation and dynamic content limits.
Astro provides internationalized routing and the locale URL helpers. This package prepares the dictionaries and initial configuration around those APIs.