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 and @astrojs/sitemap docs on November 1, 2026 (Astro 7.4.4). For an Astro i18n example to clone, Lumio Lite on GitHub, our free MIT theme, keeps content in english and french folders; the live demo 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:
// 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:
i18n: {
locales: ["en", "fr", "de"],
defaultLocale: "en",
routing: {
prefixDefaultLocale: false, // default
},
},
prefixDefaultLocale: false(the default): the default language has no prefix.src/pages/about.astroserves/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 asrc/pages/index.astrofor the root.redirectToDefaultLocale: true: only meaningful withprefixDefaultLocale: true. It makes/redirect to/en/. It defaults tofalse. If you are upgrading from Astro 5, check this one: it used to default totrue, so a site that relied on the old redirect needs it set explicitly (Astro 6 upgrade guide).
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:
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:
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). 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/:
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:
// 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:
---
// 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);
---
<h1>{post.data.title}</h1>
<Content />
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 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:
// 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;
// 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<string, string>)[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:
---
import { useTranslations } from "@/i18n/utils";
const lang = (Astro.currentLocale ?? "en") as "en" | "fr";
const t = useTranslations(lang);
---
<a href="/contact/">{t("cta.contact")}</a>
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-js2.29.3) is active, type-safe and tree-shakes unused messages. The old@inlang/paraglide-astroadapter is deprecated. The Paraglide Astro guide adds it as a Vite plugin with its own middleware, and its example usesoutput: "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:
---
// 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}(?=/|$)`), "");
---
<nav aria-label="Language">
<ul>
{
Object.entries(languages).map(([code, label]) => (
<li>
<a
href={getRelativeLocaleUrl(code, path)}
hreflang={code}
lang={code}
aria-current={code === current ? "true" : undefined}
>
{label}
</a>
</li>
))
}
</ul>
</nav>
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.preferredLocaleis 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:
// 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:
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:
---
// 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"];
---
<html lang={current}>
<head>
{
locales.map((code) => (
<link
rel="alternate"
hreflang={code}
href={getAbsoluteLocaleUrl(code, path)}
/>
))
}
<link
rel="alternate"
hreflang="x-default"
href={getAbsoluteLocaleUrl("en", path)}
/>
<link rel="canonical" href={new URL(Astro.url.pathname, Astro.site)} />
</head>
</html>
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:
// 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:
- Forgetting
<html lang>. Screen readers and search engines use it. Set it fromAstro.currentLocalein the base layout. - Hardcoded internal links. A French page linking to
/contact/drops the visitor back into English. Build links withgetRelativeLocaleUrl()or your route map. - Switchers that link to homepages. Visitors lose their place. Link to the equivalent page.
- Canonicals pointing at the default language. Each translation should be self-canonical.
- Indexing fallback content. A rewritten fallback puts English text on a French URL. Keep it out of hreflang and the sitemap, or mark it
noindexuntil itโs translated. - Untranslated metadata. Titles, meta descriptions, Open Graph text, image alt text and form error messages all need translating, not just body copy.
- Inconsistent trailing slashes. If hreflang URLs use
/fr/aboutand the site serves/fr/about/, youโre sending mixed signals. MatchtrailingSlashandbuild.formatand generate URLs with the helpers. - Locale-unaware dates and numbers. Format them with
Intl.DateTimeFormat(lang)andIntl.NumberFormat(lang)instead of hardcoded formats. - Changing the URL strategy after launch. Switching
prefixDefaultLocalechanges 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, for example, includes English, French and Arabic content, menus and routing. In practice:
- Menus live in
src/config/menu.en.jsonandsrc/config/menu.fr.json. - Language settings live in
src/config/language.json, alongside the mainsrc/config/config.toml. - Content is split into separate language folders.
- If a project only needs one language,
npm run remove-multilingualremoves the extra language files, andnpm run generate-multilingual-contentbrings them back later.
Lumio follows the same pattern for IT and consulting sites, with localized menu files that support mega menus and dropdowns. 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 <html dir> reads. We opened the Arabic demos for Lumio and Taxo on November 9, 2026 and both served <html lang="ar" dir="rtl">. We opened all 18 paid Arabic demos again on November 15, 2026, and each served dir="rtl". Our list of 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 from our free Astro themes to see a working multilingual setup. For client work, browse the full theme catalog or the All Access Pass, and check the license terms for how many client projects each plan covers. When the site is ready, our guide to deploying Astro on Cloudflare covers the last step.