Black Friday: 50% off Pro All Access until Nov 30
All articles
Guides 11 min read

Astro i18n: How to Build a Multi-Language Website

Set up Astro i18n for a multi-language site: routing, translated pages and collections, UI strings, a language switcher, hreflang tags and an i18n sitemap.

Published

Updated

On this page

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.

DecisionOptionsGood default
URL structureSubfolders (/fr/), subdomains, separate domainsSubfolders: 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
SlugsSame slug everywhere vs translated slugsSame 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.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).

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-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 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:

---
// 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.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:

// 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:

  1. Forgetting <html lang>. 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, 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 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.

Frequently asked questions

Does Astro support multilingual sites without a plugin?

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.

Should the default language have a URL prefix like /en/?

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.

Can I use translated slugs like /fr/a-propos/ in Astro?

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.

Does the Astro sitemap integration add hreflang links?

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.

Can I put each language on its own domain with Astro?

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.

Do Getastrothemes themes support right-to-left languages?

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.

Share this article

Every premium theme.
Future releases included. $99.

Premium theme collection preview
Premium theme collection preview