astro-intl 1.0.0

package/README.md

@@ -0,0 +1,295 @@
+# 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**: Funciones específicas para componentes React con `t.rich()`
+- 🎨 **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
+
+## 📦 Instalación
+
+```bash
+npm install astro-intl
+# o
+pnpm add astro-intl
+# o
+yarn add astro-intl
+```
+
+## ⚙️ Configuración
+
+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({
+      enabled: true, // opcional, por defecto es true
+    }),
+  ],
+});
+```
+
+## 🎯 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>
+```
+
+### 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>`
+})} />
+```
+
+### En componentes React
+
+```tsx
+import { getTranslationsReact } from "astro-intl";
+
+export function MyComponent() {
+  const t = getTranslationsReact();
+
+  return (
+    <div>
+      <h1>{t("welcome")}</h1>
+      <nav>
+        <a href="/">{t("nav.home")}</a>
+      </nav>
+    </div>
+  );
+}
+```
+
+### Traducciones con componentes React (rich text)
+
+```tsx
+import { getTranslationsReact } from "astro-intl";
+
+export function MyComponent() {
+  const t = getTranslationsReact();
+
+  // 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>
+  );
+}
+```
+
+### 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>
+```
+
+## 📚 API Reference
+
+### `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],
+}));
+```
+
+### `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)` con método `t.markup(key, tags)`
+
+### `getTranslationsReact<T>(namespace?)`
+
+Obtiene la función de traducción para componentes React.
+
+**Parámetros:**
+
+- `namespace?: string` - Namespace opcional
+
+**Retorna:** Función `t(key)` con método `t.rich(key, tags)`
+
+### `getLocale()`
+
+Obtiene el locale actual configurado.
+
+**Retorna:** `string` - El código del locale (ej: 'es', 'en')
+
+---
+
+## 🚀 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
+
+```
+packages/integration/
+├── src/
+│   ├── core.ts          # Lógica principal
+│   ├── react.ts         # Integración con React
+│   ├── index.ts         # Exports públicos
+│   └── types/
+│       └── index.ts     # Tipos TypeScript
+├── 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

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

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

package/dist/__tests__/core.test.js

@@ -0,0 +1,206 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { setRequestLocale, getLocale, getTranslations, getNestedValue, __resetRequestConfig, } from "../core.js";
+describe("core.ts", () => {
+    beforeEach(() => {
+        __resetRequestConfig();
+    });
+    describe("getNestedValue", () => {
+        it("should get nested values from object", () => {
+            const obj = {
+                user: {
+                    name: "John",
+                    address: {
+                        city: "New York",
+                    },
+                },
+            };
+            expect(getNestedValue(obj, "user.name")).toBe("John");
+            expect(getNestedValue(obj, "user.address.city")).toBe("New York");
+        });
+        it("should return undefined for non-existent paths", () => {
+            const obj = { user: { name: "John" } };
+            expect(getNestedValue(obj, "user.age")).toBeUndefined();
+            expect(getNestedValue(obj, "nonexistent.path")).toBeUndefined();
+        });
+        it("should block prototype pollution attempts", () => {
+            const obj = { user: { name: "John" } };
+            expect(getNestedValue(obj, "__proto__")).toBeUndefined();
+            expect(getNestedValue(obj, "constructor")).toBeUndefined();
+            expect(getNestedValue(obj, "prototype")).toBeUndefined();
+        });
+    });
+    describe("setRequestLocale", () => {
+        it("should set locale from URL pathname", async () => {
+            const url = new URL("https://example.com/es/about");
+            const config = {
+                locale: "es",
+                messages: { greeting: "Hola" },
+            };
+            await setRequestLocale(url, () => config);
+            expect(getLocale()).toBe("es");
+        });
+        it("should default to 'en' when no locale in URL", async () => {
+            const url = new URL("https://example.com/");
+            const config = {
+                locale: "en",
+                messages: { greeting: "Hello" },
+            };
+            await setRequestLocale(url, () => config);
+            expect(getLocale()).toBe("en");
+        });
+        it("should accept async config function", async () => {
+            const url = new URL("https://example.com/fr/home");
+            const config = {
+                locale: "fr",
+                messages: { greeting: "Bonjour" },
+            };
+            await setRequestLocale(url, async () => {
+                return new Promise((resolve) => {
+                    setTimeout(() => resolve(config), 10);
+                });
+            });
+            expect(getLocale()).toBe("fr");
+        });
+        it("should sanitize and validate locale", async () => {
+            const url = new URL("https://example.com/pt-BR/home");
+            const config = {
+                locale: "pt-BR",
+                messages: { greeting: "Olá" },
+            };
+            await setRequestLocale(url, () => config);
+            expect(getLocale()).toBe("pt-BR");
+        });
+        it("should throw error for invalid locale format", async () => {
+            const url = new URL("https://example.com/invalid@locale/home");
+            const config = {
+                locale: "invalid@locale",
+                messages: {},
+            };
+            await expect(setRequestLocale(url, () => config)).rejects.toThrow(/Invalid locale/);
+        });
+    });
+    describe("getLocale", () => {
+        it("should throw error when called before setRequestLocale", () => {
+            expect(() => getLocale()).toThrow(/No request config found/);
+        });
+        it("should return current locale after setRequestLocale", async () => {
+            const url = new URL("https://example.com/de/page");
+            await setRequestLocale(url, () => ({
+                locale: "de",
+                messages: {},
+            }));
+            expect(getLocale()).toBe("de");
+        });
+    });
+    describe("getTranslations", () => {
+        beforeEach(async () => {
+            const url = new URL("https://example.com/en/home");
+            await setRequestLocale(url, () => ({
+                locale: "en",
+                messages: {
+                    common: {
+                        greeting: "Hello",
+                        farewell: "Goodbye",
+                        nested: {
+                            deep: "Deep value",
+                        },
+                    },
+                    home: {
+                        title: "Welcome Home",
+                        description: "This is the home page",
+                    },
+                },
+            }));
+        });
+        it("should throw error when called before setRequestLocale", () => {
+            __resetRequestConfig();
+            expect(() => getTranslations()).toThrow(/No request config found/);
+        });
+        it("should get translations without namespace", () => {
+            const t = getTranslations();
+            expect(t("common.greeting")).toBe("Hello");
+            expect(t("home.title")).toBe("Welcome Home");
+        });
+        it("should get translations with namespace", () => {
+            const t = getTranslations("common");
+            expect(t("greeting")).toBe("Hello");
+            expect(t("farewell")).toBe("Goodbye");
+        });
+        it("should handle nested keys", () => {
+            const t = getTranslations("common");
+            expect(t("nested.deep")).toBe("Deep value");
+        });
+        it("should return key when translation not found", () => {
+            const t = getTranslations("common");
+            expect(t("nonexistent")).toBe("nonexistent");
+        });
+        describe("t.markup", () => {
+            it("should interpolate HTML tags", async () => {
+                const url = new URL("https://example.com/en/home");
+                await setRequestLocale(url, () => ({
+                    locale: "en",
+                    messages: {
+                        text: "Click <link>here</link> to continue",
+                    },
+                }));
+                const t = getTranslations();
+                const result = t.markup("text", {
+                    link: (chunks) => `<a href="/test">${chunks}</a>`,
+                });
+                expect(result).toBe('Click <a href="/test">here</a> to continue');
+            });
+            it("should handle multiple tags", async () => {
+                const url = new URL("https://example.com/en/home");
+                await setRequestLocale(url, () => ({
+                    locale: "en",
+                    messages: {
+                        text: "Text with <bold>bold</bold> and <italic>italic</italic>",
+                    },
+                }));
+                const t = getTranslations();
+                const result = t.markup("text", {
+                    bold: (chunks) => `<strong>${chunks}</strong>`,
+                    italic: (chunks) => `<em>${chunks}</em>`,
+                });
+                expect(result).toBe("Text with <strong>bold</strong> and <em>italic</em>");
+            });
+            it("should sanitize dangerous HTML", async () => {
+                const url = new URL("https://example.com/en/home");
+                await setRequestLocale(url, () => ({
+                    locale: "en",
+                    messages: {
+                        dangerous: "<script>alert('xss')</script>Safe text",
+                    },
+                }));
+                const t = getTranslations();
+                const result = t.markup("dangerous", {});
+                expect(result).not.toContain("<script>");
+                expect(result).toContain("Safe text");
+            });
+            it("should remove event handlers", async () => {
+                const url = new URL("https://example.com/en/home");
+                await setRequestLocale(url, () => ({
+                    locale: "en",
+                    messages: {
+                        text: '<div onclick="alert()">Click</div>',
+                    },
+                }));
+                const t = getTranslations();
+                const result = t.markup("text", {});
+                expect(result).not.toContain("onclick");
+            });
+            it("should remove javascript: URIs", async () => {
+                const url = new URL("https://example.com/en/home");
+                await setRequestLocale(url, () => ({
+                    locale: "en",
+                    messages: {
+                        text: '<a href="javascript:alert()">Link</a>',
+                    },
+                }));
+                const t = getTranslations();
+                const result = t.markup("text", {});
+                expect(result).not.toContain("javascript:");
+            });
+        });
+    });
+});

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

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

package/dist/__tests__/integration.test.js

@@ -0,0 +1,261 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { setRequestLocale, getLocale, getTranslations, getTranslationsReact, __resetRequestConfig, } from "../index.js";
+describe("Integration Tests", () => {
+    beforeEach(() => {
+        __resetRequestConfig();
+    });
+    describe("Complete workflow", () => {
+        it("should handle complete translation workflow", async () => {
+            const url = new URL("https://example.com/es/products");
+            const getRequestConfig = (locale) => {
+                const messages = {
+                    en: {
+                        common: {
+                            greeting: "Hello",
+                            welcome: "Welcome to our site",
+                        },
+                        products: {
+                            title: "Our Products",
+                            description: "Browse our amazing products",
+                        },
+                    },
+                    es: {
+                        common: {
+                            greeting: "Hola",
+                            welcome: "Bienvenido a nuestro sitio",
+                        },
+                        products: {
+                            title: "Nuestros Productos",
+                            description: "Explora nuestros increíbles productos",
+                        },
+                    },
+                };
+                return {
+                    locale,
+                    messages: messages[locale],
+                };
+            };
+            await setRequestLocale(url, getRequestConfig);
+            expect(getLocale()).toBe("es");
+            const tCommon = getTranslations("common");
+            expect(tCommon("greeting")).toBe("Hola");
+            expect(tCommon("welcome")).toBe("Bienvenido a nuestro sitio");
+            const tProducts = getTranslations("products");
+            expect(tProducts("title")).toBe("Nuestros Productos");
+            expect(tProducts("description")).toBe("Explora nuestros increíbles productos");
+        });
+        it("should handle locale switching", async () => {
+            const getRequestConfig = (locale) => {
+                const messages = {
+                    en: { greeting: "Hello" },
+                    fr: { greeting: "Bonjour" },
+                    de: { greeting: "Guten Tag" },
+                };
+                return {
+                    locale,
+                    messages: messages[locale],
+                };
+            };
+            const urlEn = new URL("https://example.com/en/page");
+            await setRequestLocale(urlEn, getRequestConfig);
+            expect(getLocale()).toBe("en");
+            expect(getTranslations()("greeting")).toBe("Hello");
+            const urlFr = new URL("https://example.com/fr/page");
+            await setRequestLocale(urlFr, getRequestConfig);
+            expect(getLocale()).toBe("fr");
+            expect(getTranslations()("greeting")).toBe("Bonjour");
+            const urlDe = new URL("https://example.com/de/page");
+            await setRequestLocale(urlDe, getRequestConfig);
+            expect(getLocale()).toBe("de");
+            expect(getTranslations()("greeting")).toBe("Guten Tag");
+        });
+        it("should work with deeply nested translations", async () => {
+            const url = new URL("https://example.com/en/page");
+            await setRequestLocale(url, () => ({
+                locale: "en",
+                messages: {
+                    app: {
+                        navigation: {
+                            header: {
+                                menu: {
+                                    home: "Home",
+                                    about: "About Us",
+                                    contact: "Contact",
+                                },
+                            },
+                        },
+                    },
+                },
+            }));
+            const t = getTranslations("app");
+            expect(t("navigation.header.menu.home")).toBe("Home");
+            expect(t("navigation.header.menu.about")).toBe("About Us");
+            expect(t("navigation.header.menu.contact")).toBe("Contact");
+        });
+        it("should handle markup with complex HTML", async () => {
+            const url = new URL("https://example.com/en/page");
+            await setRequestLocale(url, () => ({
+                locale: "en",
+                messages: {
+                    legal: "By clicking continue, you agree to our <terms>Terms of Service</terms> and <privacy>Privacy Policy</privacy>.",
+                },
+            }));
+            const t = getTranslations();
+            const result = t.markup("legal", {
+                terms: (chunks) => `<a href="/terms" class="link">${chunks}</a>`,
+                privacy: (chunks) => `<a href="/privacy" class="link">${chunks}</a>`,
+            });
+            expect(result).toContain('<a href="/terms" class="link">Terms of Service</a>');
+            expect(result).toContain('<a href="/privacy" class="link">Privacy Policy</a>');
+        });
+        it("should handle React translations", async () => {
+            const url = new URL("https://example.com/en/page");
+            await setRequestLocale(url, () => ({
+                locale: "en",
+                messages: {
+                    notification: "You have <count>5</count> new messages",
+                },
+            }));
+            const t = getTranslationsReact();
+            const result = t.rich("notification", {
+                count: (chunks) => `<span class="badge">${chunks}</span>`,
+            });
+            expect(result).toEqual(["You have ", '<span class="badge">5</span>', " new messages"]);
+        });
+    });
+    describe("Error handling", () => {
+        it("should throw descriptive error when accessing translations before setup", () => {
+            expect(() => getLocale()).toThrow("[astro-intl] No request config found. Did you call setRequestLocale()?");
+            expect(() => getTranslations()).toThrow("[astro-intl] No request config found. Did you call setRequestLocale()?");
+            expect(() => getTranslationsReact()).toThrow("[astro-intl] No request config found. Did you call setRequestLocale()?");
+        });
+        it("should handle missing translations gracefully", async () => {
+            const url = new URL("https://example.com/en/page");
+            await setRequestLocale(url, () => ({
+                locale: "en",
+                messages: {
+                    existing: "This exists",
+                },
+            }));
+            const t = getTranslations();
+            expect(t("existing")).toBe("This exists");
+            expect(t("missing")).toBe("missing");
+            expect(t("deeply.nested.missing")).toBe("deeply.nested.missing");
+        });
+    });
+    describe("Security", () => {
+        it("should prevent XSS attacks in markup", async () => {
+            const url = new URL("https://example.com/en/page");
+            await setRequestLocale(url, () => ({
+                locale: "en",
+                messages: {
+                    malicious: '<script>alert("XSS")</script><img src=x onerror="alert(1)">Safe text',
+                },
+            }));
+            const t = getTranslations();
+            const result = t.markup("malicious", {});
+            expect(result).not.toContain("<script>");
+            expect(result).not.toContain("onerror");
+            expect(result).toContain("Safe text");
+        });
+        it("should prevent prototype pollution", async () => {
+            const url = new URL("https://example.com/en/page");
+            await setRequestLocale(url, () => ({
+                locale: "en",
+                messages: {
+                    safe: "Safe value",
+                },
+            }));
+            const t = getTranslations();
+            expect(t("__proto__")).toBe("__proto__");
+            expect(t("constructor")).toBe("constructor");
+            expect(t("prototype")).toBe("prototype");
+        });
+        it("should sanitize javascript: URIs", async () => {
+            const url = new URL("https://example.com/en/page");
+            await setRequestLocale(url, () => ({
+                locale: "en",
+                messages: {
+                    link: '<a href="javascript:alert(1)">Click me</a>',
+                },
+            }));
+            const t = getTranslations();
+            const result = t.markup("link", {});
+            expect(result).not.toContain("javascript:");
+        });
+        it("should sanitize data: URIs", async () => {
+            const url = new URL("https://example.com/en/page");
+            await setRequestLocale(url, () => ({
+                locale: "en",
+                messages: {
+                    image: '<img src="data:text/html,<script>alert(1)</script>">',
+                },
+            }));
+            const t = getTranslations();
+            const result = t.markup("image", {});
+            expect(result).not.toContain("data:");
+        });
+    });
+    describe("Locale validation", () => {
+        it("should accept valid BCP-47 language tags", async () => {
+            const validLocales = ["en", "es", "pt-BR", "zh-CN", "en-US", "fr-CA"];
+            for (const locale of validLocales) {
+                const url = new URL(`https://example.com/${locale}/page`);
+                await setRequestLocale(url, (loc) => ({
+                    locale: loc,
+                    messages: {},
+                }));
+                expect(getLocale()).toBe(locale);
+            }
+        });
+        it("should reject invalid locale formats", async () => {
+            const invalidLocales = ["invalid@locale", "123", "en_US", "en-", "-en", "en--US"];
+            for (const locale of invalidLocales) {
+                const url = new URL(`https://example.com/${locale}/page`);
+                await expect(setRequestLocale(url, () => ({
+                    locale,
+                    messages: {},
+                }))).rejects.toThrow(/Invalid locale/);
+            }
+        });
+    });
+    describe("Performance", () => {
+        it("should handle large message objects efficiently", async () => {
+            const largeMessages = {};
+            for (let i = 0; i < 1000; i++) {
+                largeMessages[`key${i}`] = `Value ${i}`;
+            }
+            const url = new URL("https://example.com/en/page");
+            await setRequestLocale(url, () => ({
+                locale: "en",
+                messages: largeMessages,
+            }));
+            const t = getTranslations();
+            expect(t("key500")).toBe("Value 500");
+            expect(t("key999")).toBe("Value 999");
+        });
+        it("should handle multiple namespace access efficiently", async () => {
+            const url = new URL("https://example.com/en/page");
+            await setRequestLocale(url, () => ({
+                locale: "en",
+                messages: {
+                    ns1: { key: "value1" },
+                    ns2: { key: "value2" },
+                    ns3: { key: "value3" },
+                    ns4: { key: "value4" },
+                    ns5: { key: "value5" },
+                },
+            }));
+            const t1 = getTranslations("ns1");
+            const t2 = getTranslations("ns2");
+            const t3 = getTranslations("ns3");
+            const t4 = getTranslations("ns4");
+            const t5 = getTranslations("ns5");
+            expect(t1("key")).toBe("value1");
+            expect(t2("key")).toBe("value2");
+            expect(t3("key")).toBe("value3");
+            expect(t4("key")).toBe("value4");
+            expect(t5("key")).toBe("value5");
+        });
+    });
+});

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

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

package/dist/__tests__/react.test.js

@@ -0,0 +1,150 @@
+import { describe, it, expect } from "vitest";
+import { createGetTranslationsReact } from "../react.js";
+describe("react.ts", () => {
+    const ui = {
+        en: {
+            common: {
+                greeting: "Hello",
+                farewell: "Goodbye",
+                nested: {
+                    deep: "Deep value",
+                },
+            },
+            home: {
+                title: "Welcome Home",
+                withTags: "Click <link>here</link> to continue",
+                multipleTags: "Text with <bold>bold</bold> and <italic>italic</italic>",
+            },
+        },
+        es: {
+            common: {
+                greeting: "Hola",
+                farewell: "Adiós",
+                nested: {
+                    deep: "Valor profundo",
+                },
+            },
+            home: {
+                title: "Bienvenido a Casa",
+                withTags: "Haz clic <link>aquí</link> para continuar",
+                multipleTags: "Texto con <bold>negrita</bold> y <italic>cursiva</italic>",
+            },
+        },
+    };
+    describe("createGetTranslationsReact", () => {
+        it("should create translation function for default locale", () => {
+            const getT = createGetTranslationsReact(ui, "en");
+            const t = getT("en", "common");
+            expect(t("greeting")).toBe("Hello");
+            expect(t("farewell")).toBe("Goodbye");
+        });
+        it("should create translation function for non-default locale", () => {
+            const getT = createGetTranslationsReact(ui, "en");
+            const t = getT("es", "common");
+            expect(t("greeting")).toBe("Hola");
+            expect(t("farewell")).toBe("Adiós");
+        });
+        it("should handle nested keys", () => {
+            const getT = createGetTranslationsReact(ui, "en");
+            const t = getT("en", "common");
+            expect(t("nested.deep")).toBe("Deep value");
+        });
+        it("should return key when translation not found", () => {
+            const getT = createGetTranslationsReact(ui, "en");
+            const t = getT("en", "common");
+            expect(t("nonexistent")).toBe("nonexistent");
+        });
+        it("should fallback to default locale when locale not found", () => {
+            const getT = createGetTranslationsReact(ui, "en");
+            const t = getT("fr", "common");
+            expect(t("greeting")).toBe("Hello");
+        });
+        it("should work with different namespaces", () => {
+            const getT = createGetTranslationsReact(ui, "en");
+            const tCommon = getT("en", "common");
+            const tHome = getT("en", "home");
+            expect(tCommon("greeting")).toBe("Hello");
+            expect(tHome("title")).toBe("Welcome Home");
+        });
+    });
+    describe("t.rich", () => {
+        it("should interpolate React components", () => {
+            const getT = createGetTranslationsReact(ui, "en");
+            const t = getT("en", "home");
+            const result = t.rich("withTags", {
+                link: (chunks) => `<a>${chunks}</a>`,
+            });
+            expect(result).toEqual(["Click ", "<a>here</a>", " to continue"]);
+        });
+        it("should handle multiple tags", () => {
+            const getT = createGetTranslationsReact(ui, "en");
+            const t = getT("en", "home");
+            const result = t.rich("multipleTags", {
+                bold: (chunks) => `<strong>${chunks}</strong>`,
+                italic: (chunks) => `<em>${chunks}</em>`,
+            });
+            expect(result).toEqual(["Text with ", "<strong>bold</strong>", " and ", "<em>italic</em>"]);
+        });
+        it("should handle text without tags", () => {
+            const getT = createGetTranslationsReact(ui, "en");
+            const t = getT("en", "common");
+            const result = t.rich("greeting", {});
+            expect(result).toEqual(["Hello"]);
+        });
+        it("should work with Spanish locale", () => {
+            const getT = createGetTranslationsReact(ui, "en");
+            const t = getT("es", "home");
+            const result = t.rich("withTags", {
+                link: (chunks) => `<a>${chunks}</a>`,
+            });
+            expect(result).toEqual(["Haz clic ", "<a>aquí</a>", " para continuar"]);
+        });
+        it("should handle nested tags correctly", () => {
+            const customUi = {
+                en: {
+                    test: {
+                        nested: "Start <outer>outer <inner>inner</inner> outer</outer> end",
+                    },
+                },
+            };
+            const getT = createGetTranslationsReact(customUi, "en");
+            const t = getT("en", "test");
+            const result = t.rich("nested", {
+                outer: (chunks) => `[${chunks}]`,
+                inner: (chunks) => `{${chunks}}`,
+            });
+            expect(result).toEqual(["Start ", "[outer {inner} outer]", " end"]);
+        });
+        it("should handle adjacent tags", () => {
+            const customUi = {
+                en: {
+                    test: {
+                        adjacent: "<tag1>First</tag1><tag2>Second</tag2>",
+                    },
+                },
+            };
+            const getT = createGetTranslationsReact(customUi, "en");
+            const t = getT("en", "test");
+            const result = t.rich("adjacent", {
+                tag1: (chunks) => `[${chunks}]`,
+                tag2: (chunks) => `{${chunks}}`,
+            });
+            expect(result).toEqual(["[First]", "{Second}"]);
+        });
+        it("should handle empty chunks", () => {
+            const customUi = {
+                en: {
+                    test: {
+                        empty: "Text <tag></tag> more text",
+                    },
+                },
+            };
+            const getT = createGetTranslationsReact(customUi, "en");
+            const t = getT("en", "test");
+            const result = t.rich("empty", {
+                tag: (chunks) => `[${chunks}]`,
+            });
+            expect(result).toEqual(["Text ", "[]", " more text"]);
+        });
+    });
+});

package/dist/core.d.ts

@@ -0,0 +1,14 @@
+import type { RequestConfig } from "./types/index.js";
+export declare function __resetRequestConfig(): void;
+export type DotPaths<T> = T extends object ? {
+    [K in keyof T & string]: T[K] extends object ? `${K}` | `${K}.${DotPaths<T[K]>}` : `${K}`;
+}[keyof T & string] : never;
+export declare function getNestedValue(obj: Record<string, unknown>, path: string): unknown;
+export declare function setRequestLocale(url: URL, getConfig: (locale: string) => Promise<RequestConfig> | RequestConfig): Promise<void>;
+export declare function getLocale(): string;
+export declare function getTranslations<T extends Record<string, unknown> = Record<string, unknown>>(namespace?: string): ((key: DotPaths<T>) => string) & {
+    markup: (key: DotPaths<T>, tags: Record<string, (chunks: string) => string>) => string;
+};
+export declare function getTranslationsReact<T extends Record<string, unknown> = Record<string, unknown>>(namespace?: string): ((key: DotPaths<T>) => string) & {
+    rich: (key: DotPaths<T>, tags: Record<string, (chunks: string) => import("react").ReactNode>) => import("react").ReactNode[];
+};

package/dist/core.js

@@ -0,0 +1,94 @@
+import { createGetTranslationsReact } from "./react.js";
+// --- Security helpers ---
+const LOCALE_REGEX = /^[a-zA-Z]{2,3}(-[a-zA-Z0-9]{2,8})*$/;
+function sanitizeLocale(locale) {
+    const trimmed = locale.trim();
+    if (!LOCALE_REGEX.test(trimmed)) {
+        throw new Error(`[astro-intl] Invalid locale "${trimmed}". Locale must be a valid BCP-47 language tag (e.g. "en", "es", "pt-BR").`);
+    }
+    return trimmed;
+}
+function escapeRegExp(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+const DANGEROUS_HTML_REGEX = /<\s*\/?\s*(script|iframe|object|embed|form|input|textarea|button|select|meta|link|base|applet|style)\b[^>]*>/gi;
+const EVENT_HANDLER_REGEX = /\s+on\w+\s*=\s*["'][^"']*["']/gi;
+const JAVASCRIPT_URI_REGEX = /\b(href|src|action)\s*=\s*["']\s*javascript\s*:/gi;
+const DATA_URI_REGEX = /\b(href|src|action)\s*=\s*["']\s*data\s*:/gi;
+function sanitizeHtml(html) {
+    return html
+        .replace(DANGEROUS_HTML_REGEX, "")
+        .replace(EVENT_HANDLER_REGEX, "")
+        .replace(JAVASCRIPT_URI_REGEX, "")
+        .replace(DATA_URI_REGEX, "");
+}
+const FORBIDDEN_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+// Global context para almacenar la configuración del request actual
+let globalRequestConfig = null;
+// Función para resetear el config (solo para testing)
+export function __resetRequestConfig() {
+    globalRequestConfig = null;
+}
+export function getNestedValue(obj, path) {
+    return path.split(".").reduce((acc, key) => {
+        if (FORBIDDEN_KEYS.has(key))
+            return undefined;
+        if (acc && typeof acc === "object") {
+            return acc[key];
+        }
+        return undefined;
+    }, obj);
+}
+// Configurar el request actual
+export async function setRequestLocale(url, getConfig) {
+    const [, lang] = url.pathname.split("/");
+    const locale = sanitizeLocale(lang || "en");
+    const config = await getConfig(locale);
+    globalRequestConfig = {
+        locale: config.locale,
+        messages: config.messages,
+    };
+}
+// Obtener el locale actual
+export function getLocale() {
+    if (!globalRequestConfig) {
+        throw new Error("[astro-intl] No request config found. Did you call setRequestLocale()?");
+    }
+    return globalRequestConfig.locale;
+}
+// Obtener traducciones sin pasar locale
+export function getTranslations(namespace) {
+    if (!globalRequestConfig) {
+        throw new Error("[astro-intl] No request config found. Did you call setRequestLocale()?");
+    }
+    const messages = namespace
+        ? globalRequestConfig.messages[namespace]
+        : globalRequestConfig.messages;
+    function t(key) {
+        const value = getNestedValue(messages, key);
+        return typeof value === "string" ? value : key;
+    }
+    const markup = function (key, tags) {
+        let str = t(key);
+        for (const [tag, fn] of Object.entries(tags)) {
+            const escaped = escapeRegExp(tag);
+            const regex = new RegExp(`<${escaped}>(.*?)</${escaped}>`, "g");
+            str = str.replace(regex, (_match, chunks) => fn(chunks));
+        }
+        str = sanitizeHtml(str);
+        return str;
+    };
+    Object.assign(t, { markup });
+    return t;
+}
+// Obtener traducciones para React
+export function getTranslationsReact(namespace) {
+    if (!globalRequestConfig) {
+        throw new Error("[astro-intl] No request config found. Did you call setRequestLocale()?");
+    }
+    const messages = namespace
+        ? globalRequestConfig.messages[namespace]
+        : globalRequestConfig.messages;
+    const ui = { [globalRequestConfig.locale]: { default: messages } };
+    return createGetTranslationsReact(ui, globalRequestConfig.locale)(globalRequestConfig.locale, "default");
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+import type { AstroIntegration } from "astro";
+import { setRequestLocale as _setRequestLocale, getLocale as _getLocale, getTranslations as _getTranslations, getTranslationsReact as _getTranslationsReact, __resetRequestConfig as _resetRequestConfig } from "./core.js";
+export type MyIntegrationOptions = {
+    enabled?: boolean;
+};
+export default function myIntegration(options?: MyIntegrationOptions): AstroIntegration;
+export declare const setRequestLocale: typeof _setRequestLocale;
+export declare const getLocale: typeof _getLocale;
+export declare const getTranslations: typeof _getTranslations;
+export declare const getTranslationsReact: typeof _getTranslationsReact;
+export declare const __resetRequestConfig: typeof _resetRequestConfig;
+export type { RequestConfig } from "./types/index.js";
+export type { DotPaths } from "./core.js";

package/dist/index.js

@@ -0,0 +1,20 @@
+import { setRequestLocale as _setRequestLocale, getLocale as _getLocale, getTranslations as _getTranslations, getTranslationsReact as _getTranslationsReact, __resetRequestConfig as _resetRequestConfig, } from "./core.js";
+export default function myIntegration(options = {}) {
+    const { enabled = true } = options;
+    return {
+        name: "astro-intl",
+        hooks: {
+            "astro:config:setup": ({ logger }) => {
+                if (!enabled)
+                    return;
+                logger.info("[astro-intl] loaded");
+            },
+        },
+    };
+}
+// Exportar API
+export const setRequestLocale = _setRequestLocale;
+export const getLocale = _getLocale;
+export const getTranslations = _getTranslations;
+export const getTranslationsReact = _getTranslationsReact;
+export const __resetRequestConfig = _resetRequestConfig;

package/dist/react.d.ts

@@ -0,0 +1,5 @@
+import type { ReactNode } from "react";
+import { type DotPaths } from "./core.js";
+export declare function createGetTranslationsReact<UI extends Record<string, Record<string, unknown>>, DefaultLocale extends keyof UI>(ui: UI, defaultLocale: DefaultLocale): <N extends keyof UI[DefaultLocale]>(lang: string | undefined, namespace: N) => ((key: DotPaths<UI[DefaultLocale][N]>) => string) & {
+    rich: (key: DotPaths<UI[DefaultLocale][N]>, tags: Record<string, (chunks: string) => ReactNode>) => ReactNode[];
+};

package/dist/react.js

@@ -0,0 +1,44 @@
+import { getNestedValue } from "./core.js";
+function escapeRegExp(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+export function createGetTranslationsReact(ui, defaultLocale) {
+    return function getTranslationsReact(lang, namespace) {
+        const resolvedLang = lang && lang in ui ? lang : defaultLocale;
+        const messages = ui[resolvedLang][namespace];
+        function t(key) {
+            const value = getNestedValue(messages, key);
+            return typeof value === "string" ? value : key;
+        }
+        const rich = function (key, tags) {
+            const str = t(key);
+            // Función recursiva para procesar tags anidados
+            function processString(input) {
+                const tagNames = Object.keys(tags).map(escapeRegExp);
+                const regex = new RegExp(`<(${tagNames.join("|")})>(.*?)<\\/(\\1)>`, "g");
+                const result = [];
+                let lastIndex = 0;
+                let match;
+                while ((match = regex.exec(input)) !== null) {
+                    if (match.index > lastIndex) {
+                        result.push(input.slice(lastIndex, match.index));
+                    }
+                    const [, tag, chunks] = match;
+                    // Procesar recursivamente el contenido del tag
+                    const processedChunks = processString(chunks);
+                    const chunksAsString = processedChunks
+                        .map((chunk) => (typeof chunk === "string" ? chunk : ""))
+                        .join("");
+                    result.push(tags[tag](chunksAsString));
+                    lastIndex = match.index + match[0].length;
+                }
+                if (lastIndex < input.length)
+                    result.push(input.slice(lastIndex));
+                return result;
+            }
+            return processString(str);
+        };
+        Object.assign(t, { rich });
+        return t;
+    };
+}

package/dist/types/index.d.ts

@@ -0,0 +1,4 @@
+export type RequestConfig = {
+    locale: string;
+    messages: Record<string, unknown>;
+};

package/dist/types/index.js

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

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "astro-intl",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Sistema de internacionalización simple y type-safe para Astro, inspirado en next-intl",
+  "keywords": [
+    "astro",
+    "astro-integration",
+    "i18n",
+    "internationalization",
+    "intl",
+    "translations",
+    "typescript"
+  ],
+  "author": "Erick Cruz <erickj.cruzs@gmail.com>",
+  "license": "MIT",
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest run --coverage",
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch",
+    "lint": "eslint . --max-warnings 0",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
+  },
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "peerDependencies": {
+    "astro": "^4 || ^5"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ErickCSS/astro-intl"
+  },
+  "bugs": {
+    "url": "https://github.com/ErickCSS/astro-intl/issues"
+  },
+  "homepage": "https://github.com/ErickCSS/astro-intl#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.17.0",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/react": "^18.3.18",
+    "@vitest/ui": "^4.0.18",
+    "astro": "^5.17.3",
+    "eslint": "^9.17.0",
+    "happy-dom": "^20.7.0",
+    "prettier": "^3.4.2",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.19.1",
+    "vitest": "^4.0.18"
+  }
+}