# Astro i18n: How to Build a Multi-Language Website > Add an i18n block to astro.config.mjs with your locales and defaultLocale, put translated pages in one folder per locale under src/pages, and keep translated content in per-locale folders inside a content collection. Then add a UI string dictionary, a language switcher, hreflang and canonical tags, and the @astrojs/sitemap i18n option so search engines can pair each page with its translations. Canonical page: [https://getastrothemes.com/blog/astro-multilingual-website-guide/](https://getastrothemes.com/blog/astro-multilingual-website-guide/) - Author: Bektur Aslan - Published: 2026-10-12 - Updated: 2026-11-15 - Categories: Guides ## Faq ### Faq 1 Yes. Astro has built-in i18n routing configured with the i18n option in astro.config.mjs, plus helpers in the astro:i18n module such as getRelativeLocaleUrl. You still write your own UI string dictionary and language switcher, because Astro does not ship a translation library. #### Question Does Astro support multilingual sites without a plugin? ### Faq 2 Either works. Keeping the default language unprefixed (prefixDefaultLocale: false, the default) gives shorter URLs and suits sites with one main market. Prefixing every language (prefixDefaultLocale: true) is more consistent and easier to reason about when all languages are equal. Pick one before launch, because changing it later means redirecting every URL. #### Question Should the default language have a URL prefix like /en/? ### Faq 3 Yes, but Astro does not map them for you. You create the translated file or content entry yourself and keep a mapping, such as a shared translation key in frontmatter, so the language switcher, hreflang tags and sitemap can link the versions together. #### Question Can I use translated slugs like /fr/a-propos/ in Astro? ### Faq 4 Yes. The i18n option of @astrojs/sitemap adds xhtml:link alternate entries for each locale. It pairs pages by the URL path after the locale segment, so pages with translated slugs will not be paired automatically. #### Question Does the Astro sitemap integration add hreflang links? ### Faq 5 Astro has an i18n.domains option, but it requires a configured site, server output with no prerendered pages, and the @astrojs/node or @astrojs/vercel adapter. Cloudflare is not on that list. For a mostly static site, subfolders such as /fr/ are much simpler to run. #### Question Can I put each language on its own domain with Astro? ### Faq 6 Yes, in the paid themes. All 18 ship Arabic alongside English and French, and the Arabic pages mirror the layout: all 18 Arabic demos served html lang=ar dir=rtl when we opened them on November 15, 2026. The three free Lite themes are English and French only. For Hebrew, Persian or Urdu, run generate-multilingual-content with --dir rtl and translate the new content folder. #### Question Do Getastrothemes themes support right-to-left languages? To build a multilingual website with Astro's built-in i18n routing, add an `i18n` block to `astro.config.mjs` that lists your `locales` and `defaultLocale`, then put translated pages in one folder per language under `src/pages/` and translated content in per-language folders inside your content collections. Astro handles the routing and gives you URL helpers; you supply the UI string dictionary, the language switcher, and the SEO tags (`hreflang`, canonical, sitemap). Checked against the [Astro i18n guide](https://docs.astro.build/en/guides/internationalization/) and [@astrojs/sitemap docs](https://docs.astro.build/en/guides/integrations-guide/sitemap/) on November 1, 2026 (Astro 7.4.4). For an Astro i18n example to clone, [Lumio Lite on GitHub](https://github.com/getastrothemes/lumio-lite-astro), our free MIT theme, keeps content in `english` and `french` folders; the [live demo](https://lumio-lite-astro.netlify.app/) serves French at `/fr/`. ## Three decisions to make before you write code Three choices shape the rest of the project. Changing them after launch means redirects and lost search rankings, so settle them with the client first. | Decision | Options | Good default | | -------------------------------- | ------------------------------------------------- | -------------------------------------------------------- | | URL structure | Subfolders (`/fr/`), subdomains, separate domains | Subfolders: static-friendly, one deploy, one domain | | Prefix for the default language? | `/about/` vs `/en/about/` | No prefix if one market dominates; prefix if all equal | | Slugs | Same slug everywhere vs translated slugs | Same slugs for small sites; translated for SEO-led sites | Also ask who will translate, how often content changes, and whether every page must exist in every language. That last answer decides whether you need a fallback strategy. ## How do you configure Astro's built-in i18n routing? Astro's i18n routing lives in `astro.config.mjs`. The minimum is a list of locales and a default: ```js // astro.config.mjs import { defineConfig } from "astro/config"; export default defineConfig({ site: "https://example.com", i18n: { locales: ["en", "fr", "de"], defaultLocale: "en", }, }); ``` `defaultLocale` must be one of the entries in `locales`. Astro recommends lowercase codes with hyphens, such as `pt-br`. Set `site` as well: the sitemap and the absolute URL helpers need it. ### Choose a routing strategy with prefixDefaultLocale The `routing` object controls how URLs look: ```js i18n: { locales: ["en", "fr", "de"], defaultLocale: "en", routing: { prefixDefaultLocale: false, // default }, }, ``` - **`prefixDefaultLocale: false`** (the default): the default language has no prefix. `src/pages/about.astro` serves `/about/`, and French lives at `/fr/about/`. - **`prefixDefaultLocale: true`**: every language gets a prefix, so English moves to `/en/about/`. Unprefixed URLs return a 404 unless a fallback applies, and you still need a `src/pages/index.astro` for the root. - **`redirectToDefaultLocale: true`**: only meaningful with `prefixDefaultLocale: true`. It makes `/` redirect to `/en/`. It defaults to `false`. If you are upgrading from Astro 5, check this one: it used to default to `true`, so a site that relied on the old redirect needs it set explicitly ([Astro 6 upgrade guide](https://docs.astro.build/en/guides/upgrade-to/v6/)). If you need full control, such as detecting a language cookie, set `routing: "manual"`. That disables Astro's i18n middleware and lets you write your own with helpers like `redirectToDefaultLocale()` and `notFound()` from `astro:i18n`. You can't combine `"manual"` with the other routing options. ### Add a fallback for untranslated pages Client sites rarely launch with every page translated. Without a fallback, a missing page returns a 404. With one, Astro builds the missing page from another locale: ```js i18n: { locales: ["en", "fr", "de"], defaultLocale: "en", fallback: { de: "en" }, routing: { fallbackType: "redirect", // or "rewrite" }, }, ``` With `fallbackType: "redirect"` (the default), a visitor to a missing `/de/pricing/` is sent to the English page. With `"rewrite"`, the English content is shown at the German URL. Rewrite feels smoother for visitors, but it creates German URLs filled with English text. Keep those out of your hreflang tags and sitemap until the real translation exists. ### Custom locale paths and domains A locale can be an object when the URL segment should differ from the language code: ```js locales: ["en", "de", { path: "french", codes: ["fr", "fr-CA"] }], ``` The folder in `src/pages/` must then be named `french`, matching `path`. Astro also has `i18n.domains`, which maps a locale to its own domain (`fr: "https://fr.example.com"`). It requires `site`, `output: "server"` with no prerendered pages, and either the `@astrojs/node` or `@astrojs/vercel` adapter ([Astro i18n docs](https://docs.astro.build/en/guides/internationalization/#domains)). Cloudflare Workers is not supported for it. For most marketing sites that cost isn't worth it. Subfolders give you the same SEO signal and keep the site static. ## Structure translated pages and content Folder names must match your locale entries exactly. With `prefixDefaultLocale: false`, the default language sits at the root of `src/pages/`: ```text src/ pages/ index.astro -> / about.astro -> /about/ blog/[...slug].astro -> /blog/my-post/ fr/ index.astro -> /fr/ about.astro -> /fr/about/ blog/[...slug].astro -> /fr/blog/mon-article/ content/ blog/ en/ my-post.md fr/ mon-article.md i18n/ ui.ts utils.ts ``` Duplicating page files per language works for a handful of pages. When it grows, thin page files that pass the locale into a shared layout keep things manageable. All the markup stays in one component, and each locale page is a few lines. ### Translated content collections Keep one collection with a folder per language rather than one collection per language. With the `glob()` loader, the entry `id` includes the folder, so `src/content/blog/fr/mon-article.md` gets the id `fr/mon-article`: ```ts // src/content.config.ts import { defineCollection } from "astro:content"; import { glob } from "astro/loaders"; import { z } from "astro/zod"; const blog = defineCollection({ loader: glob({ pattern: "**/*.{md,mdx}", base: "./src/content/blog" }), schema: z.object({ title: z.string(), date: z.coerce.date(), translationKey: z.string(), }), }); export const collections = { blog }; ``` The `translationKey` field is the important part. It links `en/my-post` and `fr/mon-article` as versions of the same article, which you need for the language switcher, hreflang tags and translated slugs. Then filter by the locale prefix in the route. Here is the French blog route: ```astro --- // src/pages/fr/blog/[...slug].astro import { getCollection, render } from "astro:content"; export async function getStaticPaths() { const posts = await getCollection("blog", ({ id }) => id.startsWith("fr/")); return posts.map((post) => ({ params: { slug: post.id.replace(/^fr\//, "") }, props: { post }, })); } const { post } = Astro.props; const { Content } = await render(post); ---

{post.data.title}

``` If you use `prefixDefaultLocale: true`, you can replace the per-locale route files with a single `src/pages/[lang]/blog/[...slug].astro` that splits `post.id` into `lang` and `slug`. The [Astro i18n recipe](https://docs.astro.build/en/recipes/i18n/) shows that version. ## Translate UI strings with a typed dictionary Content collections cover page copy. Buttons, navigation labels, form text and footer links need a dictionary. Astro doesn't ship one, but a small typed object is enough for most sites: ```ts // src/i18n/ui.ts export const defaultLang = "en"; export const languages = { en: "English", fr: "Français", } as const; export const ui = { en: { "nav.home": "Home", "nav.about": "About", "cta.contact": "Get in touch", }, fr: { "nav.home": "Accueil", "nav.about": "À propos", "cta.contact": "Nous contacter", }, } as const; ``` ```ts // src/i18n/utils.ts import { ui, defaultLang } from "./ui"; type Lang = keyof typeof ui; type Key = keyof (typeof ui)[typeof defaultLang]; export function useTranslations(lang: Lang) { return function t(key: Key): string { return (ui[lang] as Record)[key] ?? ui[defaultLang][key]; }; } ``` In any component, read the locale from `Astro.currentLocale`. It returns the locale from the URL, or `defaultLocale` when there is no prefix, and it works on prerendered pages: ```astro --- import { useTranslations } from "@/i18n/utils"; const lang = (Astro.currentLocale ?? "en") as "en" | "fr"; const t = useTranslations(lang); --- {t("cta.contact")} ``` The fallback to the default language means a missing key shows English instead of breaking the build. That's forgiving, but it also hides gaps. Before launch, run a quick script that compares the keys in each language object. Menus deserve their own files. A navigation tree with dropdowns is easier to maintain as `menu.en.json` and `menu.fr.json` than as dictionary keys, especially when the French menu has a different structure or extra items. If translators prefer JSON files, keep the same keys in `src/i18n/en.json` and `src/i18n/fr.json` and import them into `ui.ts` (`import en from "./en.json"`). Astro imports JSON without extra setup, and the `t()` helper stays the same. ## Do you need an i18n library like i18next or Paraglide? For most brochure and business sites, no. Astro's routing plus a dictionary like the one above covers menus, buttons and form labels. A library starts to pay off when you need plurals, interpolated values in many strings, or translators working in a dedicated tool. What we found on npm on November 1, 2026: - **astro-i18next** has not had a release since March 2023 (`1.0.0-beta.21`). Don't start a new project on it. - **Paraglide JS** (`@inlang/paraglide-js` 2.29.3) is active, type-safe and tree-shakes unused messages. The old `@inlang/paraglide-astro` adapter is deprecated. The [Paraglide Astro guide](https://paraglidejs.com/astro) adds it as a Vite plugin with its own middleware, and its example uses `output: "server"` with the Node adapter, so check that fits a static site before you adopt it. - **i18next** itself (26.6.0) works in any JavaScript project, but you wire it into Astro components yourself. ## How do you build an Astro language switcher? A language switcher (or language selector) should send the visitor to the same page in another language. A list of links to each homepage is the most common shortcut, and it frustrates visitors who lose their place. For sites where every language uses the same slugs, the `astro:i18n` helpers do the work: ```astro --- // src/components/LanguageSwitcher.astro import { getRelativeLocaleUrl } from "astro:i18n"; import { languages } from "@/i18n/ui"; const current = Astro.currentLocale ?? "en"; // Strip the current locale prefix to get the shared path const path = Astro.url.pathname.replace(new RegExp(`^/${current}(?=/|$)`), ""); --- ``` `getRelativeLocaleUrl()` respects your `prefixDefaultLocale` setting, so it returns `/about/` for English and `/fr/about/` for French without extra logic. A few details matter: - Write each language name in its own language ("Français", "Deutsch"), not translated into the current one. - Avoid flags. Flags represent countries, not languages. - Use plain links, not a JavaScript redirect, so crawlers can follow them. - Don't auto-redirect visitors based on browser language. Suggest instead, and let them choose. `Astro.preferredLocale` is only available on on-demand rendered pages anyway. ## Translated slugs, not just translated locales Astro's routing translates the locale segment (`/fr/`), not the rest of the URL. If the client wants `/fr/a-propos/` instead of `/fr/about/`, you create that page and keep the mapping yourself. For static pages, the simplest approach is a route map: ```ts // src/i18n/routes.ts export const routes = { about: { en: "/about/", fr: "/fr/a-propos/" }, services: { en: "/services/", fr: "/fr/services/" }, contact: { en: "/contact/", fr: "/fr/contact/" }, } as const; ``` The file names in `src/pages/fr/` then follow the French slugs (`a-propos.astro`), and the switcher looks up the current page in this map instead of swapping prefixes. For content collections, use the `translationKey` field from earlier. To find the French version of an English post: ```ts const translations = await getCollection( "blog", ({ id, data }) => data.translationKey === post.data.translationKey && id !== post.id, ); ``` Each match gives you the locale (the first segment of `id`) and the slug (the rest), which is everything the switcher and hreflang tags need. Translated slugs are worth it when the site depends on local search traffic. For a small brochure site, identical slugs save real maintenance work, and Google handles them fine as long as the hreflang tags are correct. ## hreflang, canonical tags and the sitemap Search engines need three signals to treat your translations as alternatives rather than duplicates. ### hreflang tags in the head Every page should list all of its language versions, including itself, plus an `x-default` for visitors whose language you don't serve: ```astro --- // In your base layout head import { getAbsoluteLocaleUrl } from "astro:i18n"; const current = Astro.currentLocale ?? "en"; const path = Astro.url.pathname.replace(new RegExp(`^/${current}(?=/|$)`), ""); const locales = ["en", "fr"]; --- { locales.map((code) => ( )) } ``` This version assumes identical slugs. With translated slugs, build the list from your route map or `translationKey` lookup instead. Only output alternates for pages that actually exist in that language, which matters when you use a fallback. ### Canonical tags Each language version should be canonical to itself. A common mistake is pointing the French page's canonical at the English page, which tells search engines to ignore the French version entirely. ### The i18n sitemap The `@astrojs/sitemap` integration has an `i18n` option that writes the same alternates into the sitemap: ```js // astro.config.mjs import { defineConfig } from "astro/config"; import sitemap from "@astrojs/sitemap"; export default defineConfig({ site: "https://example.com", i18n: { locales: ["en", "fr"], defaultLocale: "en", }, integrations: [ sitemap({ i18n: { defaultLocale: "en", locales: { en: "en-US", fr: "fr-FR", }, }, }), ], }); ``` The keys are the URL segments, and the values are the language codes written to `hreflang`. Paths without a locale segment count as the default language. The build outputs `sitemap-index.xml`, and each URL entry lists `xhtml:link rel="alternate"` links for every locale. The integration pairs pages by the path after the locale segment, so `/about/` and `/fr/about/` are linked, but `/about/` and `/fr/a-propos/` are not. If you use translated slugs, rely on the in-page hreflang tags, or customize the entries with the integration's `serialize` option. ## Common mistakes on multilingual Astro sites These come up again and again on client projects: 1. **Forgetting ``.** Screen readers and search engines use it. Set it from `Astro.currentLocale` in the base layout. 2. **Hardcoded internal links.** A French page linking to `/contact/` drops the visitor back into English. Build links with `getRelativeLocaleUrl()` or your route map. 3. **Switchers that link to homepages.** Visitors lose their place. Link to the equivalent page. 4. **Canonicals pointing at the default language.** Each translation should be self-canonical. 5. **Indexing fallback content.** A rewritten fallback puts English text on a French URL. Keep it out of hreflang and the sitemap, or mark it `noindex` until it's translated. 6. **Untranslated metadata.** Titles, meta descriptions, Open Graph text, image alt text and form error messages all need translating, not just body copy. 7. **Inconsistent trailing slashes.** If hreflang URLs use `/fr/about` and the site serves `/fr/about/`, you're sending mixed signals. Match `trailingSlash` and `build.format` and generate URLs with the helpers. 8. **Locale-unaware dates and numbers.** Format them with `Intl.DateTimeFormat(lang)` and `Intl.NumberFormat(lang)` instead of hardcoded formats. 9. **Changing the URL strategy after launch.** Switching `prefixDefaultLocale` changes every URL. Decide before launch. ## Markdown, a CMS, or a translation workflow Markdown files in Git work well when developers or a technical client make the edits, the site has a few dozen pages, and translations change a few times a year. You get version control, review through pull requests, and no extra service to pay for. Move to a CMS or a translation management tool when: - Non-technical editors or external translators need to make changes without touching Git. - Content changes weekly and you need to track which translations are out of date. - There are more than two or three languages, and keeping track of gaps by hand is error-prone. - Legal or regulated copy needs an approval step before it goes live. Many headless CMSs support localized fields and can feed an Astro content collection through a loader, so the routing and SEO setup in this guide stays the same. Whatever you choose, keep the translation key or entry ID shared across languages. That link is what everything else depends on. Machine translation is fine for a first draft, but have a native speaker review anything client-facing, especially service descriptions and legal pages. ## What our themes already handle If you'd rather not wire this up from scratch, our themes ship with a multilingual structure already in place. [Taxo](https://getastrothemes.com/astro-themes/taxo/), for example, includes English, French and Arabic content, menus and routing. In practice: - Menus live in `src/config/menu.en.json` and `src/config/menu.fr.json`. - Language settings live in `src/config/language.json`, alongside the main `src/config/config.toml`. - Content is split into separate language folders. - If a project only needs one language, `npm run remove-multilingual` removes the extra language files, and `npm run generate-multilingual-content` brings them back later. [Lumio](https://getastrothemes.com/astro-themes/lumio/) follows the same pattern for IT and consulting sites, with localized menu files that support mega menus and dropdowns. [Lumio Lite](https://getastrothemes.com/astro-themes/lumio-lite/) is free and MIT licensed, with the same multilingual structure on a smaller page set (home, services, service single and 404). It's a good way to see how the setup works before buying anything. The paid themes also ship Arabic, and the Arabic pages render right to left. Each entry in `src/config/language.json` carries a `dir` of `ltr` or `rtl`, which `` reads. We opened the Arabic demos for [Lumio](https://lumio.getastrothemes.com/ar/) and [Taxo](https://taxo.getastrothemes.com/ar/) on November 9, 2026 and both served ``. We opened all 18 paid Arabic demos again on November 15, 2026, and each served `dir="rtl"`. Our list of [RTL ready Astro themes](https://getastrothemes.com/blog/rtl-ready-astro-themes/) covers them with their Arabic demos and the free alternatives. Limitations, stated plainly: a fourth language means adding its content, menu file and translations yourself. The free Lite themes are English and French only. The Arabic text in the paid themes is a machine translation, included so the right-to-left layout has real text in it, so have a native speaker review it before launch. Translated slugs and a translation workflow are still up to you. ## Next step Start with the decisions table: URL structure, default-language prefix and slug strategy. Then add the `i18n` config, one translated page and the language switcher, and check the hreflang output in your browser's page source before translating the rest. If you want to skip the scaffolding, download [Lumio Lite](https://getastrothemes.com/astro-themes/lumio-lite/) from our [free Astro themes](https://getastrothemes.com/free-astro-themes-templates/#free-templates) to see a working multilingual setup. For client work, browse the [full theme catalog](https://getastrothemes.com/themes/) or the [All Access Pass](https://getastrothemes.com/all-access-pass/), and check the [license terms](https://getastrothemes.com/license/) for how many client projects each plan covers. When the site is ready, our guide to [deploying Astro on Cloudflare](https://getastrothemes.com/blog/deploy-astro-cloudflare/) covers the last step.