Table of content
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 |
| Choosing locale codes and URL structure |
Routing | Prefixed URLs, | Folder structure under |
Missing pages |
| Deciding which locales fall back to which |
URL generation |
| Using helpers consistently in links |
Locale detection |
| Redirect or suggestion logic |
UI string translation | Not included | Dictionary files and a |
Content translation | Not included | Content collections per locale |
hreflang tags | Not included (URLs are available) | Rendering |
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, whilecount + " " + t("items")breaks word order in many languages.For plurals, use
Intl.PluralRulesor a library with ICU message support rather thanif (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
langattribute 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 explicitalternatesmap 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
siteconfig. 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.jsonas the source file and mapsde.jsonandfr.jsonas targets.Developers add keys as usual. A pull request adds
"pricing.cta": "Start free trial"toen.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.tsand import it intogetStaticPaths(), the switcher, and the layout. Three hardcoded arrays will drift apart.Generate every internal link with
astro:i18nhelpers. 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 ofmargin-left.Keep translation keys stable. Renaming
hero.titletohome.hero.titleorphans 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
LingoHub for Storyblok: Built for JSON-based content
Translate Storyblok content with LingoHub using structured JSON workflows, API sync, and file-based import/export for faster multilingual publishing.
Website localization in 2025: 10 essential best practices
Website localization in 2025 goes beyond translation. Discover 10 proven strategies to optimize design, SEO, and user experience for global audiences.