Astro i18n Routing for Multilingual Sites

Astro i18n routing is the part of Astro that helps a site generate, use, and verify URLs for multiple languages. In practice, it is what keeps a multilingual site from becoming a pile of manually maintained links and inconsistent folder names.

For merchants and developers, the value is simple: if your URLs, page structure, and language rules stay aligned, users land on the right language version more often, and your team spends less time fixing routing mistakes.

Key takeaways

• A multilingual site is easier to maintain when URL rules are defined once and reused everywhere.
• Astro i18n routing is not just about translation; it is about matching routes, folders, and fallback behavior.
• The default locale can live at the root or under a prefix, but the file structure must match the choice.
• Locale-aware helper functions reduce broken links when you add languages or change route patterns.
• Fallbacks matter because untranslated pages should still send visitors to a valid destination.

What is it?

Astro i18n routing is Astro’s built-in way to manage localized routes for sites that serve more than one language. It lets you define the supported locales, choose a default language, and generate URLs that match the structure of your pages. That matters because multilingual sites fail in subtle ways when the route logic is improvised: one section uses /fr/, another uses /french/, and the default language sometimes lives at the root and sometimes does not.

A concrete example makes it easier to see. Imagine a site with English, Spanish, and Portuguese content. You may want /about/ for English, /es/about/ for Spanish, and /pt-br/about/ for Brazilian Portuguese. Astro i18n routing gives you a framework for making those URLs predictable, so the page structure in src/pages/ and the public URLs stay in sync.

It also gives teams a shared language for discussing routing decisions. Instead of saying “the Spanish pages are somewhere under the Spanish folder,” you can say “Spanish is a supported locale, the default language is unprefixed, and all localized links should be generated from config.” That clarity matters when designers, content editors, and developers all touch the same navigation.

Another useful way to think about it is that Astro i18n routing reduces guesswork. It does not translate content for you, and it does not decide your market strategy. What it does is make the routing layer reliable enough that language-specific content can scale without every new page becoming a special case. If you are adding a second or third language, that reliability is often the difference between a manageable rollout and a maintenance headache.

A practical definition is this: if your team needs a repeatable way to map locale-specific content to locale-specific URLs, Astro i18n routing is the system that keeps that mapping explicit. It is especially helpful when the same page concept exists in multiple languages, because the route pattern can stay stable even when the text changes.

Why it matters

For business teams, multilingual routing affects discoverability, trust, and conversion. Visitors are more likely to stay when they land on a page in the language they expect, and they are less likely to bounce when navigation keeps them inside the correct locale. If a merchant runs campaigns in multiple markets, the wrong URL structure can send paid traffic to the wrong language version or to a page that has no translation at all.

For developers, the technical impact is just as important. i18n routing creates a contract between content structure and URL structure. Once that contract is clear, you can generate links programmatically, validate routes more reliably, and reduce the number of one-off exceptions in templates. That matters when a site grows from two languages to five or more, because manual routing does not scale well.

There is also an SEO angle. Localized URLs are easier to reason about when they follow a consistent pattern. Search engines and users both benefit when language versions are organized clearly, and when each locale has a stable path. Even if your content strategy changes later, a well-defined routing model makes migrations less risky.

The practical takeaway is that i18n routing is a foundation, not a cosmetic layer. If the routing model is weak, translation work becomes harder to publish and harder to maintain. If the routing model is strong, content teams can add or revise language versions without rebuilding the site’s navigation every time.

It also reduces operational risk. When a marketing team launches a new locale, the routing rules determine whether old links keep working, whether redirects are predictable, and whether a language switcher can safely point to the nearest equivalent page. That is why routing decisions should happen before a site is already full of content.

A second business benefit is governance. When routing is explicit, it becomes easier to answer questions like “Which pages are translated in every locale?” and “Which language should a visitor see if their browser preference does not match our published content?” Those questions are not just technical; they affect support load, campaign planning, and editorial workflow. A clear routing model gives non-developers a predictable framework to work inside.

How it works

Astro’s i18n routing starts with configuration. You define the list of supported locales and choose a defaultLocale. From there, Astro can understand which language versions exist and how their URLs should be formed. The routing system then uses that information to help generate localized paths and verify whether requests map to valid pages.

The next piece is file structure. Astro’s file-based routing still applies, but localized content is organized into locale-specific folders such as src/pages/es/ or src/pages/pt-br/. When the folder names match the configured locales, Astro can map those files to the correct public routes. This is where many teams either get disciplined or create future maintenance work: the folder structure must reflect the URL strategy, not just the content team’s preferred naming style.

A third part is the middleware layer. Astro uses middleware to implement its routing logic, and that middleware runs in a way that lets your own logic and page rendering happen first before Astro performs its i18n checks. In plain terms, your redirects or page logic can run, then Astro can verify that the localized URL is valid. That is useful when you need both custom behavior and built-in route validation.

The mechanism is easiest to understand as a sequence. First, a request comes in for a URL such as /es/about/. Second, Astro compares that path against the configured locale list and the page structure in src/pages/. Third, if the path matches a valid localized route, the page is served; if not, the routing layer can help determine whether a fallback, redirect, or alternate locale should apply. That sequence is what keeps the site from relying on ad hoc template logic for every language decision.

A fourth part is link generation. Once Astro knows the locale map, helper functions can derive the correct path from a route name and a locale value. That means the URL is not just a string in a template; it is the output of the routing rules you already defined. This is what makes later changes safer, because the helper can adapt when the route structure changes.

Default locale and prefixes

One of the most important decisions is whether the default language should have a prefix. With prefixDefaultLocale: false, the default language stays at the root, so English might use /about/ while Spanish uses /es/about/. With prefixDefaultLocale: true, every language gets a prefix, so English becomes /en/about/ as well.

That choice affects both URLs and file organization. If the default language is unprefixed, its pages usually live at the root of src/pages/. If every locale is prefixed, then even the default language should live in a localized folder. The route strategy and the file structure need to agree, or the generated URLs will not match the files you actually have.

A good rule is to choose the prefix strategy based on long-term consistency, not short-term convenience. If your site is likely to expand into many markets, prefixed URLs for every locale can make the structure easier to explain and automate. If your default market is dominant and you want the cleanest root URLs for that audience, leaving the default locale unprefixed can be the better tradeoff.

Helper functions and verification

Astro also provides helper functions through astro:i18n, such as getRelativeLocaleUrl(). These helpers are valuable because they compute links from your configuration instead of forcing you to hard-code every path. If you later change the default locale or add a new language, the helper-based links are much less likely to break.

Verification is the other half of the story. Astro can use the routing information to check whether a localized URL corresponds to a valid route. That is especially helpful in larger sites where content editors may add links manually, or where a page exists in one language but not another. The routing system helps you avoid sending visitors to dead ends.

In practice, helper functions are most useful when the same route appears in many places: navigation, breadcrumbs, language switchers, footer links, and campaign landing pages. The more often a URL is reused, the more value you get from centralizing the logic.

You can think of the workflow as three layers working together: configuration defines the language map, file structure defines what exists, and helper functions keep the links aligned with both. If any one of those layers is inconsistent, the site may still build, but the multilingual experience becomes fragile.

Use cases

The most common use case is a content site or marketing site that publishes the same pages in several languages. A merchant might have a homepage, product landing pages, and a blog in English and Spanish. In that setup, Astro i18n routing keeps the URLs consistent and makes it easier to add new localized pages without rewriting the entire navigation.

A second use case is a documentation or knowledge base site with regional variants. In that environment, the content may not be identical in every language, so the routing system needs to handle missing pages and fallbacks gracefully. Astro’s support for fallback languages is useful here because it gives visitors a valid destination even when a translation is not available yet.

A third use case is a site that wants language-aware navigation but still needs custom routing rules. For example, a team might want a default language at the root, but a specific market under a regional prefix, or they may want to combine built-in i18n routing with their own middleware. Astro supports that kind of flexibility, which is useful when the site’s market structure is more complex than a simple one-language-per-folder setup.

The decision criterion is usually not “Do we need i18n?” but “How much routing complexity do we want to manage manually?” If the answer is “not much,” built-in routing and helper functions are a good fit. If the answer is “quite a lot,” manual logic may still be appropriate, but you should keep the route rules documented and consistent.

Another practical scenario is a site with seasonal or campaign content. A team may launch a landing page in one locale first, then roll it out to others later. In that case, routing needs to support partial coverage without breaking the language switcher or the main navigation. Astro’s locale-aware helpers and fallback behavior make that rollout easier to control.

A fourth scenario is a brand that wants to localize only the highest-value pages first. Instead of translating the entire site at once, the team can use routing to publish a small set of pages in each locale and keep the rest on a fallback path. That approach is common when editorial resources are limited, because it lets the site expand in stages without creating broken navigation.

How to implement or apply it

Start by defining the locales and the default locale in your Astro configuration. Keep the locale codes exact and consistent with your folder names, because the routing system depends on that match. If you are using pt-br, do not rename the folder to something more readable unless you also change the locale value to match.

Next, decide on the default-language URL strategy. If you want the default locale to live at the root, keep prefixDefaultLocale off and organize the default language files accordingly. If you want every language to have a prefix, turn it on and move the default locale into a localized folder. This is a structural decision, not a cosmetic preference, so make it early.

Then build localized folders under src/pages/ for each language you support. Keep the page names aligned across locales whenever possible. If you have /about/ in English, try to keep the same page concept in Spanish and Portuguese, even if the content differs. That makes route generation and content management much easier.

A practical implementation workflow is to create one representative page first, then test the generated URL pattern before scaling to the rest of the site. For example, verify the homepage, one content page, and one cross-language link before you migrate every template. This helps you catch mismatches between config and file structure early, when the fix is still simple.

When you apply this in a real project, treat the routing setup as part of the content model. If editors need to publish pages in multiple languages, give them a predictable rule for where the localized file lives and how the public URL is formed. That reduces back-and-forth between content and engineering.

A useful implementation detail is to decide where route ownership lives. In smaller teams, one developer may own the locale map and the page structure. In larger teams, content operations may own the list of supported languages while engineering owns the URL rules. Either way, the ownership should be explicit so that new locales do not appear in one place without being added everywhere else.

Use helper functions for links

Once the routes exist, use locale-aware helpers such as getRelativeLocaleUrl() when generating internal links. This is especially helpful in navigation menus, language switchers, and content templates where you do not want to hand-build every URL. The helper approach reduces the chance of mismatched prefixes and makes route changes safer.

You do not need to replace every link immediately, but prioritize the places where a broken localized URL would be most visible: top navigation, footer language links, and cross-language CTAs. Those are the links users rely on to move between languages, so they should be the most robust.

A useful implementation habit is to keep one source of truth for locale-aware paths. If a page path is needed in several components, derive it from the same helper or route map rather than copying the string into each file. That makes future refactors much easier.

Decide whether to use built-in or manual logic

Astro also allows you to implement your own i18n logic manually, with or without the built-in middleware. That is useful when your routing rules are unusual, such as market-specific URL patterns or more advanced fallback behavior. The tradeoff is maintenance: manual logic gives you control, but it also gives you more code to test and more places for route drift to appear.

A practical rule is to use built-in routing for standard multilingual sites and manual logic only when the business requirement clearly needs it. If you do choose manual routing, keep the same discipline around locale definitions, URL generation, and fallback handling. The more exceptional the routing, the more important it is to document the rules.

Common mistakes and pitfalls

The most common mistake is letting the file structure and the locale configuration drift apart. If the config says fr but the folder is named french, Astro will not be able to map the route the way you expect. This is easy to miss during early development and expensive to clean up after content has already been published.

Another frequent problem is mixing manual links with generated links without a clear rule. If some templates use helper functions and others hard-code URLs, the site can end up with inconsistent prefixes or broken language switchers after a configuration change. That is especially risky when the default locale strategy changes from root-based to prefixed URLs.

A third pitfall is ignoring fallback behavior. Multilingual sites rarely have perfect parity across every page and every language. If a translation is missing, visitors need a valid alternative, not a dead end. Astro’s routing supports fallback languages, but teams still need to decide what “fallback” means for their content model.

There is also a governance issue: routing changes often happen alongside content changes, but not always in the same pull request. If the locale list changes, the page structure, navigation, and localized links should be reviewed together. Otherwise, the site may compile but still send users to the wrong place.

A simple fix for many of these issues is to treat routing as part of content QA. Check a sample of localized pages after every release, and verify both the visible language and the actual URL pattern. That small habit catches broken prefixes, missing folders, and stale links before users do.

Another pitfall is overcomplicating the first version of the setup. Teams sometimes try to solve every future market scenario on day one, which leads to a routing model that is hard to understand and even harder to maintain. Start with the simplest structure that supports the current languages, then extend it when the business case is real.

A final mistake is assuming browser language detection is enough. Preferred-language hints can improve the experience, but they should not replace explicit locale selection or stable URLs. Visitors still need a predictable way to switch languages, bookmark pages, and share links without ambiguity.

Best practices and quick checklist

The best i18n routing setups are the ones that make the correct path the easiest path. That means choosing a URL strategy early, keeping locale codes consistent, and using helpers for generated links instead of hand-typing every route. It also means treating the default locale as part of the routing design, not as an afterthought.

A good maintenance habit is to review routing whenever you add a new language or rename a page. Even small changes can affect localized URLs, especially if a page is linked from navigation, blog templates, or footer menus. The more places a route appears, the more valuable helper-based generation becomes.

Use this quick checklist when you apply Astro i18n routing:

• Define supported locales and the default locale before building pages.
• Decide whether the default language should be prefixed.
• Match locale folder names exactly to the configured locale values.
• Use astro:i18n helpers for internal localized links where possible.
• Plan fallback behavior for pages that do not exist in every language.
• Review navigation and language-switcher links after any routing change.
• Keep manual exceptions rare and documented.
• Test at least one page per locale after each routing or content update.
• Prefer one URL pattern per locale instead of mixing conventions across sections.
• Revisit the routing model before launching a new market or region.

If you want a broader content architecture alongside routing, Astro Content Collections is a useful companion topic because structured content and structured URLs usually work best together.

A second best practice is to write down the routing rules in plain language for non-developers. Editors do not need the implementation details, but they do need to know whether a page should exist under a locale prefix, whether the default language is special, and what happens when a translation is missing. That documentation prevents a lot of avoidable confusion.

From practice — illustrative scenario (hypothetical, not a client project)

Illustrative example — not a real client project: imagine a merchant running a small brand site in English and German, with plans to add French later. The team starts with a simple setup where English pages live at the root and German pages live under /de/. At first, the navigation is hand-built, and the language switcher uses hard-coded paths because there are only a few pages.

As the site grows, the team adds new landing pages and a blog. That is when the problems begin. A new German page is published, but one footer link still points to the English root path. A campaign email uses a manual URL that does not match the current locale prefix strategy. The site still works, but the routing is no longer trustworthy because each new page requires someone to remember the exact path pattern.

The team then moves to Astro i18n routing with a clear locale list, a defined default language, and a decision about whether the default locale should stay at the root. They also reorganize localized pages so the folder names match the locale codes exactly. Instead of building links by hand, they use locale-aware helper functions for the language switcher and the main navigation. That makes the URL pattern repeatable across templates.

Before changing the whole site, they test a small workflow: one localized homepage, one product page, and one blog post. They check whether the generated URLs match the intended structure, whether the default locale behaves as expected, and whether a missing translation has a sensible fallback. Only after those checks pass do they update the remaining templates.

The team also sets a rule for future changes. If a page is added in one language, the content owner must confirm whether the page should exist in every locale, whether it needs a fallback, and whether the navigation should link to it immediately. That rule prevents the common “published in one language, forgotten in the others” problem.

A second decision point comes when French is added. Instead of inventing a new pattern, the team reuses the same routing model: locale code, folder name, helper-based links, and a consistent fallback policy. Because the structure already exists, the new locale is mostly a content task rather than a routing redesign. That is the real benefit of the system: it turns expansion into a repeatable checklist instead of a special project.

The takeaway is not that the setup becomes magical. The takeaway is that the routing rules become visible and reusable. When a new language is added later, the team can check the locale configuration, folder structure, and fallback behavior in one place rather than hunting through templates for hard-coded paths. That is the real benefit of Astro i18n routing: it turns multilingual URLs into a system instead of a guessing game.

Related concepts and further reading

If you are planning a multilingual Astro site, routing is only one part of the architecture. Content structure, rendering strategy, and navigation behavior all affect how easy the site is to maintain.

• Astro content collections guide — useful when you want localized content to stay organized as the site grows.
• Astro islands architecture — helpful when you are balancing multilingual content with interactive UI.
• Astro Themes — browse Astro-ready designs that can be adapted for multilingual builds.
• Astro docs on internationalization — the official reference for configuration and routing behavior.
• Astro — explore the category if you are choosing a starting point for a new site.