Configurable Pathname-based i18n Routing for Astro (Next.js-style Internationalized URLs)

[9ssi7]

Summary

Introduce a configurable i18n routing system to Astro, enabling developers to define language-specific pathnames for their routes—similar to how Next.js handles internationalized URLs. This would allow for clean, localized URLs (e.g. /giris instead of /auth) mapped to the same page logic, improving both SEO and user experience.

Background & Motivation

Currently, implementing internationalized routing in Astro requires significant custom logic, especially for projects that want localized URLs for each language (not just a locale prefix or domain).
Many web applications—especially those migrating from Next.js or targeting international audiences—need the ability to map paths like /about-us (en) and /hakkimizda (tr) to the same content.
Today, achieving this in Astro is complex and involves manual rewrites, redirects, and maintaining multiple routes for the same page. There is no “official” or ergonomic way to manage locale-specific pathnames.

Goals

• Enable developers to define a single source of truth for language-specific pathnames (per route, per locale).
• Provide clean, localized URLs without requiring duplicate page files or complex workarounds.
• Support for parameterized dynamic routes (e.g. /places/[slug] → /yerler/[slug]).
• Improve international SEO by allowing true “translated URLs.”
• Reduce boilerplate and improve maintainability of i18n sites on Astro.

Example

Developers could define the mapping either directly inside astro.config.ts in the i18n section,
or import an external config file if needed (for large mappings):

// astro.config.ts

import i18n from './i18n.config'; // Optional: for large configs

export default defineConfig({
  site: 'https://example.com',
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'tr'],
    pathnames: {
      '/auth': { en: '/auth', tr: '/giris' },
      '/auth/verify': { en: '/auth/verify', tr: '/giris/dogrula' },
      '/places/[slug]': { en: '/places/[slug]', tr: '/yerler/[slug]' },
      '/about-us': { en: '/about-us', tr: '/hakkimizda' },
      // etc.
    },
    // Or: ...i18n (if using an external config file)
  }
});

Astro would use this config to handle:

• Rewrites: Incoming requests to localized URLs (e.g. /giris/dogrula) are mapped to the actual page logic (/auth/verify).
• Redirects: Optionally redirect users to the correct localized URL based on their locale or domain.
• Dynamic routes: Correctly parse parameters in translated paths (e.g. /yerler/istanbul → /places/[slug]:istanbul).

Integration with Astro's i18n and Middleware

• No new mandatory config file required. For most projects, the pathnames mapping lives directly inside astro.config.ts under the existing i18n section, keeping everything unified.
• For very large projects, importing from an external i18n.config.ts file is optional and follows normal TypeScript/ESM patterns.
• The real enabler for this feature is an SSR middleware, analogous to the one used by next-intl for Next.js.

How the Middleware Works

• Locale detection: Domain or param based, as Astro already supports.
• Canonical path & localized path lookup: Use the mapping to find which physical page file to render (canonicalPath) and which localized URL to show (localizedPath).
• Redirect: If the URL does not match the expected localized path for the detected locale, redirect the user to the correct one.
• Rewrite: If the URL does match the localized path, internally rewrite the request to the canonical path, so that Astro's file-based routing works seamlessly.
• Dynamic params: Fully supported (e.g. /places/[slug] → /yerler/[slug]).

Example Middleware Flow

export const createI18nMiddleware = (config) => {
  return defineMiddleware((context, next) => {
    const { locale } = detectLocale(context); // e.g. from domain, cookie, etc.
    context.locals.locale = locale;
    const [canonicalPath, localizedPath] = getExpectedPathname(
      config, context.url.pathname, locale, context.params
    );
    if (canonicalPath && localizedPath) {
      if (context.url.pathname === localizedPath) {
        // Rewrite to the canonical file path for logic
        return next(new Request(rewriteUrl(context.request.url, canonicalPath), context.request));
      }
      if (context.url.pathname === canonicalPath) {
        // Redirect to the localized path
        return context.redirect(localizedPath);
      }
    }
    return next();
  });
};

Directory Structure Example

/src/pages
  /about-us.astro
  /profile.astro
  /places/[slug].astro
astro.config.ts

• No need for duplicate files for each language!
• All path logic and URL translations are handled in config + middleware.

Mermaid Flowchart

flowchart TD
    A[User visits a URL] --> B[Astro SSR Middleware]
    B --> C[Detect locale]
    C --> D{Path matches localizedPath?}
    D -- No --> E[Redirect to localizedPath]
    D -- Yes --> F{Exists canonicalPath in pages?}
    F -- Yes --> G[Rewrite to canonicalPath]
    G --> H[Render canonical content; URL stays localized]
    F -- No --> I[Return 404 or continue normal]

Loading

Why Framework-level Support Matters

• Every project that wants true translated URLs must now reimplement this logic in custom middleware.
• This proposal removes duplication, improves consistency, and integrates with Astro's routing and SSR principles.
• Opt-in only, no breaking changes.
• Follows familiar patterns from Next.js (next-intl), Nuxt, and SvelteKit (with plugins).

[akifkadioglu]

Dope 🚀

[onuryucel1]

please ssi please

[ascorbic]

@9ssi7 thanks for the interesting suggestion. It would be good if your proposal could include a bit about how this would work with the existing i18n support. I don't think it would make sense to have a separate config file, for example.

[9ssi7]

I will provide clear examples as soon as I am available.

[9ssi7]

@ascorbic Thank you for the feedback and for raising important integration questions! Here’s a detailed, technical clarification of the proposal, with examples and direct analogies to next-intl’s middleware.

Config Location & Pattern

• Defining an external i18n.config.ts is optional.
• For most projects, the pathnames mapping can and should be part of the main astro.config.ts, in the i18n section.
• If a project has a very large or dynamic mapping, they can import an external config file into astro.config.ts (see example below).
• This keeps things DRY and maintains a single source of truth—matching current Astro conventions.

// astro.config.ts

import i18n from './i18n.config'; // Optional: only for very large configs

export default defineConfig({
  site: 'https://example.com',
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'tr'],
    domains: {
        tr: "https://example.com.tr",
        en: "http://example.com",
    },
    pathnames: {
      '/about-us': { en: '/about-us', tr: '/hakkimizda' },
      '/profile': { en: '/profile', tr: '/profil' },
      '/places/[slug]': { en: '/places/[slug]', tr: '/yerler/[slug]' }
    },
    // or: ...i18n  // If config is imported from external file
  }
});

The Core of the Solution: SSR Middleware

• The feature can be implemented as a middleware—very similar to what next-intl does:
  next-intl middleware source
• This middleware would only run for SSR, just like all Astro middlewares.
• Astro’s i18n already detects locale from domain or params; this proposal simply adds an optional mapping layer for translated pathnames.

Expected Middleware Flow

1. Detect locale (from domain or params — already handled by Astro’s i18n).
2. Find:

• canonicalPath = file path in /pages (or /src/pages)
• localizedPath = user-facing, translated path (from i18n.pathnames mapping)

3. If the current URL is not the localizedPath for the detected locale:

• Redirect to the correct localizedPath (to keep URLs in sync with user’s language).

4. If the current URL is the localizedPath:

• Rewrite the request to the canonicalPath in the file system (so Astro’s file-based router works as expected).
• The URL remains localized in the browser, but the content is resolved via the canonical file route.

flowchart TD
    A[User visits a URL] --> B[Astro SSR Middleware]
    B --> C[Detect locale]
    C --> D{Path matches<br>localizedPath?}
    D -- No --> E[Redirect to localizedPath]
    D -- Yes --> F{Exists canonicalPath<br>in pages?}
    F -- Yes --> G[Rewrite to canonicalPath]
    G --> H[Render canonical content<br>URL stays localized]
    F -- No --> I[Return 404 or continue normal]

Loading

Flowchart Example

1. User visits: https://example.com.tr/hakkimizda

• Detected locale: tr (com.tr - domain)
• i18n.pathnames finds mapping:
• • canonicalPath = /about-us
• • localizedPath = /hakkimizda
• No redirect needed (URL matches locale),
• Rewrite internally to /about-us (page logic runs as normal, but user sees /hakkimizda).

2. User visits: https://example.com.tr/about-us

• Detected locale: tr (com.tr - domain)
• Not at /hakkimizda → Redirect to /hakkimizda
• (After redirect: handled as above.)

File Structure Example

/src/pages
  /about-us.astro
  /profile.astro
  /places/[slug].astro
astro.config.ts

• No need for duplicate files for each language!
• Mapping in config + middleware covers everything.

Dynamic Routes

• Works for dynamic routes, e.g. /places/[slug] → /yerler/[slug]
• • Middleware extracts params, maps localized path, rewrites as above.

Analogy: next-intl for Next.js

• This approach mirrors next-intl’s middleware.
• Same business logic: redirect to canonical localized URL, rewrite for internal page resolution.
• All path-based translation logic is centralized in config + middleware, not scattered across files.

Why Framework-level Support?

• Right now, every Astro project that wants true translated URLs has to re-implement this logic in a custom middleware.
• A first-class solution would provide:
• • Consistency across projects
• • No duplication
• • Compatibility with Astro’s routing and SSR architecture
• • No breaking changes for projects that don’t use it (purely opt-in)
• Most i18n-heavy frameworks (Next.js, Nuxt, SvelteKit with plugins) already support path-based translation.
• Native support in Astro would lower the barrier for multilingual projects and reduce custom code significantly.

Let me know if you'd like code samples, a reference implementation, or further technical details!
Thanks for your attention and for considering this feature.

[ascorbic]

Thanks. Could you update your initial post with this info too?

[9ssi7]

Thanks, now updated

[florian-lefebvre]

I definitely want a better story for translated paths in astro, no matter if it's in core or an integration. I think nuxt's API is pretty good (eg. setI18nParams for dynamic params)

[9ssi7]

I am very glad for your warm approach. What do you think about getting a roadmap?

[florian-lefebvre]

Not sure what you mean by that. This is a stage 1 RFC and such feature proposal needs to go through the whole RFC process. For now, let's gather feedback

[marekbrze]

Great proposal! I really agree with everything that is written here. The biggest painpoint with native solution is duplication of logic. Adding any new language requires adding whole folder for this language and it starts to be unmaintainable really fast. Page should just look for specific translations in .json files and config should take care of routing. I am starting a new project with 2 languages but soon I will be adding 2-5 more. Thinking about the organization of this project for maintainability is quite a big headache

[jp-knj]

Thanks for this comprehensive proposal! While I appreciate the effort to bring pathname-based i18n routing to Astro, I'd like to suggest looking at next-international as an alternative inspiration rather than next-intl.

Here's why I think next-international's approach might be better suited for Astro:

1. Simplicity First

• next-international demonstrates that effective i18n doesn't require complex pathname mapping
• Most projects can achieve excellent UX with simple locale prefixing (/en/about, /tr/about)
• The complexity of pathname translation often isn't worth the maintenance burden

2. Performance Benefits

• Zero dependencies = smaller bundle size
• Lazy loading of translations keeps initial page loads fast
• Less middleware complexity means faster request processing

3. Developer Experience

• Type-safe by default with minimal configuration
• Clear separation between client and server concerns
• Easy to understand and debug

4. Practical Considerations

• URL consistency across locales actually helps with:
  • Easier debugging and analytics
  • Simpler content management
  • More predictable routing behavior
  • Better compatibility with existing tools

Alternative Suggestion:
Instead of adding pathname mapping to Astro's core, perhaps we could:

1. Keep the core i18n routing simple (like next-international)
2. Create an official plugin/integration for those who need pathname translation
3. This keeps Astro lean while offering flexibility for advanced use cases

The beauty of next-international is that it proves you can have excellent i18n without the complexity of pathname translation. For the majority of use cases, this simpler approach might actually be preferable.

What do you think about keeping Astro's i18n routing closer to next-international's philosophy while offering pathname translation as an opt-in feature? (This is an excellent proposal—I truly hope it finds its way into Astro in one form or another.)

[marekbrze]

I strongly disagree that "The complexity of pathname translation often isn't worth the maintenance burden".

As a creator of websites in Polish and English ability to translate paths is a TOP priority.

I can't imagine having English path for polish locale (or vice versa):

EN: /restaurants
PL: /pl/restaurants

This is totally unusable and not seo friendly.

[jp-knj]

You make an excellent point about SEO and user experience.

I completely understand why pathname translation is crucial for your use case. Polish users absolutely expect /restauracje not /pl/restaurants, and you're right that mixing languages in URLs hurts both usability and SEO.

I should clarify my statement: when I said "often isn't worth the maintenance burden," I was thinking specifically about next-international's philosophy of keeping things simple for the majority of use cases. However, you're highlighting exactly why this is a limitation of next-international. it doesn't support this critical feature that many multilingual sites need.

[jp-knj]

First of all, I fully understand that translating URL slugs is mission-critical for sites serving both Polish and English audiences. For certain markets, shipping an English /restaurants under a Polish locale is a non-starter for both UX and SEO.
That said, I believe keeping slug translation out of Astro core and shipping it as an official, opt-in plugin is a healthier path for the ecosystem. Here is why.

1. Astro’s philosophy is “lean core + integrations”

Astro’s maintainers explicitly aim for a small core that can be extended through integrations.
Internationalization should follow the same two-layer model:

• Core → language prefix and automatic hreflang generation, nothing more.
• Official integration → extras such as translated slugs, CMS sync, custom redirects.

This lets both “keep it simple” projects and “full i18n” projects share the same core.

2. SEO signals are multi-layered

Google’s guidelines emphasize hreflang, canonical tags and structured data.
High-authority sites like Wikipedia and MDN rank well without translating slugs, proving that translated URLs are an option, not a hard requirement.

3. Translated slugs carry heavy operational costs

• Collision checks for every new slug in every locale.
• Redirect matrices for old links.
• CMS logic to map a single content ID to many locale-specific slugs.

These costs scale with site size and speed of content updates. Bundling that complexity into core would enlarge Astro’s maintenance surface dramatically.

4. An official plugin gives us the best of both worlds

1. Core stays light: locale prefix + type-safe hreflang.

2. @astrojs/i18n-pathmap (hypothetical) ships:

   • pathnames mapping in astro.config.ts.
   • Middleware for rewrite/redirect logic.
   • Dynamic route support (/places/[slug] → /yerler/[slug]).

3. Projects that truly need translated URLs simply npm i the plugin and opt in.

Thus sites that must translate slugs and those that prefer not to both run on the identical Astro core.

5. Precedent in other frameworks

Next.js follows a similar split: core stays minimal while next-intl (or other libs) provide slug translation as an add-on. Matching that balance keeps upgrades smoother and responsibilities clear.

Bottom line

I agree that localized slugs matter for certain audiences. But baking the entire feature into Astro core would burden every project with complexity only some will use.
Providing it as an official, first-party plugin retains Astro’s lightweight core while giving teams that need full slug translation a turnkey, well-supported solution.

Lean core, powerful opt-ins—that’s the Astro way.

[9ssi7]

It might make sense for pathmap to be an external lib. When we look at it, nextjs doesn't provide it directly, next-intl does. NextJS doesn't care about pathmap upgrading flawlessly with it when upgrading, that's next-intl's problem.

However, even if it is provided as core, rewrite rule won't work unless user defines middleware. Or if pathname is not given in config, default behavior will continue.

pathname translation is included in i18n. i18n support without pathname translation is not simplicity but deficiency. If astro:i18n is core, pathname translation should be core too.

[jp-knj]

Hi there—first of all, thank you for taking the time to explain your position so thoroughly.
I’m not an SEO specialist, so I’d love to learn from you two while we compare notes and see exactly where we agree and where we don’t.

Where we already agree

• Product owner view: A site can feel only “half translated” if the URL itself is still in another language. That’s a real UX concern, and I don’t want to dismiss it.
• Need for an official path: Astro should absolutely provide an official way to achieve slug translation so users don’t reinvent the wheel.

Where our perspectives differ

from a framework-maintainer’s perspective we have to draw a line between:

• Routing primitives
• Editorial features

What must live in core?

Layer	Responsibility
Routing primitives	locale detection, prefix insertion, type-safe hreflang
Editorial features	per-slug translation tables, CMS sync, redirect matrices

• Google’s multilingual-site guide states that “language prefix + hreflang” is fully SEO-compliant.
• Large SEO-heavy sites (MDN, Wikipedia, etc.) follow that model and rank well.
• Therefore, slug translation is helpful but not mandatory for search performance.

Astro core already covers the first row. The second row explodes in complexity—collision checks, permanent redirects, CMS binding—and varies wildly per project. That variability is exactly why Next.js delegates slug translation to next-intl.

Middleware is required either way

Even if slug translation were baked into core, you still need middleware to:

• map localizedPath → canonicalPath;
• redirect “wrong-locale” hits;
• expand dynamic params.

So every project ends up with src/middleware.ts regardless.
Providing that same logic as an official plugin yields the same DX while keeping core lean.

Upgrade safety & maintenance

• Plugin approach
  • Core upgrades stay painless—no breaking rewrite logic inside Astro.
  • Plugin can iterate faster (JSON/YAML configs, CMS look-ups, etc.) without blocking Astro releases.
• Hard-wired core
  • Every routing edge-case becomes a framework bug, not a plugin bug—exactly the burden Next.js avoids by delegating to next-intl.

A concrete compromise

1. Ship astro:i18n (prefix + hreflang) as-is in core.
2. Publish @astrojs/i18n-pathmap (name TBD) that:
   • reads pathnames from astro.config.ts;
   • auto-installs the rewrite/redirect middleware;
   • exports helper types so configs stay type-safe.

Projects needing translated slugs run:

npm i @astrojs/i18n-pathmap

Others stay on zero-config core. Everyone shares the same file-based router and upgrade path.

❓ Open question

Is there a workflow that this plugin-based outline cannot cover?
If Google’s docs plus MDN’s success still miss something crucial for your market, could you point me to concrete SEO data I should look at?

Thanks again for the discussion—I truly appreciate any insight you can share.

[BuckyBuck135]

It would be absolutely amazing to have more native i18n features. At the moment, features such as hreflang or translated paths do require implementing a lot of custom code or an integration.

Unfortunately (but understandably, i18n is very complex), the more comprehensive integrations that I know of (i18n for Astro and astro-i18next)are unmaintained.

[ematipico]

The reason why localised paths weren't added as part of the core was that:

• not all users require this feature
• localisation of paths can be done in different ways, and we deemed this feature not a blocker for i18n when we initially implemented the feature
• at the time of when i18n was introduced, Astro didn't have the routing infrastructure to support the feature. At that time, routing to /it/saluti would have caused a 404 because that route doesn't exist in the file system

However, core now has the infrastructure to support such a feature.

[ematipico]

Oh, and yes, another thing that made myself and Matthew hesitant about the feature is "being opinionated".

Since it's a feature that comes with strings attached and compromises, we thought it was best to delegate this to an integration, so users can use the package that fits their needs.

[florian-lefebvre]

Then maybe this feature could live under @astrojs/i18n-paths or whatever, ie. as an official integration. Only problem IMO is how to interact with the sitemap

[delucis]

Could also be a community integration I guess

And integrations are composable, so for now you could just take options and have the i18n integration process and pass those when injecting the sitemap integration.

[florian-lefebvre]

Honestly the fact that there have been 10-ish integrations and most of are now unmaintained is a signal that this is difficult to get right, and maybe too hard for the community to handle. I know that very well 😅. But even if it was a community maintained integration, the official sitemap i18n handling is too naive for this atm

[delucis]

Maybe also a sign we wouldn't get it right either 😅