astro-intl 2.0.1 → 2.0.3

package/README.md

@@ -1,701 +1,701 @@
-# astro-intl
-
-Sistema de internacionalización simple y type-safe para Astro, inspirado en next-intl.
-
-## ✨ Características
-
-- 🔒 **Type-safe**: Autocompletado y validación de claves de traducción con TypeScript
-- 🎯 **API simple**: Inspirada en next-intl, fácil de usar
-- ⚛️ **Soporte React**: Adapter dedicado con `t.rich()` para rich text con componentes React. Importa desde `astro-intl/react`
-- 🧡 **Soporte Svelte**: Adapter dedicado con `t.rich()` que retorna segmentos y componente `RichText`. Importa desde `astro-intl/svelte`
-- 🎨 **Markup en traducciones**: Inserta HTML en strings con `t.markup()`
-- 📁 **Namespaces**: Organiza traducciones por secciones
-- 🌐 **Detección automática de locale**: Extrae el idioma desde la URL
-- 🛡️ **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
-- 📦 **Sub-path imports**: `astro-intl/react`, `astro-intl/svelte`, `astro-intl/routing`, `astro-intl/middleware`
-
-## � Migración desde v1 a v2
-
-### Breaking changes
-
-1. **`getTranslationsReact` ya no se exporta desde `astro-intl`**. Usa `getTranslations` desde `astro-intl/react`:
-
-```diff
-- import { getTranslationsReact } from "astro-intl";
-+ import { getTranslations } from "astro-intl/react";
-
-- const t = getTranslationsReact();
-+ const t = getTranslations();
-```
-
-2. **Sub-path imports obligatorios para adapters de framework**:
-   - React: `astro-intl/react`
-   - Svelte: `astro-intl/svelte`
-
-3. Las funciones base de Astro (`getTranslations`, `setRequestLocale`, `getLocale`, etc.) siguen exportándose desde `astro-intl` sin cambios.
-
-### Nuevas funcionalidades
-
-- **Adapter Svelte** con `t.rich()` y `renderRichText()`
-- **`createGetTranslations` factory** en ambos adapters (React y Svelte) para uso standalone sin store global
-- **`parseRichSegments()`** base agnóstica compartida
-
-## �📦 Instalación
-
-### Instalación automática (Recomendado)
-
-Usa el CLI de Astro para instalar y configurar automáticamente:
-
-```bash
-npx astro add astro-intl
-```
-
-Este comando:
-
-- ✅ Instala el paquete
-- ✅ Agrega la integración a tu `astro.config.mjs`
-- ✅ Configura las dependencias necesarias
-
-### Instalación manual
-
-Si prefieres instalar manualmente:
-
-```bash
-npm install astro-intl
-# o
-pnpm add astro-intl
-# o
-yarn add astro-intl
-```
-
-Luego agrega la integración en tu `astro.config.mjs`:
-
-```js
-import { defineConfig } from "astro/config";
-import astroIntl from "astro-intl";
-
-export default defineConfig({
-  integrations: [
-    astroIntl({
-      defaultLocale: "en", // opcional, por defecto es "en"
-    }),
-  ],
-});
-```
-
-## 🎯 Uso
-
-### Estructura de archivos de traducción
-
-Primero, crea tus archivos de traducción:
-
-```ts
-// src/i18n/es.json
-{
-  "welcome": "Bienvenido",
-  "nav": {
-    "home": "Inicio",
-    "about": "Acerca de"
-  }
-}
-
-// src/i18n/en.json
-{
-  "welcome": "Welcome",
-  "nav": {
-    "home": "Home",
-    "about": "About"
-  }
-}
-
-// src/i18n/index.ts
-import es from './es.json';
-import en from './en.json';
-
-export const ui = { es, en };
-export type Messages = typeof es;
-```
-
-### En componentes Astro
-
-```astro
----
-import { setRequestLocale, getTranslations } from 'astro-intl';
-import { ui } from '../i18n';
-
-// Configurar el locale para esta petición
-await setRequestLocale(Astro.url, async (locale) => ({
-  locale,
-  messages: ui[locale as keyof typeof ui]
-}));
-
-// Obtener función de traducción
-const t = getTranslations();
----
-
-<h1>{t('welcome')}</h1>
-<nav>
-  <a href="/">{t('nav.home')}</a>
-  <a href="/about">{t('nav.about')}</a>
-</nav>
-```
-
-### Interpolación de variables
-
-Usa `{varName}` en tus strings de traducción y pasa un objeto de valores:
-
-```json
-// src/i18n/en.json
-{
-  "greeting": "Hello, {name}!",
-  "info": "You have {count} items"
-}
-```
-
-```astro
----
-const t = getTranslations();
----
-
-<p>{t('greeting', { name: 'John' })}</p>   <!-- "Hello, John!" -->
-<p>{t('info', { count: 5 })}</p>             <!-- "You have 5 items" -->
-<p>{t('greeting')}</p>                       <!-- "Hello, {name}!" (sin valores, placeholder se mantiene) -->
-```
-
-Los valores aceptados son `string | number | boolean`. Si una variable no se pasa o es `null`/`undefined`, el placeholder `{varName}` se mantiene sin cambios.
-
-### Traducciones con markup (HTML en strings)
-
-```astro
----
-// src/i18n/es.json
-// { "terms": "Acepto los <link>términos y condiciones</link>" }
-
-const t = getTranslations();
----
-
-<p set:html={t.markup('terms', {
-  link: (chunks) => `<a href="/terms">${chunks}</a>`
-})} />
-```
-
-### Markup con interpolación
-
-Puedes combinar variables e interpolación de tags usando el formato `{ values, tags }`:
-
-```astro
----
-// src/i18n/en.json
-// { "welcome": "Hello {name}, click <link>here</link> to continue" }
-
-const t = getTranslations();
----
-
-<p set:html={t.markup('welcome', {
-  values: { name: 'John' },
-  tags: {
-    link: (chunks) => `<a href="/home">${chunks}</a>`
-  }
-})} />
-<!-- "Hello John, click <a href="/home">here</a> to continue" -->
-```
-
-### En componentes React
-
-> **v2**: Importa desde `astro-intl/react` en lugar de `astro-intl`.
-
-```tsx
-import { getTranslations } from "astro-intl/react";
-
-export function MyComponent() {
-  const t = getTranslations();
-
-  return (
-    <div>
-      <h1>{t("welcome")}</h1>
-      <nav>
-        <a href="/">{t("nav.home")}</a>
-      </nav>
-    </div>
-  );
-}
-```
-
-#### Factory standalone (sin store)
-
-Si prefieres pasar los mensajes directamente sin depender del store global:
-
-```tsx
-import { createGetTranslations } from "astro-intl/react";
-import { ui } from "../i18n";
-
-const getT = createGetTranslations(ui, "en");
-
-export function MyComponent({ lang }: { lang: string }) {
-  const t = getT(lang, "nav");
-  return <a href="/">{t("home")}</a>;
-}
-```
-
-### Traducciones con componentes React (rich text)
-
-```tsx
-import { getTranslations } from "astro-intl/react";
-
-export function MyComponent() {
-  const t = getTranslations();
-
-  // src/i18n/es.json
-  // { "terms": "Acepto los <link>términos y condiciones</link>" }
-
-  return (
-    <p>
-      {t.rich("terms", {
-        link: (chunks) => <a href="/terms">{chunks}</a>,
-      })}
-    </p>
-  );
-}
-```
-
-### En componentes Svelte
-
-> **v2**: Nuevo adapter. Importa desde `astro-intl/svelte`.
-
-```svelte
-<script>
-  import { getTranslations } from 'astro-intl/svelte';
-
-  const t = getTranslations();
-</script>
-
-<h1>{t('welcome')}</h1>
-<nav>
-  <a href="/">{t('nav.home')}</a>
-</nav>
-```
-
-#### Rich text en Svelte
-
-`t.rich()` retorna un array de `RichSegment[]` que puedes renderizar con `renderRichText()`:
-
-```svelte
-<script>
-  import { getTranslations, renderRichText } from 'astro-intl/svelte';
-
-  // { "terms": "Acepto los <link>términos y condiciones</link>" }
-  const t = getTranslations();
-  const segments = t.rich('terms', ['link']);
-
-  const html = renderRichText(segments, {
-    tags: { link: 'a' },       // renderiza como <a>...</a>
-  });
-</script>
-
-<p>{@html html}</p>
-```
-
-También puedes usar funciones personalizadas con `components`:
-
-```svelte
-<script>
-  import { getTranslations, renderRichText } from 'astro-intl/svelte';
-
-  const t = getTranslations();
-  const segments = t.rich('terms', ['link']);
-
-  const html = renderRichText(segments, {
-    components: {
-      link: (chunks) => `<a href="/terms" class="underline">${chunks}</a>`,
-    },
-  });
-</script>
-
-<p>{@html html}</p>
-```
-
-#### Factory standalone en Svelte (sin store)
-
-```svelte
-<script>
-  import { createGetTranslations } from 'astro-intl/svelte';
-  import { ui } from '../i18n';
-
-  const getT = createGetTranslations(ui, 'en');
-
-  export let lang;
-  const t = getT(lang, 'nav');
-</script>
-
-<a href="/">{t('home')}</a>
-```
-
-### Type-safety con TypeScript
-
-```astro
----
-import { setRequestLocale, getTranslations } from 'astro-intl';
-import { ui, type Messages } from '../i18n';
-
-await setRequestLocale(Astro.url, async (locale) => ({
-  locale,
-  messages: ui[locale as keyof typeof ui]
-}));
-
-// Tipado fuerte con autocompletado
-const t = getTranslations<Messages>();
-
-// TypeScript autocompletará las rutas válidas:
-// t('nav.home')     ✓
-// t('nav.invalid')  ✗ Error de TypeScript
----
-```
-
-### Usar namespaces
-
-```astro
----
-// Obtener solo un namespace específico
-const t = getTranslations<Messages>('nav');
----
-
-<nav>
-  <a href="/">{t('home')}</a>  <!-- En lugar de t('nav.home') -->
-  <a href="/about">{t('about')}</a>
-</nav>
-```
-
-## �️ 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?)`
-
-Configura la integración en `astro.config.mjs`.
-
-**Opciones:**
-
-- `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?)`
-
-Configura el locale para la petición actual.
-
-**Parámetros:**
-
-- `url: URL` - El objeto URL de Astro (`Astro.url`)
-- `getConfig?: (locale: string) => RequestConfig | Promise<RequestConfig>` - Función que retorna la configuración
-
-**Ejemplo:**
-
-```ts
-await setRequestLocale(Astro.url, async (locale) => ({
-  locale,
-  messages: ui[locale],
-}));
-```
-
-### `runWithLocale(url, fn, getConfig?)`
-
-Ejecuta una función dentro de un contexto aislado por request. Usa `AsyncLocalStorage` cuando está disponible (Node.js) para evitar race conditions en SSR con requests concurrentes.
-
-**Parámetros:**
-
-- `url: URL` - El objeto URL de Astro (`Astro.url`)
-- `fn: () => R | Promise<R>` - Función a ejecutar dentro del contexto aislado
-- `getConfig?: GetRequestConfigFn` - Función de configuración opcional
-
-**Ejemplo en middleware:**
-
-```ts
-// src/middleware.ts
-import { runWithLocale } from "astro-intl";
-
-export const onRequest = async (context, next) => {
-  return runWithLocale(
-    context.url,
-    () => next(),
-    (locale) => ({
-      locale,
-      messages: ui[locale],
-    })
-  );
-};
-```
-
-### `getTranslations<T>(namespace?)`
-
-Obtiene la función de traducción para componentes Astro.
-
-**Parámetros:**
-
-- `namespace?: string` - Namespace opcional para obtener solo un subconjunto de traducciones
-
-**Retorna:** Función `t(key, values?)` con método `t.markup(key, tags | { values?, tags })`
-
-#### `t(key, values?)`
-
-- `key: string` - Clave de traducción (soporta dot notation)
-- `values?: Record<string, Primitive>` - Valores para interpolación `{varName}` (opcional)
-
-#### `t.markup(key, options)`
-
-- `key: string` - Clave de traducción
-- `options` - Puede ser:
-  - `Record<string, (chunks: string) => string>` - Solo tags (backward compatible)
-  - `{ values?: Record<string, Primitive>, tags: Record<string, (chunks: string) => string> }` - Tags con interpolación
-
-### `getTranslations()` — `astro-intl/react`
-
-Obtiene la función de traducción para componentes React (usa el store global).
-
-**Retorna:** Función `t(key)` con método `t.rich(key, tags)` que retorna `ReactNode[]`
-
-### `createGetTranslations(ui, defaultLocale)` — `astro-intl/react`
-
-Factory standalone que no depende del store global. Útil para pasar mensajes directamente.
-
-**Parámetros:**
-
-- `ui: Record<string, Record<string, unknown>>` - Objeto con todos los mensajes por locale
-- `defaultLocale: string` - Locale por defecto
-
-**Retorna:** `(lang, namespace) => t` — función que retorna `t(key)` con `t.rich(key, tags)`
-
-### `getTranslations()` — `astro-intl/svelte`
-
-Obtiene la función de traducción para componentes Svelte (usa el store global).
-
-**Retorna:** Función `t(key)` con método `t.rich(key, tagNames?)` que retorna `RichSegment[]`
-
-### `createGetTranslations(ui, defaultLocale)` — `astro-intl/svelte`
-
-Factory standalone para Svelte. Misma firma que el de React pero `t.rich()` retorna `RichSegment[]`.
-
-### `renderRichText(segments, options?)` — `astro-intl/svelte`
-
-Resuelve un array de `RichSegment[]` en un string HTML.
-
-**Parámetros:**
-
-- `segments: RichSegment[]` - Segmentos retornados por `t.rich()`
-- `options.tags?: Record<string, string>` - Mapea nombre de tag a elemento HTML (ej: `{ link: 'a' }`)
-- `options.components?: Record<string, (chunks: string) => string>` - Funciones personalizadas por tag
-
-**Retorna:** `string` - HTML listo para renderizar con `{@html}`
-
-### `getLocale()`
-
-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)
-
-### Compilar el paquete
-
-Antes de usar el paquete en el playground o en cualquier proyecto, debes compilarlo:
-
-```bash
-npm run build
-```
-
-Esto generará los archivos JavaScript y las declaraciones de tipos (`.d.ts`) en la carpeta `dist/`.
-
-### Modo desarrollo
-
-Para compilar automáticamente cuando hagas cambios:
-
-```bash
-npm run dev
-```
-
-### Después de compilar
-
-Si estás trabajando en un monorepo con pnpm workspaces, después de compilar ejecuta:
-
-```bash
-pnpm install
-```
-
-Esto actualizará los enlaces simbólicos y los tipos estarán disponibles en los proyectos que usen el paquete.
-
-## 📦 Estructura del Paquete
-
-```text
-packages/integration/
-├── src/
-│   ├── adapters/
-│   │   ├── react.ts       # Adapter React — getTranslations, createGetTranslations, t.rich() → ReactNode[]
-│   │   └── svelte.ts      # Adapter Svelte — getTranslations, createGetTranslations, t.rich() → RichSegment[], renderRichText()
-│   ├── core.ts            # Barrel — re-exporta todo desde los módulos
-│   ├── framework-base.ts  # parseRichSegments() — base agnóstica compartida por React y Svelte
-│   ├── sanitize.ts        # Validación de locale, sanitización HTML, escape regex
-│   ├── interpolation.ts   # Interpolación {variables}, acceso a valores anidados
-│   ├── store.ts           # Estado por request (AsyncLocalStorage + fallback)
-│   ├── translations.ts    # getTranslations para componentes Astro
-│   ├── 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 (incluye RoutesMap)
-├── dist/                  # Archivos compilados (generados)
-│   ├── *.js               # JavaScript compilado
-│   └── *.d.ts             # Declaraciones de tipos
-├── package.json
-└── tsconfig.json
-```
-
-## 🔧 Configuración TypeScript
-
-El paquete usa:
-
-- `module: "Node16"` para soporte ESM completo
-- `declaration: true` para generar archivos `.d.ts`
-- Imports con extensión `.js` para compatibilidad ESM
-
-## 📝 Notas Importantes
-
-1. **Siempre compila antes de probar**: Los cambios en `src/` no se reflejan hasta que ejecutes `npm run build`
-2. **Archivos dist/ en .gitignore**: Los archivos compilados no se suben a git, se generan en cada instalación
-3. **Extensiones .js en imports**: Aunque el código fuente es TypeScript, los imports deben usar `.js` para compatibilidad con Node16/ESM
+# astro-intl
+
+Simple and type-safe internationalization system for Astro.
+
+## ✨ Features
+
+- 🔒 **Type-safe**: Autocompletion and validation of translation keys with TypeScript
+- 🎯 **Simple API**: Inspired by next-intl, easy to use
+- ⚛️ **React support**: Dedicated adapter with `t.rich()` for rich text with React components. Import from `astro-intl/react`
+- 🧡 **Svelte support**: Dedicated adapter with `t.rich()` that returns segments and `RichText` component. Import from `astro-intl/svelte`
+- 🎨 **Markup in translations**: Insert HTML in strings with `t.markup()`
+- 📁 **Namespaces**: Organize translations by sections
+- 🌐 **Automatic locale detection**: Extracts the language from the URL
+- 🛡️ **Concurrency-safe**: Uses `AsyncLocalStorage` in SSR to isolate concurrent requests
+- 🌍 **Multi-runtime**: Compatible with Node.js, Cloudflare Workers and Deno
+- ⚙️ **Configurable default locale**: Define your default locale from options
+- 🗺️ **Localized routing**: Define translated URLs per locale (`/es/sobre-nosotros` instead of `/es/about`)
+- 🔄 **Automatic rewrites**: Middleware rewrites translated URLs to canonical filesystem routes
+- 🔗 **URL generation**: `path()` and `switchLocalePath()` to build and transform localized URLs
+- 📦 **Sub-path imports**: `astro-intl/react`, `astro-intl/svelte`, `astro-intl/routing`, `astro-intl/middleware`
+
+## 🔄 Migration from v1 to v2
+
+### Breaking changes
+
+1. **`getTranslationsReact` is no longer exported from `astro-intl`**. Use `getTranslations` from `astro-intl/react`:
+
+```diff
+- import { getTranslationsReact } from "astro-intl";
++ import { getTranslations } from "astro-intl/react";
+
+- const t = getTranslationsReact();
++ const t = getTranslations();
+```
+
+2. **Sub-path imports required for framework adapters**:
+   - React: `astro-intl/react`
+   - Svelte: `astro-intl/svelte`
+
+3. Base Astro functions (`getTranslations`, `setRequestLocale`, `getLocale`, etc.) continue to be exported from `astro-intl` without changes.
+
+### New features
+
+- **Svelte adapter** with `t.rich()` and `renderRichText()`
+- **`createGetTranslations` factory** in both adapters (React and Svelte) for standalone use without global store
+- **`parseRichSegments()`** shared framework-agnostic base
+
+## 📦 Installation
+
+### Automatic installation (Recommended)
+
+Use the Astro CLI to install and configure automatically:
+
+```bash
+npx astro add astro-intl
+```
+
+This command:
+
+- ✅ Installs the package
+- ✅ Adds the integration to your `astro.config.mjs`
+- ✅ Configures necessary dependencies
+
+### Manual installation
+
+If you prefer to install manually:
+
+```bash
+npm install astro-intl
+# o
+pnpm add astro-intl
+# o
+yarn add astro-intl
+```
+
+Then add the integration in your `astro.config.mjs`:
+
+```js
+import { defineConfig } from "astro/config";
+import astroIntl from "astro-intl";
+
+export default defineConfig({
+  integrations: [
+    astroIntl({
+      defaultLocale: "en", // optional, defaults to "en"
+    }),
+  ],
+});
+```
+
+## 🎯 Usage
+
+### Translation file structure
+
+First, create your translation files:
+
+```ts
+// src/i18n/es.json
+{
+  "welcome": "Bienvenido",
+  "nav": {
+    "home": "Inicio",
+    "about": "Acerca de"
+  }
+}
+
+// src/i18n/en.json
+{
+  "welcome": "Welcome",
+  "nav": {
+    "home": "Home",
+    "about": "About"
+  }
+}
+
+// src/i18n/index.ts
+import es from './es.json';
+import en from './en.json';
+
+export const ui = { es, en };
+export type Messages = typeof es;
+```
+
+### In Astro components
+
+```astro
+---
+import { setRequestLocale, getTranslations } from 'astro-intl';
+import { ui } from '../i18n';
+
+// Configure the locale for this request
+await setRequestLocale(Astro.url, async (locale) => ({
+  locale,
+  messages: ui[locale as keyof typeof ui]
+}));
+
+// Get translation function
+const t = getTranslations();
+---
+
+<h1>{t('welcome')}</h1>
+<nav>
+  <a href="/">{t('nav.home')}</a>
+  <a href="/about">{t('nav.about')}</a>
+</nav>
+```
+
+### Variable interpolation
+
+Use `{varName}` in your translation strings and pass an object of values:
+
+```json
+// src/i18n/en.json
+{
+  "greeting": "Hello, {name}!",
+  "info": "You have {count} items"
+}
+```
+
+```astro
+---
+const t = getTranslations();
+---
+
+<p>{t('greeting', { name: 'John' })}</p>   <!-- "Hello, John!" -->
+<p>{t('info', { count: 5 })}</p>             <!-- "You have 5 items" -->
+<p>{t('greeting')}</p>                       <!-- "Hello, {name}!" (without values, placeholder remains) -->
+```
+
+Accepted values are `string | number | boolean`. If a variable is not passed or is `null`/`undefined`, the placeholder `{varName}` remains unchanged.
+
+### Translations with markup (HTML in strings)
+
+```astro
+---
+// src/i18n/es.json
+// { "terms": "Acepto los <link>términos y condiciones</link>" }
+
+const t = getTranslations();
+---
+
+<p set:html={t.markup('terms', {
+  link: (chunks) => `<a href="/terms">${chunks}</a>`
+})} />
+```
+
+### Markup with interpolation
+
+You can combine variables and tag interpolation using the `{ values, tags }` format:
+
+```astro
+---
+// src/i18n/en.json
+// { "welcome": "Hello {name}, click <link>here</link> to continue" }
+
+const t = getTranslations();
+---
+
+<p set:html={t.markup('welcome', {
+  values: { name: 'John' },
+  tags: {
+    link: (chunks) => `<a href="/home">${chunks}</a>`
+  }
+})} />
+<!-- "Hello John, click <a href="/home">here</a> to continue" -->
+```
+
+### In React components
+
+> **v2**: Import from `astro-intl/react` instead of `astro-intl`.
+
+```tsx
+import { getTranslations } from "astro-intl/react";
+
+export function MyComponent() {
+  const t = getTranslations();
+
+  return (
+    <div>
+      <h1>{t("welcome")}</h1>
+      <nav>
+        <a href="/">{t("nav.home")}</a>
+      </nav>
+    </div>
+  );
+}
+```
+
+#### Standalone factory (without store)
+
+If you prefer to pass messages directly without depending on the global store:
+
+```tsx
+import { createGetTranslations } from "astro-intl/react";
+import { ui } from "../i18n";
+
+const getT = createGetTranslations(ui, "en");
+
+export function MyComponent({ lang }: { lang: string }) {
+  const t = getT(lang, "nav");
+  return <a href="/">{t("home")}</a>;
+}
+```
+
+### Translations with React components (rich text)
+
+```tsx
+import { getTranslations } from "astro-intl/react";
+
+export function MyComponent() {
+  const t = getTranslations();
+
+  // src/i18n/es.json
+  // { "terms": "Acepto los <link>términos y condiciones</link>" }
+
+  return (
+    <p>
+      {t.rich("terms", {
+        link: (chunks) => <a href="/terms">{chunks}</a>,
+      })}
+    </p>
+  );
+}
+```
+
+### In Svelte components
+
+> **v2**: New adapter. Import from `astro-intl/svelte`.
+
+```svelte
+<script>
+  import { getTranslations } from 'astro-intl/svelte';
+
+  const t = getTranslations();
+</script>
+
+<h1>{t('welcome')}</h1>
+<nav>
+  <a href="/">{t('nav.home')}</a>
+</nav>
+```
+
+#### Rich text in Svelte
+
+`t.rich()` returns an array of `RichSegment[]` that you can render with `renderRichText()`:
+
+```svelte
+<script>
+  import { getTranslations, renderRichText } from 'astro-intl/svelte';
+
+  // { "terms": "Acepto los <link>términos y condiciones</link>" }
+  const t = getTranslations();
+  const segments = t.rich('terms', ['link']);
+
+  const html = renderRichText(segments, {
+    tags: { link: 'a' },       // renders as <a>...</a>
+  });
+</script>
+
+<p>{@html html}</p>
+```
+
+You can also use custom functions with `components`:
+
+```svelte
+<script>
+  import { getTranslations, renderRichText } from 'astro-intl/svelte';
+
+  const t = getTranslations();
+  const segments = t.rich('terms', ['link']);
+
+  const html = renderRichText(segments, {
+    components: {
+      link: (chunks) => `<a href="/terms" class="underline">${chunks}</a>`,
+    },
+  });
+</script>
+
+<p>{@html html}</p>
+```
+
+#### Standalone factory in Svelte (without store)
+
+```svelte
+<script>
+  import { createGetTranslations } from 'astro-intl/svelte';
+  import { ui } from '../i18n';
+
+  const getT = createGetTranslations(ui, 'en');
+
+  export let lang;
+  const t = getT(lang, 'nav');
+</script>
+
+<a href="/">{t('home')}</a>
+```
+
+### Type-safety with TypeScript
+
+```astro
+---
+import { setRequestLocale, getTranslations } from 'astro-intl';
+import { ui, type Messages } from '../i18n';
+
+await setRequestLocale(Astro.url, async (locale) => ({
+  locale,
+  messages: ui[locale as keyof typeof ui]
+}));
+
+// Strong typing with autocompletion
+const t = getTranslations<Messages>();
+
+// TypeScript will autocomplete valid paths:
+// t('nav.home')     ✓
+// t('nav.invalid')  ✗ TypeScript error
+---
+```
+
+### Using namespaces
+
+```astro
+---
+// Get only a specific namespace
+const t = getTranslations<Messages>('nav');
+---
+
+<nav>
+  <a href="/">{t('home')}</a>  <!-- Instead of t('nav.home') -->
+  <a href="/about">{t('about')}</a>
+</nav>
+```
+
+## 🗺️ Localized Routing
+
+### Define translated routes
+
+Create a route map with translated URLs per 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;
+```
+
+### With Middleware (recommended)
+
+Pass the routes to the middleware. It automatically rewrites translated URLs to canonical filesystem routes:
+
+```ts
+// src/middleware.ts
+import "@/i18n/request";
+import { createIntlMiddleware } from "astro-intl/middleware";
+import { routing } from "@/i18n/routing";
+
+export const onRequest = createIntlMiddleware(routing);
+```
+
+When a user visits `/es/sobre-nosotros`, the middleware rewrites it to `/es/about` — which maps to your `[lang]/about.astro` file. No duplicate pages.
+
+### Without Middleware
+
+Configure routes via integration options:
+
+```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" },
+      },
+    }),
+  ],
+});
+```
+
+Without middleware there are no automatic rewrites. Create lightweight wrappers for each translated route:
+
+```astro
+---
+// src/pages/[lang]/sobre-nosotros.astro
+export { default } from "./about.astro";
+export { getStaticPaths } from "./about.astro";
+---
+```
+
+### Generate URLs with `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" } })}>
+  View product
+</a>
+<!-- → /es/tienda/ropa/42 -->
+```
+
+### Switch locale with `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>
+<!-- On /en/about → /es/sobre-nosotros -->
+<!-- On /es/tienda/ropa/42 → /en/shop/ropa/42 -->
+```
+
+## 📚 API Reference
+
+### `astroIntl(options?)`
+
+Configures the integration in `astro.config.mjs`.
+
+**Options:**
+
+- `defaultLocale?: string` - Default locale when the URL has no language prefix (default: `"en"`)
+- `enabled?: boolean` - Enable/disable the integration (default: `true`)
+- `messages?: MessagesConfig` - Static or dynamic translation messages
+- `locales?: string[]` - List of supported locales
+- `routes?: RoutesMap` - Map of translated routes per locale
+
+### `setRequestLocale(url, getConfig?)`
+
+Configures the locale for the current request.
+
+**Parameters:**
+
+- `url: URL` - The Astro URL object (`Astro.url`)
+- `getConfig?: (locale: string) => RequestConfig | Promise<RequestConfig>` - Function that returns the configuration
+
+**Example:**
+
+```ts
+await setRequestLocale(Astro.url, async (locale) => ({
+  locale,
+  messages: ui[locale],
+}));
+```
+
+### `runWithLocale(url, fn, getConfig?)`
+
+Executes a function within a request-isolated context. Uses `AsyncLocalStorage` when available (Node.js) to avoid race conditions in SSR with concurrent requests.
+
+**Parameters:**
+
+- `url: URL` - The Astro URL object (`Astro.url`)
+- `fn: () => R | Promise<R>` - Function to execute within the isolated context
+- `getConfig?: GetRequestConfigFn` - Optional configuration function
+
+**Example in middleware:**
+
+```ts
+// src/middleware.ts
+import { runWithLocale } from "astro-intl";
+
+export const onRequest = async (context, next) => {
+  return runWithLocale(
+    context.url,
+    () => next(),
+    (locale) => ({
+      locale,
+      messages: ui[locale],
+    })
+  );
+};
+```
+
+### `getTranslations<T>(namespace?)`
+
+Gets the translation function for Astro components.
+
+**Parameters:**
+
+- `namespace?: string` - Optional namespace to get only a subset of translations
+
+**Returns:** Function `t(key, values?)` with method `t.markup(key, tags | { values?, tags })`
+
+#### `t(key, values?)`
+
+- `key: string` - Translation key (supports dot notation)
+- `values?: Record<string, Primitive>` - Values for `{varName}` interpolation (optional)
+
+#### `t.markup(key, options)`
+
+- `key: string` - Translation key
+- `options` - Can be:
+  - `Record<string, (chunks: string) => string>` - Tags only (backward compatible)
+  - `{ values?: Record<string, Primitive>, tags: Record<string, (chunks: string) => string> }` - Tags with interpolation
+
+### `getTranslations()` — `astro-intl/react`
+
+Gets the translation function for React components (uses the global store).
+
+**Returns:** Function `t(key)` with method `t.rich(key, tags)` that returns `ReactNode[]`
+
+### `createGetTranslations(ui, defaultLocale)` — `astro-intl/react`
+
+Standalone factory that doesn't depend on the global store. Useful for passing messages directly.
+
+**Parameters:**
+
+- `ui: Record<string, Record<string, unknown>>` - Object with all messages per locale
+- `defaultLocale: string` - Default locale
+
+**Returns:** `(lang, namespace) => t` — function that returns `t(key)` with `t.rich(key, tags)`
+
+### `getTranslations()` — `astro-intl/svelte`
+
+Gets the translation function for Svelte components (uses the global store).
+
+**Returns:** Function `t(key)` with method `t.rich(key, tagNames?)` that returns `RichSegment[]`
+
+### `createGetTranslations(ui, defaultLocale)` — `astro-intl/svelte`
+
+Standalone factory for Svelte. Same signature as React but `t.rich()` returns `RichSegment[]`.
+
+### `renderRichText(segments, options?)` — `astro-intl/svelte`
+
+Resolves an array of `RichSegment[]` into an HTML string.
+
+**Parameters:**
+
+- `segments: RichSegment[]` - Segments returned by `t.rich()`
+- `options.tags?: Record<string, string>` - Maps tag name to HTML element (e.g., `{ link: 'a' }`)
+- `options.components?: Record<string, (chunks: string) => string>` - Custom functions per tag
+
+**Returns:** `string` - HTML ready to render with `{@html}`
+
+### `getLocale()`
+
+Gets the currently configured locale.
+
+**Returns:** `string` - The locale code (e.g., `'es'`, `'en'`)
+
+### `createIntlMiddleware(options)`
+
+Creates an Astro middleware that automatically calls `setRequestLocale` on each request. Import from `astro-intl/middleware`.
+
+**Options:**
+
+- `locales: string[]` - List of supported locales
+- `defaultLocale?: string` - Default locale (default: `"en"`)
+- `routes?: RoutesMap` - Map of translated routes. When provided, the middleware rewrites translated URLs to their canonical filesystem routes
+
+### `path(routeKey, options?)`
+
+Generates a localized URL for a named route. Import from `astro-intl/routing`.
+
+**Parameters:**
+
+- `routeKey: string` - Route name (key from the `routes` map)
+- `options?.locale` - Target locale (default: current locale)
+- `options?.params` - `Record<string, string>` to substitute `[param]` in the template
+- `options?.encode` - Encode params with `encodeURIComponent` (default: `true`)
+
+**Returns:** `string` - Localized URL (e.g., `"/es/sobre-nosotros"`)
+
+### `switchLocalePath(currentPath, nextLocale)`
+
+Converts the current URL to its equivalent in another locale. Import from `astro-intl/routing`.
+
+**Parameters:**
+
+- `currentPath: string | URL` - Current path (pathname, URL string or URL object)
+- `nextLocale: string` - Target locale
+
+**Returns:** `string` - Equivalent URL in the new locale. Preserves query strings and hashes. If no template matches, falls back to swapping the locale prefix.
+
+---
+
+## 🚀 Development (for contributors)
+
+### Build the package
+
+Before using the package in the playground or any project, you must build it:
+
+```bash
+npm run build
+```
+
+This will generate the JavaScript files and type declarations (`.d.ts`) in the `dist/` folder.
+
+### Development mode
+
+To automatically compile when you make changes:
+
+```bash
+npm run dev
+```
+
+### After building
+
+If you're working in a monorepo with pnpm workspaces, after building run:
+
+```bash
+pnpm install
+```
+
+This will update the symbolic links and types will be available in projects that use the package.
+
+## 📦 Package Structure
+
+```text
+packages/integration/
+├── src/
+│   ├── adapters/
+│   │   ├── react.ts       # React Adapter — getTranslations, createGetTranslations, t.rich() → ReactNode[]
+│   │   └── svelte.ts      # Svelte Adapter — getTranslations, createGetTranslations, t.rich() → RichSegment[], renderRichText()
+│   ├── core.ts            # Barrel — re-exports everything from modules
+│   ├── framework-base.ts  # parseRichSegments() — framework-agnostic base shared by React and Svelte
+│   ├── sanitize.ts        # Locale validation, HTML sanitization, regex escape
+│   ├── interpolation.ts   # {variable} interpolation, nested value access
+│   ├── store.ts           # Per-request state (AsyncLocalStorage + fallback)
+│   ├── translations.ts    # getTranslations for Astro components
+│   ├── routing.ts         # path(), switchLocalePath() — localized URL generation
+│   ├── middleware.ts       # createIntlMiddleware() with translated route rewrites
+│   ├── index.ts           # Public entry point + Astro integration
+│   └── types/
+│       └── index.ts       # TypeScript types (includes RoutesMap)
+├── dist/                  # Compiled files (generated)
+│   ├── *.js               # Compiled JavaScript
+│   └── *.d.ts             # Type declarations
+├── package.json
+└── tsconfig.json
+```
+
+## 🔧 TypeScript Configuration
+
+The package uses:
+
+- `module: "Node16"` for full ESM support
+- `declaration: true` to generate `.d.ts` files
+- Imports with `.js` extension for ESM compatibility
+
+## 📝 Important Notes
+
+1. **Always build before testing**: Changes in `src/` are not reflected until you run `npm run build`
+2. **dist/ files in .gitignore**: Compiled files are not uploaded to git, they are generated on each installation
+3. **.js extensions in imports**: Although the source code is TypeScript, imports must use `.js` for Node16/ESM compatibility