@gschz/astro-plugin-i18n 0.3.7-rc.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Gera Schz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,348 @@
+# astro-plugin-i18n
+
+Plugin de internacionalización (i18n) para Astro, enfocado en la simplicidad y el rendimiento.
+
+[![NPM Version](https://img.shields.io/npm/v/@hkxdv/astro-plugin-i18n)](https://www.npmjs.com/package/@hkxdv/astro-plugin-i18n)
+[![License](https://img.shields.io/npm/l/@hkxdv/astro-plugin-i18n)](https://github.com/hkxdv/astro-plugin-i18n/blob/main/LICENSE)
+
+## Estado del Proyecto
+
+Este paquete fue reconstruido a partir de las versiones previamente publicadas en NPM bajo `@hkxdv/astro-plugin-i18n`, recuperando su API, componentes y flujo de integración para poder continuar su mantenimiento.
+
+Las próximas publicaciones se realizarán desde la cuenta `gschz`. La intención es mantener compatibilidad con la API pública recuperada y estabilizar el paquete antes de su nueva publicación.
+
+## Motivación
+
+¿Por qué otro plugin de i18n para Astro? Este plugin fue creado con el objetivo de ofrecer una solución **simple, eficiente y fácil de integrar**, abordando algunas complejidades encontradas en otras herramientas y enfocándose en una experiencia de desarrollador fluida.
+
+## Características
+
+- **Configuración Obligatoria Simplificada**: Configura idiomas y opciones a través de la integración de Astro.
+- **Fácil de usar**: Archivos JSON estándar para las traducciones.
+- **Componentes Incluidos**: Componentes listos para usar en Astro (`.astro`) y React (`.tsx`).
+- **Sin FOUC (Flash of Untranslated Content)**: Renderiza el texto traducido inicial en el servidor.
+- **TypeScript**: Soporte completo con tipos generados automáticamente para las claves de traducción (opcional).
+- **Detección Automática**: Detecta el idioma preferido del usuario (localStorage, navegador) en el cliente.
+- **Flexible**: Funciona con o sin React.
+
+## Instalación
+
+```bash
+bun add @hkxdv/astro-plugin-i18n
+```
+
+Para instalar una versión de prueba publicada en NPM (canal `next`):
+
+```bash
+bun add @hkxdv/astro-plugin-i18n@next
+```
+
+Si estás probando localmente antes de publicar:
+
+```bash
+bun add ../astro-plugin-i18n
+```
+
+## Flujo recomendado de publicación (pruebas)
+
+Antes de publicar una versión estable (`latest`), se recomienda publicar una release candidata en `next`, probarla en un proyecto consumidor real (por ejemplo `test-i18n`) y corregir incidencias antes de promoverla.
+
+1. Generar siguiente versión `rc`:
+
+```bash
+bun run version:rc
+```
+
+2. Publicar al canal de pruebas (`next`):
+
+```bash
+bun run publish:next
+```
+
+3. Instalar esa versión en el proyecto de prueba:
+
+```bash
+# dentro del proyecto consumidor
+bun add @hkxdv/astro-plugin-i18n@next
+```
+
+4. Validar `dev`, `build` y comportamiento de i18n en cliente/SSR.
+
+5. Promover a estable cuando esté listo:
+
+```bash
+bun run publish:latest
+```
+
+## Configuración (Obligatoria con Integración)
+
+Este plugin **requiere** configuración a través de la integración de Astro en `astro.config.mjs`.
+
+```javascript
+// astro.config.mjs
+import { defineConfig } from "astro/config";
+import i18n from "@hkxdv/astro-plugin-i18n/integration";
+// Opcional: importa tu integración de React si la usas
+// import react from "@astrojs/react";
+
+export default defineConfig({
+  integrations: [
+    // react(), // Si usas React
+    i18n({
+      // --- Opciones Requeridas ---
+      defaultLang: "es", // Idioma por defecto de tu sitio
+      supportedLangs: ["es", "en"], // Lista de idiomas soportados (debe incluir defaultLang)
+
+      // --- Opciones Opcionales ---
+      translationsDir: "./src/i18n", // Directorio de traducciones (relativo a la raíz)
+      autoDetect: true, // Detectar idioma del navegador como fallback
+      generateTypes: true, // Generar tipos para claves de traducción
+      typesOutputPath: "./src/types/i18n-types.d.ts", // Dónde guardar los tipos generados
+      missingKeyStrategy: "key", // Qué hacer si falta una clave ('key', 'empty', 'error')
+    }),
+  ],
+});
+```
+
+**Importante:**
+
+- `defaultLang` y `supportedLangs` son **obligatorias**.
+- El `defaultLang` debe estar incluido en `supportedLangs`.
+
+## Uso Rápido
+
+### 1. Crear Archivos de Traducción
+
+Crea un directorio (por defecto `src/i18n`) con tus archivos de traducción en formato JSON. El nombre de cada archivo debe ser el código del idioma (ej. `es.json`, `en.json`).
+
+```json
+// src/i18n/es.json
+{
+  "welcome": "Bienvenido a mi sitio",
+  "nav": {
+    "home": "Inicio",
+    "about": "Acerca de"
+  }
+}
+```
+
+```json
+// src/i18n/en.json
+{
+  "welcome": "Welcome to my site",
+  "nav": {
+    "home": "Home",
+    "about": "About"
+  }
+}
+```
+
+### 2. Inicializar el Idioma en el Cliente
+
+En tu layout principal (ej. `src/layouts/Layout.astro`), añade un script para inicializar el estado del idioma en el cliente. Esto es crucial para la detección de preferencias del usuario y cambios dinámicos.
+
+```astro
+{/* src/layouts/Layout.astro */}
+---
+// Puedes obtener el idioma actual en el servidor si lo necesitas
+import { getCurrentLanguage, getTranslationsForLanguage } from '@hkxdv/astro-plugin-i18n';
+const serverLang = getCurrentLanguage(); // Obtendrá el idioma por defecto aquí
+const initialTranslations = await getTranslationsForLanguage(serverLang);
+---
+<html lang={serverLang}>
+  <head>
+    {/* ... otras etiquetas ... */}
+
+    {/* Script para inyectar estado inicial (Optimización FOUC) */}
+    <script define:vars={{ currentLang: serverLang, initialTranslations: initialTranslations || {} }}>
+      window.__INITIAL_I18N_STATE__ = {
+        lang: currentLang,
+        translations: initialTranslations,
+      };
+    </script>
+  </head>
+  <body>
+    <slot /> {/* Contenido de la página */}
+
+    {/* Script Principal del Cliente */}
+    <script>
+      import { setupLanguage } from "@hkxdv/astro-plugin-i18n";
+
+      // Inicializa el idioma en el cliente.
+      // Usará __INITIAL_I18N_STATE__, luego localStorage, luego navegador (si autoDetect=true)
+      // y aplicará el idioma correcto.
+      setupLanguage();
+    </script>
+  </body>
+</html>
+```
+
+### 3. Usar Componentes de Traducción
+
+#### Componente Astro (`I18nText.astro`)
+
+```astro
+{/* En cualquier página .astro */}
+---
+import I18nText from '@hkxdv/astro-plugin-i18n/components/I18nText.astro';
+---
+<h1><I18nText key="welcome" /></h1>
+
+<nav>
+  <a href="/"><I18nText key="nav.home" /></a>
+  <a href="/about"><I18nText key="nav.about" /></a>
+</nav>
+```
+
+#### Componente React (`TranslatedText.tsx`)
+
+Necesitas tener la integración de React configurada.
+
+```jsx
+// En un componente .jsx o .tsx (recuerda añadir client:load o similar en Astro)
+import TranslatedText from "@hkxdv/astro-plugin-i18n/components/TranslatedText";
+
+function MyReactComponent() {
+  return (
+    <div>
+      <h1>
+        <TranslatedText textKey="welcome" />
+      </h1>
+      <nav>
+        <a href="/">
+          <TranslatedText textKey="nav.home" />
+        </a>
+        <a href="/about">
+          <TranslatedText textKey="nav.about" />
+        </a>
+      </nav>
+    </div>
+  );
+}
+```
+
+## API
+
+### Componentes
+
+- **`I18nText.astro`**: Muestra texto traducido en componentes Astro. Renderiza en el servidor.
+  - Props: `key` (obligatoria), `values`, `lang`, `element`, `class`, ...otros atributos HTML.
+
+  ```astro
+  <I18nText key="welcome" element="h1" class="title" />
+  ```
+
+- **`TranslatedText`** (`.tsx`): Componente React para mostrar texto traducido. Se actualiza dinámicamente con los cambios de idioma.
+  - Props: `textKey` (obligatoria), `values`, `lang`, `as` (elemento/componente a renderizar), ...otros atributos HTML.
+
+  ```jsx
+  <TranslatedText textKey="welcome" as="h1" className="title" />
+  ```
+
+- **`LangToggle`** (`.tsx`): Componente React que renderiza un `<select>` para cambiar el idioma.
+  - Props: `languages` (obligatoria: `Array<{code: string, label: string}>`), `className`, `currentLang`.
+
+  ```jsx
+  // Necesitas pasar la lista de idiomas
+  const availableLanguages = [
+    { code: "es", label: "Español" },
+    { code: "en", label: "English" },
+  ];
+
+  <LangToggle languages={availableLanguages} client:load />;
+  ```
+
+  Nota: en la implementación actual recuperada, `LangToggle` renderiza un dropdown personalizado con botones, no un `<select>` nativo.
+
+### Funciones
+
+- **`t(key, options)`**: (Cliente/Servidor) Función síncrona principal para obtener una traducción. En el cliente usa una caché interna poblada al inicio. En el servidor/build usa `getTranslation`.
+
+  ```javascript
+  import { t } from "@hkxdv/astro-plugin-i18n";
+  const text = t("welcome"); // Síncrono
+  const textWithVar = t("greeting", { values: { name: "Astro" } });
+  ```
+
+- **`getCurrentLanguage()`**: (Cliente/Servidor) Obtiene el código del idioma actual detectado. En el servidor siempre devolverá el `defaultLang`.
+
+  ```javascript
+  import { getCurrentLanguage } from "@hkxdv/astro-plugin-i18n";
+  const lang = getCurrentLanguage(); // "es", "en", etc.
+  ```
+
+- **`changeLanguage(lang)`**: (Cliente) Cambia el idioma de la aplicación, actualiza `localStorage` y dispara el evento `languagechange`.
+
+  ```javascript
+  import { changeLanguage } from "@hkxdv/astro-plugin-i18n";
+  changeLanguage("en");
+  ```
+
+- **`setupLanguage()`**: (Cliente) Función **esencial** para llamar en un script de cliente (preferiblemente en el layout). Inicializa el estado del idioma detectando preferencias y aplicando el idioma correcto.
+
+  ```javascript
+  // En <script> de tu layout
+  import { setupLanguage } from "@hkxdv/astro-plugin-i18n";
+  setupLanguage();
+  ```
+
+- **`useTranslation()`**: (React Hook) Hook para usar dentro de componentes React. Proporciona `language` (estado reactivo), `t` (vinculada al idioma actual) y `changeLanguage`.
+
+  ```jsx
+  import { useTranslation } from "@hkxdv/astro-plugin-i18n";
+
+  function MyComponent() {
+    const { t, language, changeLanguage } = useTranslation();
+    return (
+      <div>
+        <p>{t("welcome")}</p>
+        <button onClick={() => changeLanguage("en")}>English</button>
+      </div>
+    );
+  }
+  ```
+
+- **`getTranslationsForLanguage(lang)`**: (Server/Build) Carga y devuelve _todas_ las traducciones para un idioma desde su archivo JSON. Útil en el servidor para inyectar estado inicial.
+- **`getTranslation(key, lang)`**: (Server/Build) Obtiene una _única_ traducción de forma asíncrona desde el archivo JSON.
+- **`translateAsync(key, options)`**: (Server/Build) Similar a `getTranslation` pero permite pasar `values`.
+
+## Ejemplos Avanzados
+
+### Variables en Traducciones
+
+Define placeholders en tu JSON:
+
+```jsonc
+// es.json
+{
+  "greeting": "Hola {name}, tienes {count} mensajes nuevos.",
+}
+```
+
+Usa la opción `values`:
+
+```astro
+<I18nText key="greeting" values={{ name: "Gera", count: 3 }} />
+```
+
+```jsx
+<TranslatedText textKey="greeting" values={{ name: "Gera", count: 3 }} />
+```
+
+```javascript
+const message = t("greeting", { values: { name: "Gera", count: 3 } });
+```
+
+### Elementos HTML Personalizados
+
+Con `I18nText`:
+
+```astro
+<I18nText key="welcome" element="h1" class="text-2xl font-bold" />
+```
+
+Con `TranslatedText`:
+
+```jsx
+<TranslatedText textKey="welcome" as="h1" className="text-2xl font-bold" />
+```

package/dist/components/I18nText.astro

@@ -0,0 +1,38 @@
+---
+import { getCurrentLanguage } from "@hkxdv/astro-plugin-i18n";
+import { translateAsync } from "@hkxdv/astro-plugin-i18n";
+import type { TranslationKey } from "@hkxdv/astro-plugin-i18n";
+
+interface Props {
+  key: TranslationKey;
+  lang?: string;
+  values?: Record<string, string | number | boolean>;
+  class?: string;
+  element?:
+    | "span"
+    | "div"
+    | "p"
+    | "h1"
+    | "h2"
+    | "h3"
+    | "h4"
+    | "h5"
+    | "h6"
+    | "label";
+  [key: string]: any;
+}
+
+const {
+  key,
+  lang,
+  values,
+  element: Element = "span",
+  class: className,
+  ...rest
+} = Astro.props;
+
+const targetLang = lang || getCurrentLanguage(Astro.locals);
+const translatedText = await translateAsync(key, { lang: targetLang, values });
+---
+
+<Element class={className} {...rest}>{translatedText}</Element>

package/dist/components/LangToggle.d.ts

@@ -0,0 +1,14 @@
+import * as React from 'react';
+import { L as Language } from '../index-Dyxmdid5.js';
+
+interface LangToggleProps {
+    className?: string;
+    languages: Array<{
+        code: Language;
+        label: string;
+    }>;
+    currentLang?: Language;
+}
+declare const LangToggle: React.FC<LangToggleProps>;
+
+export { LangToggle, LangToggle as default };