astro-intl 1.0.4 → 1.1.1

package/README.md

@@ -13,6 +13,9 @@ Sistema de internacionalización simple y type-safe para Astro, inspirado en nex
 - 🛡️ **Concurrency-safe**: Usa `AsyncLocalStorage` en SSR para aislar requests concurrentes
 - 🌍 **Multi-runtime**: Compatible con Node.js, Cloudflare Workers y Deno
 - ⚙️ **Default locale configurable**: Define tu locale por defecto desde las opciones
+- 🗺️ **Routing localizado**: Define URLs traducidas por locale (`/es/sobre-nosotros` en vez de `/es/about`)
+- 🔄 **Rewrites automáticos**: El middleware reescribe URLs traducidas a rutas canónicas del filesystem
+- 🔗 **Generación de URLs**: `path()` y `switchLocalePath()` para construir y transformar URLs localizadas
 
 ## 📦 Instalación
 
@@ -249,7 +252,104 @@ const t = getTranslations<Messages>('nav');
 </nav>
 ```
 
-## 📚 API Reference
+## �️ Routing Localizado
+
+### Definir rutas traducidas
+
+Crea un mapa de rutas con URLs traducidas por locale:
+
+```ts
+// src/i18n/routing.ts
+export const routing = {
+  locales: ["en", "es"],
+  defaultLocale: "en",
+  routes: {
+    home: { en: "/", es: "/" },
+    about: { en: "/about", es: "/sobre-nosotros" },
+    blog: { en: "/blog/[slug]", es: "/blog/[slug]" },
+    shop: { en: "/shop/[category]/[id]", es: "/tienda/[category]/[id]" },
+  },
+} as const;
+```
+
+### Con Middleware (recomendado)
+
+Pasa las rutas al middleware. Este reescribe automáticamente URLs traducidas a las rutas canónicas del filesystem:
+
+```ts
+// src/middleware.ts
+import "@/i18n/request";
+import { createIntlMiddleware } from "astro-intl/middleware";
+import { routing } from "@/i18n/routing";
+
+export const onRequest = createIntlMiddleware(routing);
+```
+
+Cuando un usuario visita `/es/sobre-nosotros`, el middleware lo reescribe a `/es/about` — que mapea a tu archivo `[lang]/about.astro`. Sin páginas duplicadas.
+
+### Sin Middleware
+
+Configura las rutas via las opciones de la integración:
+
+```js
+// astro.config.mjs
+import { defineConfig } from "astro/config";
+import astroIntl from "astro-intl";
+
+export default defineConfig({
+  integrations: [
+    astroIntl({
+      defaultLocale: "en",
+      locales: ["en", "es"],
+      routes: {
+        about: { en: "/about", es: "/sobre-nosotros" },
+      },
+    }),
+  ],
+});
+```
+
+Sin middleware no hay rewrites automáticos. Crea wrappers ligeros para cada ruta traducida:
+
+```astro
+---
+// src/pages/[lang]/sobre-nosotros.astro
+export { default } from "./about.astro";
+export { getStaticPaths } from "./about.astro";
+---
+```
+
+### Generar URLs con `path()`
+
+```astro
+---
+import { path } from "astro-intl/routing";
+---
+
+<a href={path("about")}>About</a>
+<!-- locale "en" → /en/about -->
+<!-- locale "es" → /es/sobre-nosotros -->
+
+<a href={path("shop", { locale: "es", params: { category: "ropa", id: "42" } })}>
+  Ver producto
+</a>
+<!-- → /es/tienda/ropa/42 -->
+```
+
+### Cambiar locale con `switchLocalePath()`
+
+```astro
+---
+import { switchLocalePath } from "astro-intl/routing";
+---
+
+<a href={switchLocalePath(Astro.url.pathname, "en")}>English</a>
+<a href={switchLocalePath(Astro.url.pathname, "es")}>Español</a>
+<!-- En /en/about → /es/sobre-nosotros -->
+<!-- En /es/tienda/ropa/42 → /en/shop/ropa/42 -->
+```
+
+## � API Reference
 
 ### `astroIntl(options?)`
 
@@ -260,6 +360,8 @@ Configura la integración en `astro.config.mjs`.
 - `defaultLocale?: string` - Locale por defecto cuando la URL no tiene prefijo de idioma (default: `"en"`)
 - `enabled?: boolean` - Habilitar/deshabilitar la integración (default: `true`)
 - `messages?: MessagesConfig` - Mensajes de traducción estáticos o dinámicos
+- `locales?: string[]` - Lista de locales soportados
+- `routes?: RoutesMap` - Mapa de rutas traducidas por locale
 
 ### `setRequestLocale(url, getConfig?)`
 
@@ -345,6 +447,40 @@ Obtiene el locale actual configurado.
 
 **Retorna:** `string` - El código del locale (ej: `'es'`, `'en'`)
 
+### `createIntlMiddleware(options)`
+
+Crea un middleware de Astro que llama automáticamente a `setRequestLocale` en cada request. Importar desde `astro-intl/middleware`.
+
+**Opciones:**
+
+- `locales: string[]` - Lista de locales soportados
+- `defaultLocale?: string` - Locale por defecto (default: `"en"`)
+- `routes?: RoutesMap` - Mapa de rutas traducidas. Cuando se proporciona, el middleware reescribe URLs traducidas a sus rutas canónicas del filesystem
+
+### `path(routeKey, options?)`
+
+Genera una URL localizada para una ruta nombrada. Importar desde `astro-intl/routing`.
+
+**Parámetros:**
+
+- `routeKey: string` - Nombre de la ruta (clave del mapa de `routes`)
+- `options?.locale` - Locale destino (default: locale actual)
+- `options?.params` - `Record<string, string>` para sustituir `[param]` en el template
+- `options?.encode` - Codificar params con `encodeURIComponent` (default: `true`)
+
+**Retorna:** `string` - URL localizada (ej: `"/es/sobre-nosotros"`)
+
+### `switchLocalePath(currentPath, nextLocale)`
+
+Convierte la URL actual a su equivalente en otro locale. Importar desde `astro-intl/routing`.
+
+**Parámetros:**
+
+- `currentPath: string | URL` - Ruta actual (pathname, URL string o URL object)
+- `nextLocale: string` - Locale destino
+
+**Retorna:** `string` - URL equivalente en el nuevo locale. Preserva query strings y hashes. Si no matchea ningún template, hace fallback a intercambiar el prefijo del locale.
+
 ---
 
 ## 🚀 Desarrollo (para contribuidores)
@@ -388,9 +524,11 @@ packages/integration/
 │   ├── store.ts           # Estado por request (AsyncLocalStorage + fallback)
 │   ├── translations.ts    # getTranslations y getTranslationsReact
 │   ├── react.ts           # Factory de t.rich() para React
+│   ├── routing.ts         # path(), switchLocalePath() — generación de URLs localizadas
+│   ├── middleware.ts       # createIntlMiddleware() con rewrites de rutas traducidas
 │   ├── index.ts           # Entry point público + integración de Astro
 │   └── types/
-│       └── index.ts       # Tipos TypeScript
+│       └── index.ts       # Tipos TypeScript (incluye RoutesMap)
 ├── dist/                  # Archivos compilados (generados)
 │   ├── *.js               # JavaScript compilado
 │   └── *.d.ts             # Declaraciones de tipos

package/dist/__tests__/routing.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/routing.test.js

@@ -0,0 +1,265 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { __resetRequestConfig, __setIntlConfig, setRequestLocale } from "../core.js";
+import { path, switchLocalePath, templateToRegex } from "../routing.js";
+// ─── Helpers ─────────────────────────────────────────────────────────
+const ROUTES = {
+    home: { en: "/", es: "/" },
+    about: { en: "/about", es: "/sobre-nosotros" },
+    post: { en: "/blog/[slug]", es: "/blog/[slug]" },
+    shop: { en: "/shop/[category]/[id]", es: "/tienda/[category]/[id]" },
+};
+function setupConfig(opts) {
+    __setIntlConfig({
+        defaultLocale: "en",
+        locales: opts?.locales ?? ["en", "es"],
+        routes: opts?.routes ?? ROUTES,
+    });
+}
+async function setLocale(locale) {
+    const url = new URL(`https://example.com/${locale}/page`);
+    const config = { locale, messages: {} };
+    await setRequestLocale(url, () => config);
+}
+// ─── templateToRegex ─────────────────────────────────────────────────
+describe("templateToRegex()", () => {
+    it("converts template without params", () => {
+        const { regex, paramNames } = templateToRegex("/about");
+        expect(paramNames).toEqual([]);
+        expect(regex.test("/about")).toBe(true);
+        expect(regex.test("/other")).toBe(false);
+    });
+    it("converts template with one param", () => {
+        const { regex, paramNames } = templateToRegex("/blog/[slug]");
+        expect(paramNames).toEqual(["slug"]);
+        expect(regex.test("/blog/hello-world")).toBe(true);
+        expect(regex.test("/blog/")).toBe(false);
+        expect(regex.test("/blog/a/b")).toBe(false);
+    });
+    it("converts template with multiple params", () => {
+        const { regex, paramNames } = templateToRegex("/shop/[category]/[id]");
+        expect(paramNames).toEqual(["category", "id"]);
+        expect(regex.test("/shop/clothing/42")).toBe(true);
+        expect(regex.test("/shop/clothing")).toBe(false);
+    });
+    it("escapes special regex characters in template", () => {
+        const { regex } = templateToRegex("/file.html");
+        expect(regex.test("/file.html")).toBe(true);
+        expect(regex.test("/fileXhtml")).toBe(false);
+    });
+    it("caches compiled regex", () => {
+        const a = templateToRegex("/blog/[slug]");
+        const b = templateToRegex("/blog/[slug]");
+        expect(a).toBe(b);
+    });
+    it("matches root path", () => {
+        const { regex, paramNames } = templateToRegex("/");
+        expect(paramNames).toEqual([]);
+        expect(regex.test("/")).toBe(true);
+    });
+});
+// ─── path() ──────────────────────────────────────────────────────────
+describe("path()", () => {
+    beforeEach(() => {
+        __resetRequestConfig();
+    });
+    it("generates simple path without params", async () => {
+        setupConfig();
+        await setLocale("en");
+        expect(path("about", { locale: "es" })).toBe("/es/sobre-nosotros");
+    });
+    it("generates path with params", async () => {
+        setupConfig();
+        await setLocale("en");
+        expect(path("post", { locale: "en", params: { slug: "hello-world" } })).toBe("/en/blog/hello-world");
+    });
+    it("generates path with multiple params", async () => {
+        setupConfig();
+        await setLocale("en");
+        expect(path("shop", { locale: "es", params: { category: "ropa", id: "42" } })).toBe("/es/tienda/ropa/42");
+    });
+    it("uses current locale when not specified", async () => {
+        setupConfig();
+        await setLocale("en");
+        expect(path("about", {})).toBe("/en/about");
+    });
+    it("uses current locale when options is empty", async () => {
+        setupConfig();
+        await setLocale("es");
+        expect(path("about")).toBe("/es/sobre-nosotros");
+    });
+    it("throws if routeKey does not exist", async () => {
+        setupConfig();
+        await setLocale("en");
+        expect(() => path("nonexistent", { locale: "en" })).toThrow(/Unknown route key/);
+    });
+    it("throws if locale has no template for route", async () => {
+        setupConfig({
+            routes: { about: { en: "/about" } },
+            locales: ["en", "es"],
+        });
+        await setLocale("en");
+        expect(() => path("about", { locale: "es" })).toThrow(/no template for locale/);
+    });
+    it("throws if routes not configured", async () => {
+        __setIntlConfig({ defaultLocale: "en", locales: ["en", "es"] });
+        await setLocale("en");
+        expect(() => path("about", { locale: "en" })).toThrow(/No routes configured/);
+    });
+    it("throws if params are missing", async () => {
+        setupConfig();
+        await setLocale("en");
+        expect(() => path("post", { locale: "en" })).toThrow(/Missing params/);
+    });
+    it("throws for invalid locale", async () => {
+        setupConfig();
+        await setLocale("en");
+        expect(() => path("about", { locale: "fr" })).toThrow(/Invalid locale/);
+    });
+    it("encodes params by default", async () => {
+        setupConfig();
+        await setLocale("en");
+        expect(path("post", { locale: "en", params: { slug: "hello world" } })).toBe("/en/blog/hello%20world");
+    });
+    it("skips encoding when encode is false", async () => {
+        setupConfig();
+        await setLocale("en");
+        expect(path("post", { locale: "en", params: { slug: "hello world" }, encode: false })).toBe("/en/blog/hello world");
+    });
+    it("handles root path template", async () => {
+        setupConfig();
+        await setLocale("en");
+        expect(path("home", { locale: "es" })).toBe("/es/");
+    });
+});
+// ─── switchLocalePath() ──────────────────────────────────────────────
+describe("switchLocalePath()", () => {
+    beforeEach(() => {
+        __resetRequestConfig();
+    });
+    it("switches locale on simple route", () => {
+        setupConfig();
+        expect(switchLocalePath("/en/about", "es")).toBe("/es/sobre-nosotros");
+    });
+    it("switches locale on route with params", () => {
+        setupConfig();
+        expect(switchLocalePath("/en/blog/my-post", "es")).toBe("/es/blog/my-post");
+    });
+    it("switches locale with multiple params", () => {
+        setupConfig();
+        expect(switchLocalePath("/en/shop/clothing/42", "es")).toBe("/es/tienda/clothing/42");
+    });
+    it("fallback: just swaps prefix when no route matches", () => {
+        setupConfig();
+        expect(switchLocalePath("/en/unknown/page", "es")).toBe("/es/unknown/page");
+    });
+    it("handles full URL input", () => {
+        setupConfig();
+        expect(switchLocalePath("https://example.com/en/about", "es")).toBe("/es/sobre-nosotros");
+    });
+    it("handles URL object input", () => {
+        setupConfig();
+        const url = new URL("https://example.com/en/about");
+        expect(switchLocalePath(url, "es")).toBe("/es/sobre-nosotros");
+    });
+    it("handles root path", () => {
+        setupConfig();
+        expect(switchLocalePath("/en/", "es")).toBe("/es/");
+    });
+    it("handles root path without trailing slash", () => {
+        setupConfig();
+        expect(switchLocalePath("/en", "es")).toBe("/es/");
+    });
+    it("preserves query params", () => {
+        setupConfig();
+        expect(switchLocalePath("/en/about?ref=nav", "es")).toBe("/es/sobre-nosotros?ref=nav");
+    });
+    it("preserves hash", () => {
+        setupConfig();
+        expect(switchLocalePath("/en/about#section", "es")).toBe("/es/sobre-nosotros#section");
+    });
+    it("preserves query + hash", () => {
+        setupConfig();
+        expect(switchLocalePath("/en/about?x=1#section", "es")).toBe("/es/sobre-nosotros?x=1#section");
+    });
+    it("works without routes configured (fallback only)", () => {
+        __setIntlConfig({ defaultLocale: "en", locales: ["en", "es"] });
+        expect(switchLocalePath("/en/about", "es")).toBe("/es/about");
+    });
+    it("prepends locale when path has no locale prefix", () => {
+        setupConfig();
+        expect(switchLocalePath("/about", "es")).toBe("/es/about");
+    });
+    it("throws for invalid nextLocale", () => {
+        setupConfig();
+        expect(() => switchLocalePath("/en/about", "fr")).toThrow(/Invalid locale/);
+    });
+    it("switches from es to en", () => {
+        setupConfig();
+        expect(switchLocalePath("/es/sobre-nosotros", "en")).toBe("/en/about");
+    });
+    it("switches es route with params to en", () => {
+        setupConfig();
+        expect(switchLocalePath("/es/tienda/ropa/42", "en")).toBe("/en/shop/ropa/42");
+    });
+});
+// ─── detectRouteConflicts (via __setIntlConfig) ──────────────────────
+describe("detectRouteConflicts", () => {
+    beforeEach(() => {
+        __resetRequestConfig();
+    });
+    it("throws on exact duplicate templates", () => {
+        expect(() => __setIntlConfig({
+            locales: ["en"],
+            routes: {
+                blog: { en: "/blog/[slug]" },
+                news: { en: "/blog/[slug]" },
+            },
+        })).toThrow(/Duplicate route template/);
+    });
+    it("warns on structurally equivalent templates", () => {
+        const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => { });
+        __setIntlConfig({
+            locales: ["en"],
+            routes: {
+                blog: { en: "/blog/[slug]" },
+                news: { en: "/blog/[article]" },
+            },
+        });
+        expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("Route conflict detected"));
+        warnSpy.mockRestore();
+    });
+    it("does not warn for distinct templates", () => {
+        const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => { });
+        __setIntlConfig({
+            locales: ["en"],
+            routes: {
+                blog: { en: "/blog/[slug]" },
+                about: { en: "/about" },
+            },
+        });
+        expect(warnSpy).not.toHaveBeenCalled();
+        warnSpy.mockRestore();
+    });
+});
+// ─── Template validation ─────────────────────────────────────────────
+describe("template validation", () => {
+    beforeEach(() => {
+        __resetRequestConfig();
+    });
+    it("throws on unbalanced brackets", async () => {
+        setupConfig({
+            routes: { bad: { en: "/blog/[slug", es: "/blog/[slug]" } },
+            locales: ["en", "es"],
+        });
+        await setLocale("en");
+        expect(() => path("bad", { locale: "en" })).toThrow(/Unbalanced brackets/);
+    });
+    it("throws on invalid param names", async () => {
+        setupConfig({
+            routes: { bad: { en: "/blog/[slug-name]", es: "/blog/[slug]" } },
+            locales: ["en", "es"],
+        });
+        await setLocale("en");
+        expect(() => path("bad", { locale: "en" })).toThrow(/Param names must match/);
+    });
+});

package/dist/core.d.ts

@@ -2,3 +2,4 @@ export { setRequestLocale, runWithLocale, getLocale, getLocales, isValidLocale,
 export { getTranslations, getTranslationsReact } from "./translations.js";
 export { getNestedValue, type DotPaths } from "./interpolation.js";
 export { sanitizeLocale, sanitizeHtml, escapeRegExp } from "./sanitize.js";
+export { path, switchLocalePath, templateToRegex } from "./routing.js";

package/dist/core.js

@@ -6,3 +6,5 @@ export { getTranslations, getTranslationsReact } from "./translations.js";
 export { getNestedValue } from "./interpolation.js";
 // ─── Sanitisation utilities ─────────────────────────────────────────
 export { sanitizeLocale, sanitizeHtml, escapeRegExp } from "./sanitize.js";
+// ─── Routing utilities ──────────────────────────────────────────────
+export { path, switchLocalePath, templateToRegex } from "./routing.js";

package/dist/index.d.ts

@@ -1,11 +1,12 @@
 import type { AstroIntegration } from "astro";
-import type { MessagesConfig } from "./types/index.js";
-import { setRequestLocale as _setRequestLocale, runWithLocale as _runWithLocale, getLocale as _getLocale, getLocales as _getLocales, isValidLocale as _isValidLocale, getMessages as _getMessages, getTranslations as _getTranslations, getTranslationsReact as _getTranslationsReact, defineRequestConfig as _defineRequestConfig, __resetRequestConfig as _resetRequestConfig } from "./core.js";
+import type { MessagesConfig, RoutesMap } from "./types/index.js";
+import { setRequestLocale as _setRequestLocale, runWithLocale as _runWithLocale, getLocale as _getLocale, getLocales as _getLocales, isValidLocale as _isValidLocale, getMessages as _getMessages, getTranslations as _getTranslations, getTranslationsReact as _getTranslationsReact, defineRequestConfig as _defineRequestConfig, __resetRequestConfig as _resetRequestConfig, path as _path, switchLocalePath as _switchLocalePath } from "./core.js";
 export type AstroIntlOptions = {
     enabled?: boolean;
     defaultLocale?: string;
     locales?: string[];
     messages?: MessagesConfig;
+    routes?: RoutesMap;
 };
 export default function astroIntl(options?: AstroIntlOptions): AstroIntegration;
 export declare const setRequestLocale: typeof _setRequestLocale;
@@ -18,5 +19,7 @@ export declare const getTranslations: typeof _getTranslations;
 export declare const getTranslationsReact: typeof _getTranslationsReact;
 export declare const defineRequestConfig: typeof _defineRequestConfig;
 export declare const __resetRequestConfig: typeof _resetRequestConfig;
-export type { RequestConfig, Primitive, GetRequestConfigFn, MessagesConfig, IntlConfig, } from "./types/index.js";
+export declare const path: typeof _path;
+export declare const switchLocalePath: typeof _switchLocalePath;
+export type { RequestConfig, Primitive, GetRequestConfigFn, MessagesConfig, IntlConfig, RoutesMap, ExtractParams, ParamsForRoute, } from "./types/index.js";
 export type { DotPaths } from "./core.js";

package/dist/index.js

@@ -1,10 +1,11 @@
-import { setRequestLocale as _setRequestLocale, runWithLocale as _runWithLocale, getLocale as _getLocale, getLocales as _getLocales, isValidLocale as _isValidLocale, getMessages as _getMessages, getTranslations as _getTranslations, getTranslationsReact as _getTranslationsReact, defineRequestConfig as _defineRequestConfig, __resetRequestConfig as _resetRequestConfig, __setConfigMessages, __setIntlConfig, } from "./core.js";
+import { setRequestLocale as _setRequestLocale, runWithLocale as _runWithLocale, getLocale as _getLocale, getLocales as _getLocales, isValidLocale as _isValidLocale, getMessages as _getMessages, getTranslations as _getTranslations, getTranslationsReact as _getTranslationsReact, defineRequestConfig as _defineRequestConfig, __resetRequestConfig as _resetRequestConfig, __setConfigMessages, __setIntlConfig, path as _path, switchLocalePath as _switchLocalePath, } from "./core.js";
 export default function astroIntl(options = {}) {
-    const { enabled = true, defaultLocale, locales, messages } = options;
-    if (defaultLocale || locales) {
+    const { enabled = true, defaultLocale, locales, messages, routes } = options;
+    if (defaultLocale || locales || routes) {
         __setIntlConfig({
             ...(defaultLocale && { defaultLocale }),
             ...(locales && { locales }),
+            ...(routes && { routes }),
         });
     }
     if (messages) {
@@ -40,3 +41,5 @@ export const getTranslations = _getTranslations;
 export const getTranslationsReact = _getTranslationsReact;
 export const defineRequestConfig = _defineRequestConfig;
 export const __resetRequestConfig = _resetRequestConfig;
+export const path = _path;
+export const switchLocalePath = _switchLocalePath;

package/dist/middleware.d.ts

@@ -1,8 +1,11 @@
+import type { RoutesMap } from "./types/index.js";
 export type IntlMiddlewareOptions = {
     locales: readonly string[];
     defaultLocale?: string;
+    routes?: RoutesMap;
 };
 export declare function createIntlMiddleware(options: IntlMiddlewareOptions): (context: {
     url: URL;
     request: Request;
+    rewrite: (path: string | URL) => Promise<Response>;
 }, next: () => Promise<Response>) => Promise<Response>;

package/dist/middleware.js

@@ -1,9 +1,43 @@
 import { setRequestLocale, __setIntlConfig } from "./store.js";
+import { templateToRegex } from "./routing.js";
+// ─── Route rewrite helper ────────────────────────────────────────────
+// Given a pathname like /es/sobre-nosotros, checks if it matches a
+// translated route template. If so, returns the canonical (defaultLocale)
+// path that maps to the filesystem, e.g. /es/about.
+// Returns null when no rewrite is needed.
+function resolveTranslatedRoute(pathname, lang, routes, defaultLocale) {
+    const restPath = "/" + pathname.split("/").slice(2).join("/");
+    for (const routeKey of Object.keys(routes)) {
+        const entry = routes[routeKey];
+        const localTemplate = entry[lang];
+        if (!localTemplate)
+            continue;
+        const { regex, paramNames } = templateToRegex(localTemplate);
+        const match = restPath.match(regex);
+        if (!match)
+            continue;
+        // If this locale's template is the same as defaultLocale's, no rewrite needed
+        const canonicalTemplate = entry[defaultLocale];
+        if (!canonicalTemplate || canonicalTemplate === localTemplate)
+            return null;
+        // Extract params and substitute into the canonical template
+        const params = {};
+        paramNames.forEach((name, idx) => {
+            params[name] = match[idx + 1];
+        });
+        let canonical = canonicalTemplate;
+        canonical = canonical.replace(/\[(\w+)\]/g, (_m, name) => params[name] ?? `[${name}]`);
+        return `/${lang}${canonical}`;
+    }
+    return null;
+}
 export function createIntlMiddleware(options) {
-    const { locales, defaultLocale } = options;
+    const { locales, defaultLocale: _defaultLocale, routes } = options;
+    const resolvedDefaultLocale = _defaultLocale ?? "en";
     __setIntlConfig({
         locales: [...locales],
-        ...(defaultLocale && { defaultLocale }),
+        ...(resolvedDefaultLocale && { defaultLocale: resolvedDefaultLocale }),
+        ...(routes && { routes }),
     });
     return async (context, next) => {
         const [, lang] = context.url.pathname.split("/");
@@ -11,6 +45,13 @@ export function createIntlMiddleware(options) {
             return next();
         }
         await setRequestLocale(context.url);
+        // Rewrite translated routes to their canonical filesystem paths
+        if (routes) {
+            const rewrittenPath = resolveTranslatedRoute(context.url.pathname, lang, routes, resolvedDefaultLocale);
+            if (rewrittenPath) {
+                return context.rewrite(rewrittenPath);
+            }
+        }
         return next();
     };
 }

package/dist/routing.d.ts

@@ -0,0 +1,12 @@
+type CompiledTemplate = {
+    regex: RegExp;
+    paramNames: string[];
+};
+export declare function templateToRegex(template: string): CompiledTemplate;
+export declare function path(routeKey: string, options?: {
+    locale?: string;
+    params?: Record<string, string>;
+    encode?: boolean;
+}): string;
+export declare function switchLocalePath(currentPath: string | URL, nextLocale: string): string;
+export {};

package/dist/routing.js

@@ -0,0 +1,162 @@
+import { getRoutes, getDefaultLocale, getLocales, getLocale, isValidLocale } from "./store.js";
+const regexCache = new Map();
+// ─── Template validation ─────────────────────────────────────────────
+const VALID_PARAM_REGEX = /^\w+$/;
+const BRACKET_OPEN = /\[/g;
+const BRACKET_CLOSE = /\]/g;
+function validateTemplate(template, routeKey, locale) {
+    const opens = (template.match(BRACKET_OPEN) || []).length;
+    const closes = (template.match(BRACKET_CLOSE) || []).length;
+    if (opens !== closes) {
+        throw new Error(`[astro-intl] Invalid route template for "${routeKey}" (${locale}): "${template}". ` +
+            `Unbalanced brackets.`);
+    }
+    const params = [...template.matchAll(/\[([^\]]*)\]/g)];
+    for (const match of params) {
+        if (!VALID_PARAM_REGEX.test(match[1])) {
+            throw new Error(`[astro-intl] Invalid param name "[${match[1]}]" in route "${routeKey}" (${locale}): "${template}". ` +
+                `Param names must match /\\w+/.`);
+        }
+    }
+}
+// ─── templateToRegex ─────────────────────────────────────────────────
+export function templateToRegex(template) {
+    const cached = regexCache.get(template);
+    if (cached)
+        return cached;
+    const paramNames = [];
+    const pattern = template
+        .replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+        .replace(/\\\[(\w+)\\\]/g, (_match, name) => {
+        paramNames.push(name);
+        return "([^/]+)";
+    });
+    const compiled = {
+        regex: new RegExp(`^${pattern}$`),
+        paramNames,
+    };
+    regexCache.set(template, compiled);
+    return compiled;
+}
+// ─── substituteParams ────────────────────────────────────────────────
+function substituteParams(template, params, encode) {
+    let result = template;
+    const missing = [];
+    result = result.replace(/\[(\w+)\]/g, (_match, name) => {
+        if (!(name in params)) {
+            missing.push(name);
+            return `[${name}]`;
+        }
+        return encode ? encodeURIComponent(params[name]) : params[name];
+    });
+    if (missing.length > 0) {
+        throw new Error(`[astro-intl] Missing params for route template "${template}": ${missing.join(", ")}`);
+    }
+    return result;
+}
+// ─── path() ──────────────────────────────────────────────────────────
+export function path(routeKey, options = {}) {
+    const routes = getRoutes();
+    if (!routes) {
+        throw new Error("[astro-intl] No routes configured. Add routes to your astro-intl config.");
+    }
+    const routeEntry = routes[routeKey];
+    if (!routeEntry) {
+        throw new Error(`[astro-intl] Unknown route key: "${routeKey}". ` +
+            `Available keys: ${Object.keys(routes).join(", ")}`);
+    }
+    const locale = options.locale ?? getLocale();
+    if (getLocales().length > 0 && !isValidLocale(locale)) {
+        throw new Error(`[astro-intl] Invalid locale "${locale}" for path(). ` +
+            `Configured locales: ${getLocales().join(", ")}`);
+    }
+    const template = routeEntry[locale];
+    if (!template) {
+        throw new Error(`[astro-intl] Route "${routeKey}" has no template for locale "${locale}". ` +
+            `Available locales for this route: ${Object.keys(routeEntry).join(", ")}`);
+    }
+    validateTemplate(template, routeKey, locale);
+    const encode = options.encode !== false;
+    const resolvedPath = substituteParams(template, options.params ?? {}, encode);
+    return `/${locale}${resolvedPath}`;
+}
+// ─── switchLocalePath() ──────────────────────────────────────────────
+export function switchLocalePath(currentPath, nextLocale) {
+    const locales = getLocales();
+    if (locales.length > 0 && !isValidLocale(nextLocale)) {
+        throw new Error(`[astro-intl] Invalid locale "${nextLocale}" for switchLocalePath(). ` +
+            `Configured locales: ${locales.join(", ")}`);
+    }
+    // Parse input
+    let pathname;
+    let suffix = "";
+    if (currentPath instanceof URL) {
+        pathname = currentPath.pathname;
+        suffix = (currentPath.search || "") + (currentPath.hash || "");
+    }
+    else if (currentPath.includes("://")) {
+        try {
+            const url = new URL(currentPath);
+            pathname = url.pathname;
+            suffix = (url.search || "") + (url.hash || "");
+        }
+        catch {
+            pathname = currentPath;
+        }
+    }
+    else {
+        const qIdx = currentPath.indexOf("?");
+        const hIdx = currentPath.indexOf("#");
+        const splitIdx = qIdx >= 0 && hIdx >= 0 ? Math.min(qIdx, hIdx) : qIdx >= 0 ? qIdx : hIdx >= 0 ? hIdx : -1;
+        if (splitIdx >= 0) {
+            pathname = currentPath.slice(0, splitIdx);
+            suffix = currentPath.slice(splitIdx);
+        }
+        else {
+            pathname = currentPath;
+        }
+    }
+    // Detect current locale from pathname
+    const segments = pathname.split("/");
+    const currentLocaleSegment = segments[1] || "";
+    const defaultLocale = getDefaultLocale();
+    const currentLocale = locales.length > 0 && locales.includes(currentLocaleSegment)
+        ? currentLocaleSegment
+        : currentLocaleSegment === defaultLocale
+            ? defaultLocale
+            : null;
+    // No locale detected in path → prepend nextLocale
+    if (!currentLocale) {
+        return `/${nextLocale}${pathname}${suffix}`;
+    }
+    // Extract rest of path after locale segment
+    const restPath = "/" + segments.slice(2).join("/");
+    const routes = getRoutes();
+    // Try to match against route templates
+    if (routes) {
+        for (const routeKey of Object.keys(routes)) {
+            const routeEntry = routes[routeKey];
+            const currentTemplate = routeEntry[currentLocale];
+            if (!currentTemplate)
+                continue;
+            const { regex, paramNames } = templateToRegex(currentTemplate);
+            const match = restPath.match(regex);
+            if (match) {
+                const nextTemplate = routeEntry[nextLocale];
+                if (!nextTemplate) {
+                    // No template for nextLocale → fallback
+                    break;
+                }
+                // Extract params from match
+                const params = {};
+                paramNames.forEach((name, idx) => {
+                    params[name] = match[idx + 1];
+                });
+                const nextPath = substituteParams(nextTemplate, params, false);
+                return `/${nextLocale}${nextPath}${suffix}`;
+            }
+        }
+    }
+    // Fallback: just swap locale prefix
+    return `/${nextLocale}${restPath}${suffix}`;
+}

package/dist/store.d.ts

@@ -1,6 +1,7 @@
-import type { GetRequestConfigFn, MessagesConfig, IntlConfig, RequestConfig } from "./types/index.js";
+import type { GetRequestConfigFn, MessagesConfig, IntlConfig, RequestConfig, RoutesMap } from "./types/index.js";
 export declare function __setIntlConfig(config: Partial<IntlConfig>): void;
 export declare function getDefaultLocale(): string;
+export declare function getRoutes(): RoutesMap | undefined;
 export declare function getLocales(): string[];
 export declare function isValidLocale(locale: string): boolean;
 export declare function defineRequestConfig(fn: (locale: string) => Promise<RequestConfig> | RequestConfig): GetRequestConfigFn;

package/dist/store.js

@@ -37,10 +37,17 @@ export function __setIntlConfig(config) {
     if (config.locales) {
         intlConfig = { ...intlConfig, locales: config.locales };
     }
+    if (config.routes) {
+        intlConfig = { ...intlConfig, routes: config.routes };
+        detectRouteConflicts(config.routes);
+    }
 }
 export function getDefaultLocale() {
     return intlConfig.defaultLocale;
 }
+export function getRoutes() {
+    return intlConfig.routes;
+}
 export function getLocales() {
     return intlConfig.locales;
 }
@@ -60,7 +67,35 @@ export function __resetRequestConfig() {
     registeredGetRequestConfig = null;
     configMessages = null;
     fallbackState = null;
-    intlConfig = { defaultLocale: "en", locales: [] };
+    intlConfig = { defaultLocale: "en", locales: [], routes: undefined };
+}
+// ─── Route conflict detection ────────────────────────────────────────
+function normalizeTemplate(template) {
+    return template.replace(/\[\w+\]/g, "[*]");
+}
+function detectRouteConflicts(routes) {
+    const keys = Object.keys(routes);
+    for (let i = 0; i < keys.length; i++) {
+        for (let j = i + 1; j < keys.length; j++) {
+            const a = routes[keys[i]];
+            const b = routes[keys[j]];
+            for (const locale of Object.keys(a)) {
+                if (!b[locale])
+                    continue;
+                if (a[locale] === b[locale]) {
+                    throw new Error(`[astro-intl] Duplicate route template for locale "${locale}": ` +
+                        `"${keys[i]}" and "${keys[j]}" both use "${a[locale]}". ` +
+                        `Each routeKey must have a unique template per locale.`);
+                }
+                if (normalizeTemplate(a[locale]) === normalizeTemplate(b[locale])) {
+                    console.warn(`[astro-intl] ⚠️  Route conflict detected for locale "${locale}":\n` +
+                        `  "${keys[i]}" (${a[locale]})\n` +
+                        `  "${keys[j]}" (${b[locale]})\n` +
+                        `  Both templates match the same pattern. "${keys[i]}" will take priority.`);
+                }
+            }
+        }
+    }
 }
 // ─── Resolve messages from MessagesConfig ───────────────────────────
 async function resolveMessages(locale, source) {

package/dist/types/index.d.ts

@@ -7,7 +7,15 @@ export type GetRequestConfigFn = (locale: string) => Promise<RequestConfig> | Re
 export type MessagesConfig = Record<string, Record<string, unknown> | (() => Promise<{
     default: Record<string, unknown>;
 } | Record<string, unknown>>)>;
+export type RoutesMap = {
+    [routeKey: string]: {
+        [locale: string]: string;
+    };
+};
+export type ExtractParams<T extends string> = T extends `${string}[${infer P}]${infer Rest}` ? P | ExtractParams<Rest> : never;
+export type ParamsForRoute<Template extends string> = [ExtractParams<Template>] extends [never] ? Record<string, never> : Record<ExtractParams<Template>, string>;
 export type IntlConfig = {
     defaultLocale: string;
     locales: string[];
+    routes?: RoutesMap;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astro-intl",
-  "version": "1.0.4",
+  "version": "1.1.1",
   "type": "module",
   "description": "Sistema de internacionalización simple y type-safe para Astro, inspirado en next-intl",
   "keywords": [
@@ -12,7 +12,8 @@
     "internationalization",
     "intl",
     "translations",
-    "typescript"
+    "typescript",
+    "accessibility"
   ],
   "author": "Erick Cruz <erickj.cruzs@gmail.com>",
   "license": "MIT",
@@ -41,6 +42,10 @@
     "./middleware": {
       "types": "./dist/middleware.d.ts",
       "import": "./dist/middleware.js"
+    },
+    "./routing": {
+      "types": "./dist/routing.d.ts",
+      "import": "./dist/routing.js"
     }
   },
   "peerDependencies": {