Skip to content
Home / Blog / Astro i18n: Build and manage multilingual Astro websites

Astro i18n: Build and manage multilingual Astro websites

Developer resources
Helmut Juskewycz
CEO & Co-Founder

Last updated

11/19/2026

Read time

14 min

Best for

Developers

Illustration of an Astro website surrounded by icons for multilingual content, translation, website structure, and localization workflows.

Astro i18n gives you a solid foundation for multilingual websites: locale-aware routing, URL helpers, fallback rules, and browser language detection, all built into the framework. What it leaves to you is the rest of Astro.js localization: where translations live, how UI strings get rendered, how content stays in sync across languages, and how search engines discover each version of a page.

This tutorial walks through that full picture. You will configure locales and routing, set up translation files, translate static and dynamic content, build a language switcher, and add hreflang tags. The last part covers how to keep translations manageable once your site grows beyond two or three languages.

The examples assume a working Astro project and basic familiarity with components, layouts, and content collections.

What is Astro i18n and how does it work?

Astro i18n is the framework’s built-in internationalization routing API, available since Astro 4. You declare your supported locales and a default locale in astro.config.mjs, and Astro maps those locales to your file-based routes in src/pages/.

Under the hood, Astro runs an i18n middleware that is placed first in the middleware chain. It waits until your own middleware and pages have produced a response, then checks whether a localized URL matches a valid route, applies redirects, and handles fallbacks.

The astro:i18n virtual module exposes helpers such as getRelativeLocaleUrl(), getAbsoluteLocaleUrl(), and getAbsoluteLocaleUrlList(). Every page also has access to Astro.currentLocale, and on-demand rendered pages get Astro.preferredLocale from the browser’s Accept-Language header.

What Astro handles and what you build yourself

Astro’s i18n API is deliberately focused on routing. It does not ship a translation function, a message format, or a content sync mechanism. The table below shows where the boundary sits.

Concern

Built into Astro i18n

Your responsibility

Locale configuration

locales, defaultLocale, custom path and codes

Choosing locale codes and URL structure

Routing

Prefixed URLs, prefixDefaultLocale, domain mapping (SSR)

Folder structure under src/pages/

Missing pages

fallback with redirect or rewrite

Deciding which locales fall back to which

URL generation

getRelativeLocaleUrl(), getAbsoluteLocaleUrlList()

Using helpers consistently in links

Locale detection

Astro.currentLocale, Astro.preferredLocale (SSR)

Redirect or suggestion logic

UI string translation

Not included

Dictionary files and a t() helper

Content translation

Not included

Content collections per locale

hreflang tags

Not included (URLs are available)

Rendering <link rel="alternate"> in the head

Translation workflow

Not included

TMS, reviews, automation

In practice, most production setups combine Astro’s routing with a lightweight dictionary layer and content collections. Some teams add libraries such as i18next or Paraglide JS for more advanced message formatting, but the native approach covers a large share of real projects.

Step 1: Set up locales and i18n routing in Astro

A typical i18n Astro setup starts with three decisions: which locales you support, which one is the default, and whether the default locale gets a URL prefix. Here is a configuration for English, German, and French:

// astro.config.mjs
import { defineConfig } from "astro/config";

export default defineConfig({
  site: "https://example.com",
  trailingSlash: "always",
  i18n: {
    locales: ["en", "de", "fr"],
    defaultLocale: "en",
    routing: {
      prefixDefaultLocale: true,
      redirectToDefaultLocale: true,
    },
  },
});

The site value matters more than it looks. Absolute URL helpers, canonical tags, and hreflang links all depend on it, so set it before you start building localized pages. Set trailingSlash explicitly as well. The i18n URL helpers follow it, and with the default ("ignore") they can return URLs without a trailing slash while your static pages are served with one. A canonical URL and an hreflang URL that differ by one slash count as two different URLs. Note that with "always", the dev server returns a 404 for URLs typed without the slash, such as /de/about, which is one more reason to build links with the i18n helpers.

Prefixed or unprefixed default locale?

With prefixDefaultLocale: false (the default), English pages live at /about/ and other languages at /de/about/. With true, every locale is prefixed, including /en/about/.

Full prefixing is usually easier to maintain. Every language follows the same folder structure, your code never needs a special case for the default locale, and adding a new default later does not break URLs. If you are migrating an existing English site and want to keep its URLs, unprefixed is the safer choice.

When you prefix the default locale, src/pages/index.astro is still required. With redirectToDefaultLocale: true, that root page redirects to /en/. Default redirect behavior has changed between major Astro versions, so set this option explicitly instead of relying on the default.

Folder structure

You can create one physical folder per locale, but that duplicates every page. A dynamic [locale] segment keeps a single template per page:

src/
├── pages/
│   ├── index.astro          # redirects to /en/
│   └── [locale]/
│       ├── index.astro
│       ├── about.astro
│       └── blog/
│           ├── index.astro
│           └── [...slug].astro
├── i18n/
│   ├── ui.ts
│   └── utils.ts
└── content/
    └── blog/
        ├── en/
        ├── de/
        └── fr/

Each page under [locale] exports getStaticPaths() to generate one route per language (required for prerendered dynamic routes):

---
// src/pages/[locale]/about.astro
import Layout from "../../layouts/Layout.astro";

export function getStaticPaths() {
  return ["en", "de", "fr"].map((locale) => ({ params: { locale } }));
}

const locale = Astro.currentLocale;
---
<Layout title="About">
  <h1>About ({locale})</h1>
</Layout>

To avoid repeating the locale list, import it from one place instead. Step 2 creates src/i18n/ui.ts, which exports it as locales.

Fallbacks for untranslated pages

Astro’s i18n.fallback option serves another locale’s content when a page does not exist, for example fallback: { fr: "en" }. By default, Astro redirects. Setting routing.fallbackType: "rewrite" keeps the French URL and renders the English content in place. See the Astro i18n routing guide for the full set of options.

Use rewrites carefully. They avoid a broken experience, but they also publish English content under a French URL, which can confuse users and search engines if it stays that way for long.

This option is meant for projects with a physical folder per locale (src/pages/fr/), where a page can be missing. With the dynamic [locale] segment used in this tutorial, every route comes from getStaticPaths(), so no page is ever missing. Adding fallback to this setup only makes Astro log a route-conflict warning for every page, which is why the config above leaves it out. For dynamic routes, generate fallback pages in getStaticPaths() instead, as shown in Step 3.

Step 2: Create and manage translation files

UI strings such as navigation labels, buttons, and form messages belong in translation files, separate from your templates. The official Astro i18n recipe keeps them in a TypeScript object. That works for small sites, but JSON files per locale are easier to hand off to translators and to sync with a translation management system.

One JSON file per locale

src/i18n/locales/
├── en.json
├── de.json
└── fr.json

src/i18n/locales/en.json:

{
  "nav.home": "Home",
  "nav.about": "About",
  "nav.blog": "Blog",
  "hero.title": "Ship multilingual sites faster",
  "blog.readingTime": "{minutes} min read",
  "footer.language": "Language"
}

src/i18n/locales/de.json:

{
  "nav.home": "Startseite",
  "nav.about": "Über uns",
  "nav.blog": "Blog",
  "hero.title": "Mehrsprachige Websites schneller ausliefern",
  "blog.readingTime": "{minutes} Min. Lesezeit",
  "footer.language": "Sprache"
}

Flat, namespaced keys (nav.home) are easy to search, diff, and review. Nested objects work too, but keep one convention across the project.

A typed translation helper

The helper below loads the dictionaries, falls back to the default locale for missing keys, and supports simple placeholder interpolation:

// src/i18n/ui.ts
import en from "./locales/en.json";
import de from "./locales/de.json";
import fr from "./locales/fr.json";

export const locales = ["en", "de", "fr"] as const;
export type Locale = (typeof locales)[number];
export const defaultLocale: Locale = "en";

export const languageNames: Record<Locale, string> = {
  en: "English",
  de: "Deutsch",
  fr: "Français",
};

export const dictionaries = { en, de, fr } as const;
export type TranslationKey = keyof typeof en;
// src/i18n/utils.ts
import { dictionaries, defaultLocale, type Locale, type TranslationKey } from "./ui";

export function useTranslations(locale: Locale) {
  return function t(key: TranslationKey, vars: Record<string, string | number> = {}) {
    const dict = dictionaries[locale] as Record<string, string>;
    const fallback = dictionaries[defaultLocale] as Record<string, string>;
    let text = dict[key] ?? fallback[key] ?? key;

    for (const [name, value] of Object.entries(vars)) {
      text = text.replaceAll(`{${name}}`, String(value));
    }
    return text;
  };
}

Typing TranslationKey against the English file means a typo like t("nav.hom") is flagged in your editor and by astro check (astro build does not type-check, so add astro check to CI). English acts as the source of truth: new keys get added there first, and other locales fall back to it until translated.

Keep the source file authoritative

A few habits keep translation files healthy as the project grows:

  • Add keys only to the source locale in code. Let your translation workflow create entries in the other files.

  • Never reuse a key for different meanings. “Save” on a form and “Save 20%” on a pricing page need separate keys.

  • Avoid concatenating strings in templates. t("cart.items", { count }) translates well, while count + " " + t("items") breaks word order in many languages.

  • For plurals, use Intl.PluralRules or a library with ICU message support rather than if (count === 1) checks.

Step 3: Translate static and dynamic content

Astro translation work falls into two categories. Static content means UI strings and fixed page copy that live in your dictionaries. Dynamic content means blog posts, docs pages, product data, or anything loaded from Markdown, a CMS, or an API.

Static content in components

With the helper in place, translating a component is straightforward:

---
// src/components/Header.astro
import { getRelativeLocaleUrl } from "astro:i18n";
import { useTranslations } from "../i18n/utils";
import { defaultLocale, type Locale } from "../i18n/ui";

const locale = (Astro.currentLocale ?? defaultLocale) as Locale;
const t = useTranslations(locale);
---
<nav>
  <a href={getRelativeLocaleUrl(locale, "")}>{t("nav.home")}</a>
  <a href={getRelativeLocaleUrl(locale, "about")}>{t("nav.about")}</a>
  <a href={getRelativeLocaleUrl(locale, "blog")}>{t("nav.blog")}</a>
</nav>

Use getRelativeLocaleUrl() for every internal link instead of building paths by hand. If you later switch prefixDefaultLocale or add a custom locale path, the links stay correct.

For dates, numbers, and currencies, rely on the Intl APIs with the current locale rather than storing formatted values in translation files:

new Intl.DateTimeFormat(locale, { dateStyle: "long" }).format(post.data.pubDate);

An Astro i18n example with content collections

For long-form content, keep one file per language in a content collection, organized by locale folder. A shared translationKey in the frontmatter links the language versions of the same article:

---
# src/content/blog/de/astro-i18n-guide.md
title: "Astro i18n Leitfaden"
pubDate: 2026-10-01
translationKey: "astro-i18n-guide"
---

Define the collection with the glob() loader so the locale folder becomes part of each entry’s id:

// 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", base: "./src/content/blog" }),
  schema: z.object({
    title: z.string(),
    pubDate: z.coerce.date(),
    translationKey: z.string(),
  }),
});

export const collections = { blog };

Then generate one route per post and locale. Entry IDs look like de/astro-i18n-guide, so the first segment is the locale and the rest is the slug:

---
// src/pages/[locale]/blog/[...slug].astro
import { getCollection, render } from "astro:content";
import { getRelativeLocaleUrl } from "astro:i18n";
import Layout from "../../../layouts/Layout.astro";

export async function getStaticPaths() {
  const posts = await getCollection("blog");
  return posts.map((post) => {
    const [locale, ...rest] = post.id.split("/");
    return {
      params: { locale, slug: rest.join("/") },
      props: { post },
    };
  });
}

const { post } = Astro.props;
const { Content } = await render(post);

const siblings = await getCollection("blog", ({ data }) =>
  data.translationKey === post.data.translationKey
);
const alternates = Object.fromEntries(
  siblings.map((entry) => {
    const [locale, ...rest] = entry.id.split("/");
    return [locale, getRelativeLocaleUrl(locale, `blog/${rest.join("/")}`)];
  })
);
---
<Layout title={post.data.title} alternates={alternates}>
  <h1>{post.data.title}</h1>
  <Content />
</Layout>

This approach only builds pages that exist. A German post without a French version simply has no /fr/ route, which is better than generating a page with mixed-language content.

If you prefer to show the English version at the French URL until a translation is ready, add those routes in the same getStaticPaths() function:

// locales: the shared list from src/i18n/ui.ts
const englishPosts = posts.filter((p) => p.id.startsWith("en/"));

const fallbackRoutes = englishPosts.flatMap((post) => {
  const slug = post.id.slice("en/".length);
  return locales
    .filter((locale) => !posts.some(
      (p) => p.id.startsWith(`${locale}/`) && p.data.translationKey === post.data.translationKey
    ))
    .map((locale) => ({
      params: { locale, slug },
      props: { post, isFallback: true },
    }));
});

The check compares translationKey, not the slug. A slug comparison would treat the German preisleitfaden post as a missing translation of pricing-guide and publish a duplicate English page at /de/blog/pricing-guide/.

Return fallbackRoutes alongside the translated routes. Mark fallback pages with a short notice and <meta name="robots" content="noindex"> so readers and search engines do not mistake them for real translations. Also wrap the borrowed content in an element with lang="en". The layout sets the page language from the URL, so without it the page declares French while the text is English.

The header links to a blog index in each language, so add a listing page that filters the collection by locale:

---
// src/pages/[locale]/blog/index.astro
import { getCollection } from "astro:content";
import { getRelativeLocaleUrl } from "astro:i18n";
import Layout from "../../../layouts/Layout.astro";
import { locales, type Locale } from "../../../i18n/ui";

export function getStaticPaths() {
  return locales.map((locale) => ({ params: { locale } }));
}

const locale = Astro.currentLocale as Locale;
const posts = await getCollection("blog", ({ id }) => id.startsWith(`${locale}/`));
---
<Layout title="Blog">
  <ul>
    {posts.map((post) => (
      <li>
        <a href={getRelativeLocaleUrl(locale, `blog/${post.id.slice(locale.length + 1)}`)}>
          {post.data.title}
        </a>
      </li>
    ))}
  </ul>
</Layout>

Content from a CMS or API

Most headless CMSs support localized fields. Pass the current locale into your query and keep the URL structure identical across languages:

const res = await fetch(`https://cms.example.com/api/pages/${slug}?locale=${locale}`);
const page = await res.json();

For interactive islands (React, Vue, Svelte), resolve translated strings on the server and pass them as props. Shipping every dictionary to the browser adds weight that most pages never use.

Step 4: Implement a language switcher

A good language switcher keeps users on the same page when they change languages. Sending someone who switches to French on /de/blog/astro-i18n-guide/ to the French homepage instead of the French article is a common and avoidable frustration.

A path-preserving switcher

For pages that share the same slug across languages, strip the current locale from the path and rebuild it for each target locale:

---
// src/components/LanguageSwitcher.astro
import { getRelativeLocaleUrl } from "astro:i18n";
import { locales, languageNames, defaultLocale, type Locale } from "../i18n/ui";

interface Props {
  // Pass on pages whose slugs differ per language (see below)
  alternates?: Partial<Record<Locale, string>>;
}

const { alternates } = Astro.props;
const current = (Astro.currentLocale ?? defaultLocale) as Locale;

// "/de/about/" -> "about/"
const pathWithoutLocale = Astro.url.pathname
  .replace(new RegExp(`^/${current}(/|$)`), "")
  .replace(/^\//, "");

const links = locales.map((locale) => ({
  locale,
  label: languageNames[locale],
  href: alternates
    ? // no translation for this locale: link to its homepage instead of a 404
      alternates[locale] ?? getRelativeLocaleUrl(locale, "")
    : getRelativeLocaleUrl(locale, pathWithoutLocale),
}));
---
<nav aria-label="Language">
  <ul>
    {links.map(({ locale, label, href }) => (
      <li>
        <a
          href={href}
          hreflang={locale}
          lang={locale}
          aria-current={locale === current ? "page" : undefined}
        >
          {label}
        </a>
      </li>
    ))}
  </ul>
</nav>

A few details worth noting:

  • Language names are shown in their own language (“Deutsch”, not “German”). Users looking for their language recognize it faster that way.

  • The lang attribute on each link helps screen readers pronounce the label correctly.

  • Avoid flags. Flags represent countries, and many languages span several countries.

Handling localized slugs

If translated posts use different slugs (/en/blog/pricing-guide/ and /de/blog/preisleitfaden/), path replacement will produce broken links. The alternates prop solves this. On the post page, look up all entries with the same translationKey and pass their URLs to the switcher:

const siblings = await getCollection("blog", ({ data }) =>
  data.translationKey === post.data.translationKey
);

const alternates = Object.fromEntries(
  siblings.map((entry) => {
    const [locale, ...rest] = entry.id.split("/");
    return [locale, getRelativeLocaleUrl(locale, `blog/${rest.join("/")}`)];
  })
);

The same alternates map is useful again in the next step, where it feeds your hreflang tags.

Should you redirect based on browser language?

On server-rendered pages, Astro.preferredLocale tells you which supported language the browser prefers. Use it to show a dismissible suggestion banner rather than an automatic redirect. Forced redirects frustrate users who deliberately opened a specific language, and they can prevent crawlers from reaching all versions of your site.

Astro matches browser languages only against the codes in your config. With plain locales like "fr", a browser that asks for fr-CA is not matched to French. To cover regional variants, define the locale with codes:

locales: ["en", "de", { path: "fr", codes: ["fr", "fr-CA", "fr-FR"] }],

Astro.preferredLocale then returns the matched code (fr-CA), and getPathByLocale() from astro:i18n turns it into the URL segment (fr). Astro.currentLocale keeps returning fr, so the rest of the code in this tutorial works unchanged.

Step 5: Multilingual SEO for Astro i18n sites

A multilingual site needs a stable URL per language and hreflang annotations that connect the language versions. Add a lang attribute on each page too. Google detects language from visible content rather than from lang, but browsers, screen readers, and some other search engines use it. Astro i18n gives you the URLs through routing. The hreflang tags and lang attribute belong in your base layout.

Localized URLs

Subdirectories (/de/, /fr/) are the most common choice for Astro sites. They work with static builds, keep all languages on one domain, and need no special hosting. Astro also supports per-locale domains through i18n.domains, but only for server-rendered projects with a supported adapter.

If you want localized slugs (/de/ueber-uns/ instead of /de/about/), plan for them early. They help users and click-through rates in some markets, but they require the alternates mapping shown in Step 4 for every page type.

Rendering hreflang tags

Add the tags in your base layout. For pages that share slugs across languages, getAbsoluteLocaleUrl() builds each alternate URL from your site setting:

---
// src/layouts/Layout.astro
import { getAbsoluteLocaleUrl } from "astro:i18n";
import { locales, defaultLocale, type Locale } from "../i18n/ui";

interface Props {
  title: string;
  alternates?: Partial<Record<Locale, string>>;
}

const { title, alternates } = Astro.props;
const current = (Astro.currentLocale ?? defaultLocale) as Locale;
const path = Astro.url.pathname
  .replace(new RegExp(`^/${current}(/|$)`), "")
  .replace(/^\//, "");

const hreflangs = alternates
  ? Object.entries(alternates).map(([locale, href]) => ({
      locale,
      href: new URL(href!, Astro.site).href,
    }))
  : locales.map((locale) => ({ locale, href: getAbsoluteLocaleUrl(locale, path) }));

const xDefault = hreflangs.find((h) => h.locale === defaultLocale)?.href;
---
<html lang={current}>
  <head>
    <title>{title}</title>
    <link rel="canonical" href={new URL(Astro.url.pathname, Astro.site).href} />
    {hreflangs.map(({ locale, href }) => (
      <link rel="alternate" hreflang={locale} href={href} />
    ))}
    {xDefault && <link rel="alternate" hreflang="x-default" href={xDefault} />}
  </head>
  <body>
    <slot />
  </body>
</html>

The rules from Google’s localized versions guide apply here. Each page must reference itself and every other language version, the references must be reciprocal, and URLs must be absolute. The x-default entry tells search engines which version to show when no language matches.

Common hreflang mistakes in Astro projects

  • Pointing hreflang at fallback pages. If /fr/blog/pricing-guide/ is a fallback page showing the English post (Step 3), do not list it as the French alternate. Pass an explicit alternates map that only includes real translations.

  • Canonical tags pointing to the default locale. Each language version should be canonical to itself. A German page with a canonical pointing to English tells search engines to ignore the German one.

  • Missing site config. Without it, absolute URL helpers cannot produce full URLs.

Localized sitemaps

The @astrojs/sitemap integration accepts an i18n option that adds xhtml:link alternates to each sitemap entry:

// astro.config.mjs
import sitemap from "@astrojs/sitemap";

export default defineConfig({
  site: "https://example.com",
  integrations: [
    sitemap({
      i18n: {
        defaultLocale: "en",
        locales: { en: "en", de: "de", fr: "fr" },
      },
    }),
  ],
});

Hreflang in the HTML head and in the sitemap are equivalent signals. Using both is fine as long as they agree. The values in the sitemap’s locales map become the hreflang codes, so keep them identical to the codes your layout outputs.

The sitemap builds its alternates from URL patterns, so it lists every page it finds under a locale prefix. That includes fallback pages you generate in getStaticPaths() (Step 3) and, since Astro 6.1, pages created by Astro’s own i18n.fallback routing when fallbackType is set to "rewrite". Use the integration’s filter option to exclude fallback URLs and the redirecting root page (/). Otherwise the sitemap advertises English content as the French alternate, which contradicts the hreflang rule above.

The sitemap also links pages only when their paths are identical apart from the locale prefix. Pages with localized slugs (/de/blog/preisleitfaden/) get no alternates at all, so the sitemap and your head tags disagree. With prefixDefaultLocale: true, it also treats the root / as English, which adds a second en entry to every homepage’s alternates. If you use localized slugs, rely on the hreflang tags in your layout and leave out the sitemap’s i18n option.

Step 6: Manage Astro translations with a TMS like LingoHub

After the initial setup, most ongoing i18n work is translation: every new feature adds keys, every copy change invalidates existing translations, and every new language multiplies the work. Editing JSON files by hand and sending spreadsheets to translators works for a while, then it starts to slow releases down.

A translation management system (TMS) moves that work out of your codebase without changing how your Astro project reads translations. Your app still imports en.json and de.json. The TMS handles how those files get filled.

How the workflow fits together

With LingoHub, a typical setup for the project in this tutorial looks like this:

  • Connect the repository. The GitHub integration (GitLab, Bitbucket, and Azure DevOps are also supported) syncs src/i18n/locales/en.json as the source file and maps de.json and fr.json as targets.

  • Developers add keys as usual. A pull request adds "pricing.cta": "Start free trial" to en.json. After merge, LingoHub picks up the new and changed strings.

  • AI translation drafts the new strings. LINA, LingoHub’s AI translation agent, translates new segments using your glossary, translation memory, and style guide as context. You decide whether LINA only suggests, translates automatically, or also handles checks and approval.

  • Reviewers check what needs a human. Translators and reviewers work in the web editor, where they see glossary terms, previous approved translations, and screenshots for context.

  • Translations come back as a pull request. LingoHub pushes the updated target files to your repository, so translations go through the same review and CI pipeline as code.

The localization workflow features page covers the configuration options in more detail.

What a TMS adds over files in Git

Task

JSON files in Git only

With LingoHub

Detecting new or changed strings

Manual diffing or custom scripts

Automatic on repository sync

First-draft translations

Copy-paste into a translation tool

AI translation with glossary and memory context

Consistent terminology

Relies on translator memory

Shared glossary applied to every string

Reusing existing translations

Not tracked

Translation memory suggests approved matches

Placeholder and formatting errors

Often caught late, sometimes in production

Automated quality checks before delivery

Translator access

Repository access or file handoffs

Web editor with context, no Git needed

Progress per locale

Unknown until you check each file

Status per segment and language

Protecting placeholders and keys

Placeholders like {minutes} from Step 2 are a frequent source of bugs. A translator who writes {Minuten} breaks interpolation silently. LingoHub’s quality checks flag missing or altered placeholders before translations reach your repository.

It is still worth adding a lightweight CI guard on your side. This script fails the build on mismatched placeholders and warns about missing keys:

// scripts/check-translations.ts
import en from "../src/i18n/locales/en.json";
import de from "../src/i18n/locales/de.json";
import fr from "../src/i18n/locales/fr.json";

const targets = { de, fr } as Record<string, Record<string, string>>;
const placeholders = (s: string) => (s.match(/\{\w+\}/g) ?? []).sort().join(",");
let errors = 0;

for (const [locale, dict] of Object.entries(targets)) {
  for (const [key, source] of Object.entries(en)) {
    const value = dict[key];
    if (value === undefined) {
      console.warn(`[${locale}] missing: ${key}`);
      continue; // falls back to English at runtime
    }
    if (placeholders(value) !== placeholders(source)) {
      console.error(`[${locale}] placeholder mismatch: ${key}`);
      errors++;
    }
  }
}

process.exit(errors > 0 ? 1 : 0);

Missing keys only warn, because the t() helper falls back to English. Placeholder mismatches fail the build, because they produce visibly broken text.

Run it in CI with npx tsx scripts/check-translations.ts, before astro build.

Astro i18n best practices and common pitfalls

Most i18n problems show up months after launch, when the site has more pages, more languages, and more people editing content. These habits prevent the common ones:

  • Define locales once. Keep the locale list in src/i18n/ui.ts and import it into getStaticPaths(), the switcher, and the layout. Three hardcoded arrays will drift apart.

  • Generate every internal link with astro:i18n helpers. Handwritten paths break the moment you change routing options.

  • Leave room for text expansion. German and French strings often run 20 to 35 percent longer than English. Test layouts with your longest language, not your source language.

  • Plan for right-to-left languages early. If Arabic or Hebrew is on the roadmap, set dir="rtl" on <html> per locale and use CSS logical properties (margin-inline-start) instead of margin-left.

  • Keep translation keys stable. Renaming hero.title to home.hero.title orphans every existing translation unless your TMS migrates them.

  • Avoid long-lived fallbacks. Fallback content is a stopgap. Track untranslated pages and close the gap, or remove the locale from those routes.

  • Translate metadata too. Page titles, meta descriptions, Open Graph tags, and image alt text are easy to miss and visible in search results.

FAQ

Does Astro have built-in i18n support?

Yes. Since Astro 4, the framework includes i18n routing configured through the i18n key in astro.config.mjs. It covers locale routing, URL helpers, fallbacks, and browser language detection. It does not include a translation function or message format, so you add a dictionary layer or a library for UI strings.

Should I use a library like Paraglide JS or i18next with Astro i18n?

For most marketing sites, docs, and blogs, Astro’s native routing plus JSON dictionaries is enough. A library makes sense when you need ICU plural and gender rules, tree-shaken messages for client-side islands, or a large number of strings. Both approaches can read JSON message files, so the same TMS workflow applies.

How do I translate content collections in Astro?

Store one file per language in locale subfolders (src/content/blog/en/, src/content/blog/de/), use the glob() loader, and read the locale from each entry’s id in getStaticPaths(). A shared translationKey in the frontmatter links language versions for the switcher and hreflang tags.

Does Astro i18n generate hreflang tags automatically?

No. Astro provides getAbsoluteLocaleUrl() and getAbsoluteLocaleUrlList() to build the URLs, but you render the <link rel="alternate" hreflang> tags in your layout. The @astrojs/sitemap integration can add hreflang alternates to your sitemap with its i18n option.

Can I use Astro i18n with server-side rendering?

Yes. Routing and helpers work for static and on-demand rendered pages. Some features only work with on-demand rendering: Astro.preferredLocale and Astro.preferredLocaleList need the request headers, and per-locale domains via i18n.domains require server output with a supported adapter. If you switch to output: "server", add export const prerender = true to the pages in this tutorial that use getStaticPaths(). Otherwise Astro ignores getStaticPaths(), and the blog post pages fail with a server error because their props are missing.

Wrapping up

Astro i18n handles the routing layer well: locale-prefixed URLs, link helpers, fallbacks, and locale detection come with the framework. A small amount of your own code covers the rest. That means JSON dictionaries with a typed t() helper, content collections organized by locale, a switcher that keeps users on the same page, and hreflang tags in your base layout.

Translation work grows with your site. Keeping source files authoritative, protecting placeholders, and moving translation work into a TMS such as LingoHub keeps new languages and new features from turning into a manual sync problem.

For the full API reference, see the Astro internationalization guide and the astro:i18n module reference.

Related articles