@intlayer/docs 5.7.7 → 5.8.0-canary.0

package/docs/en-GB/packages/next-intlayer/index.md

@@ -110,8 +110,8 @@ const clientComponentContent = {
   content: {
     myTranslatedContent: t({
       en: "Hello World",
-      fr: "Bonjour le monde",
       es: "Hola Mundo",
+      fr: "Bonjour le monde",
     }),
     numberOfCar: enu({
       "<-1": "Less than minus one car",
@@ -136,8 +136,8 @@ const clientComponentContent = {
   content: {
     myTranslatedContent: t({
       en: "Hello World",
-      fr: "Bonjour le monde",
       es: "Hola Mundo",
+      fr: "Bonjour le monde",
     }),
     numberOfCar: enu({
       "<-1": "Less than minus one car",
@@ -162,8 +162,8 @@ const clientComponentContent = {
   content: {
     myTranslatedContent: t({
       en: "Hello World",
-      fr: "Bonjour le monde",
       es: "Hola Mundo",
+      fr: "Bonjour le monde",
     }),
     numberOfCar: enu({
       "<-1": "Less than minus one car",

package/docs/en-GB/packages/react-intlayer/index.md

@@ -110,8 +110,8 @@ const component1Content = {
   content: {
     myTranslatedContent: t({
       en: "Hello World",
-      fr: "Bonjour le monde",
       es: "Hola Mundo",
+      fr: "Bonjour le monde",
     }),
     numberOfCar: enu({
       "<-1": "Less than minus one car",
@@ -136,8 +136,8 @@ const component1Content = {
   content: {
     myTranslatedContent: t({
       en: "Hello World",
-      fr: "Bonjour le monde",
       es: "Hola Mundo",
+      fr: "Bonjour le monde",
     }),
     numberOfCar: enu({
       "<-1": "Less than minus one car",
@@ -162,8 +162,8 @@ const component1Content = {
   content: {
     myTranslatedContent: t({
       en: "Hello World",
-      fr: "Bonjour le monde",
       es: "Hola Mundo",
+      fr: "Bonjour le monde",
     }),
     numberOfCar: enu({
       "<-1": "Less than minus one car",

package/docs/es/CI_CD.md

@@ -1,8 +1,8 @@
 ---
 createdAt: 2025-05-20
-updatedAt: 2025-06-29
+updatedAt: 2025-08-13
 title: Integración CI/CD
-description: Aprende cómo integrar Intlayer en tu pipeline de CI/CD para la gestión y despliegue automatizado de contenido.
+description: Aprende cómo integrar Intlayer en tu pipeline CI/CD para la gestión y despliegue automatizado de contenido.
 keywords:
   - CI/CD
   - Integración Continua
@@ -19,13 +19,13 @@ slugs:
 
 # Generación Automática de Traducciones en un Pipeline CI/CD
 
-Intlayer permite la generación automática de traducciones para tus archivos de declaración de contenido. Existen varias formas de lograr esto dependiendo de tu flujo de trabajo.
+Intlayer permite la generación automática de traducciones para tus archivos de declaración de contenido. Existen múltiples formas de lograr esto dependiendo de tu flujo de trabajo.
 
 ## Uso del CMS
 
-Con Intlayer, puedes adoptar un flujo de trabajo donde solo se declara un único locale localmente, mientras que todas las traducciones se gestionan de forma remota a través del CMS. Esto permite que el contenido y las traducciones estén completamente desacoplados de la base de código, ofreciendo mayor flexibilidad para los editores de contenido y habilitando la recarga dinámica del contenido (sin necesidad de reconstruir la aplicación para aplicar cambios).
+Con Intlayer, puedes adoptar un flujo de trabajo donde solo se declara un único locale localmente, mientras que todas las traducciones se gestionan de forma remota a través del CMS. Esto permite que el contenido y las traducciones estén completamente desacoplados del código base, ofreciendo más flexibilidad para los editores de contenido y habilitando la recarga en caliente del contenido (no es necesario reconstruir la aplicación para aplicar cambios).
 
-### Configuración de ejemplo
+### Configuración de Ejemplo
 
 ```ts fileName="intlayer.config.ts"
 import { Locales, type IntlayerConfig } from "intlayer";
@@ -45,7 +45,7 @@ const config: IntlayerConfig = {
     clientSecret: process.env.INTLAYER_CLIENT_SECRET,
   },
   ai: {
-    applicationContext: "This is a test application", // Ayuda a asegurar la generación consistente de traducciones
+    applicationContext: "Esta es una aplicación de prueba", // Ayuda a asegurar una generación consistente de traducciones
   },
 };
 
@@ -58,7 +58,7 @@ Para aprender más sobre el CMS, consulta la [documentación oficial](https://gi
 
 Puedes integrar la generación de traducciones en tu flujo de trabajo local de Git usando [Husky](https://typicode.github.io/husky/).
 
-### Configuración de ejemplo
+### Configuración de Ejemplo
 
 ```ts fileName="intlayer.config.ts"
 import { Locales, type IntlayerConfig } from "intlayer";
@@ -66,7 +66,7 @@ import { Locales, type IntlayerConfig } from "intlayer";
 const config: IntlayerConfig = {
   internationalization: {
     locales: [Locales.ENGLISH, Locales.SPANISH, Locales.FRENCH],
-    requiredLocales: [Locales.ENGLISH], // Los locales opcionales se gestionan de forma remota
+    requiredLocales: [Locales.ENGLISH], // Los locales opcionales se manejan de forma remota
     defaultLocale: Locales.ENGLISH,
   },
   editor: {
@@ -77,7 +77,7 @@ const config: IntlayerConfig = {
     provider: "openai",
     apiKey: process.env.OPENAI_API_KEY, // Usa tu propia clave API
 
-    applicationContext: "This is a test application", // Ayuda a asegurar la generación consistente de traducciones
+    applicationContext: "Esta es una aplicación de prueba", // Ayuda a asegurar una generación consistente de traducciones
   },
 };
 
@@ -91,7 +91,7 @@ npx intlayer fill --unpushed --mode fill    # Solo rellena el contenido faltante
 
 > Para más información sobre los comandos CLI de Intlayer y su uso, consulta la [documentación CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/intlayer_cli.md).
 
-> Si tienes múltiples aplicaciones en tu repositorio usando instancias separadas de Intlayer, puedes usar el argumento `--base-dir` así:
+> Si tienes múltiples aplicaciones en tu repositorio usando instancias separadas de Intlayer, puedes usar el argumento `--base-dir` de esta manera:
 
 ```bash fileName=".husky/pre-push"
 # App 1
@@ -105,68 +105,94 @@ npx intlayer fill --base-dir ./app2 --unpushed --mode fill
 
 ## Uso de GitHub Actions
 
-Intlayer proporciona un comando CLI para auto-rellenar y revisar el contenido del diccionario. Esto puede integrarse en tu flujo de trabajo CI/CD usando GitHub Actions.
+Intlayer proporciona un comando CLI para rellenar automáticamente y revisar el contenido del diccionario. Esto se puede integrar en tu flujo de trabajo CI/CD usando GitHub Actions.
 
 ```yaml fileName=".github/workflows/intlayer-translate.yml"
-name: Auto-Relleno Intlayer
+name: Relleno Automático de Intlayer
+# Condiciones para activar este flujo de trabajo
 on:
-  push:
-    branches: [ main ]
-    paths:
-      - 'src/**'
   pull_request:
-    branches: [ main ]
-    paths:
-      - 'src/**'
-  workflow_dispatch: {}
+    branches:
+      - "main"
+
+permissions:
+  contents: write
+  pull-requests: write
 
 concurrency:
-  group: 'autofill-${{ github.ref }}'
+  group: "autofill-${{ github.ref }}"
   cancel-in-progress: true
 
 jobs:
   autofill:
     runs-on: ubuntu-latest
     env:
-      INTLAYER_CLIENT_ID: ${{ secrets.INTLAYER_CLIENT_ID }}
-      INTLAYER_CLIENT_SECRET: ${{ secrets.INTLAYER_CLIENT_SECRET }}
-      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+      # OpenAI
+      AI_MODEL: openai
+      AI_PROVIDER: gpt-5-mini
+      AI_API_KEY: ${{ secrets.AI_API_KEY }}
 
     steps:
+      # Paso 1: Obtener el código más reciente del repositorio
       - name: ⬇️ Clonar repositorio
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
-          persist-credentials: true
+          persist-credentials: true # Mantener credenciales para crear PRs
+          fetch-depth: 0 # Obtener todo el historial git para análisis de diferencias
 
+      # Paso 2: Configurar el entorno de Node.js
       - name: 🟢 Configurar Node.js
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 20 # Usar Node.js 20 LTS para estabilidad
 
+      # Paso 3: Instalar dependencias del proyecto
       - name: 📦 Instalar dependencias
-        run: npm ci
+        run: npm install
+
+      # Paso 4: Instalar Intlayer CLI globalmente para gestión de traducciones
+      - name: 📦 Instalar Intlayer
+        run: npm install -g intlayer-cli
 
+      # Paso 5: Construir el proyecto Intlayer para generar archivos de traducción
       - name: ⚙️ Construir proyecto Intlayer
         run: npx intlayer build
 
-      - name: 🤖 Auto-rellenar traducciones faltantes
-        run: npx intlayer fill --git-diff --mode fill
-
-      - name: 📤 Crear o actualizar PR de traducción
-        uses: peter-evans/create-pull-request@v4
-        with:
-          commit-message: chore: auto-rellenar traducciones faltantes [skip ci]
-          branch: auto-translations
-          title: chore: actualizar traducciones faltantes
-          labels: translation, automated
+      # Paso 6: Usar IA para rellenar automáticamente las traducciones faltantes
+      - name: 🤖 Rellenar automáticamente las traducciones faltantes
+        run: npx intlayer fill --git-diff --mode fill --provider $AI_PROVIDER --model $AI_MODEL --api-key $AI_API_KEY
+
+      # Paso 7: Verificar si hay cambios y confirmarlos
+      - name: � Verificar cambios
+        id: check-changes
+        run: |
+          if [ -n "$(git status --porcelain)" ]; then
+            echo "has-changes=true" >> $GITHUB_OUTPUT
+          else
+            echo "has-changes=false" >> $GITHUB_OUTPUT
+          fi
+
+      # Paso 8: Confirmar y enviar cambios si existen
+      - name: 📤 Confirmar y enviar cambios
+        if: steps.check-changes.outputs.has-changes == 'true'
+        run: |
+          git config --local user.email "action@github.com"
+          git config --local user.name "GitHub Action"
+          git add .
+          git commit -m "chore: auto-fill missing translations [skip ci]"
+          git push origin HEAD:${{ github.head_ref }}
 ```
 
-> Igual que con Husky, en el caso de un monorepo, puedes usar el argumento `--base-dir` para tratar secuencialmente cada aplicación.
+Para configurar las variables de entorno, vaya a GitHub → Configuración → Secrets and variables → Actions y agregue el secreto .
+
+> Al igual que con Husky, en el caso de un monorepo, puede usar el argumento `--base-dir` para tratar secuencialmente cada aplicación.
 
 > Por defecto, el argumento `--git-diff` filtra los diccionarios que incluyen cambios desde la base (por defecto `origin/main`) hasta la rama actual (por defecto: `HEAD`).
 
-> Para más información sobre los comandos de la CLI de Intlayer y su uso, consulta la [documentación de la CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/intlayer_cli.md).
+> Para más información sobre los comandos de Intlayer CLI y su uso, consulte la [documentación del CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/intlayer_cli.md).
 
 ## Historial del documento
 
-- 5.5.10 - 2025-06-29: Historial inicial
+| Versión | Fecha      | Cambios           |
+| ------- | ---------- | ----------------- |
+| 5.5.10  | 2025-06-29 | Historial inicial |

package/docs/es/formatters.md

@@ -0,0 +1,239 @@
+---
+createdAt: 2024-08-13
+updatedAt: 2025-08-20
+title: Formateadores
+description: Utilidades de formato conscientes de la configuración regional basadas en Intl para números, porcentajes, moneda, fechas, tiempo relativo, unidades y notación compacta. Incluye un ayudante Intl con caché.
+keywords:
+  - Formateadores
+  - Intl
+  - Número
+  - Moneda
+  - Porcentaje
+  - Fecha
+  - Tiempo Relativo
+  - Unidades
+  - Compacto
+  - Internacionalización
+slugs:
+  - doc
+  - formatters
+---
+
+# Formateadores de Intlayer
+
+## Resumen
+
+Intlayer proporciona un conjunto de ayudantes ligeros construidos sobre las APIs nativas `Intl`, además de un envoltorio `Intl` con caché para evitar construir repetidamente formateadores pesados. Estas utilidades son totalmente conscientes de la configuración regional y pueden usarse desde el paquete principal `intlayer`.
+
+### Importar
+
+```ts
+import {
+  Intl,
+  number,
+  percentage,
+  currency,
+  date,
+  relativeTime,
+  units,
+  compact,
+} from "intlayer";
+```
+
+Si usas React, también hay disponibles hooks; consulta `react-intlayer/format`.
+
+## Intl con caché
+
+El `Intl` exportado es un envoltorio delgado con caché alrededor del `Intl` global. Memoiza instancias de `NumberFormat`, `DateTimeFormat`, `RelativeTimeFormat`, lo que evita reconstruir el mismo formateador repetidamente.
+
+Debido a que la construcción de formateadores es relativamente costosa, esta caché mejora el rendimiento sin cambiar el comportamiento. El envoltorio expone la misma API que el `Intl` nativo, por lo que el uso es idéntico.
+
+- La caché es por proceso y transparente para los llamadores.
+
+> Si `Intl.DisplayNames` no está disponible en el entorno, se imprime una única advertencia solo para desarrollo (considera un polyfill).
+
+Ejemplo:
+
+```ts
+import { Intl } from "intlayer";
+
+const numberFormat = new Intl.NumberFormat("en-GB", {
+  style: "currency",
+  currency: "GBP",
+});
+numberFormat.format(1234.5); // "£1,234.50"
+```
+
+## Formateadores
+
+Todos los ayudantes a continuación se exportan desde `intlayer`.
+
+### `number(value, options?)`
+
+Formatea un valor numérico usando agrupación y decimales sensibles a la configuración regional.
+
+- **value**: `number | string`
+- **options**: `Intl.NumberFormatOptions & { locale?: LocalesValues }`
+
+Ejemplos:
+
+```ts
+import { number } from "intlayer";
+
+number(123456.789); // "123,456.789" (en en-US)
+number("1000000", { locale: "fr" }); // "1 000 000"
+number(1234.5, { minimumFractionDigits: 2 }); // "1,234.50"
+```
+
+### `percentage(value, options?)`
+
+Formatea un número como una cadena de porcentaje.
+
+Comportamiento: los valores mayores que 1 se interpretan como porcentajes enteros y se normalizan (por ejemplo, `25` → `25%`, `0.25` → `25%`).
+
+- **value**: `number | string`
+- **options**: `Intl.NumberFormatOptions & { locale?: LocalesValues }`
+
+Ejemplos:
+
+```ts
+import { percentage } from "intlayer";
+
+percentage(0.25); // "25%"
+percentage(25); // "25%"
+percentage(0.237, { minimumFractionDigits: 1 }); // "23.7%"
+```
+
+### `currency(value, options?)`
+
+Formatea un valor como moneda localizada. Por defecto es `USD` con dos dígitos decimales.
+
+- **value**: `number | string`
+- **options**: `Intl.NumberFormatOptions & { locale?: LocalesValues }`
+  - Campos comunes: `currency` (por ejemplo, `"EUR"`), `currencyDisplay` (`"symbol" | "code" | "name"`)
+
+Ejemplos:
+
+```ts
+import { currency } from "intlayer";
+
+currency(1234.5, { currency: "EUR" }); // "€1,234.50"
+currency("5000", { locale: "fr", currency: "CAD", currencyDisplay: "code" }); // "5 000,00 CAD"
+```
+
+### `date(date, optionsOrPreset?)`
+
+Formatea un valor de fecha/hora con `Intl.DateTimeFormat`.
+
+- **date**: `Date | string | number`
+- **optionsOrPreset**: `Intl.DateTimeFormatOptions & { locale?: LocalesValues }` o uno de los preajustes:
+  - Preajustes: `"short" | "long" | "dateOnly" | "timeOnly" | "full"`
+
+Ejemplos:
+
+```ts
+import { date } from "intlayer";
+
+date(new Date(), "short"); // p. ej., "08/02/25, 14:30"
+date("2025-08-02T14:30:00Z", { locale: "fr", month: "long", day: "numeric" }); // "2 août"
+```
+
+### `relativeTime(from, to = new Date(), options?)`
+
+Formatea el tiempo relativo entre dos instantes con `Intl.RelativeTimeFormat`.
+
+- Pasa "now" como el primer argumento y el objetivo como el segundo para obtener una frase natural.
+- **from**: `Date | string | number`
+- **to**: `Date | string | number` (por defecto `new Date()`)
+- **options**: `{ locale?: LocalesValues; unit?: Intl.RelativeTimeFormatUnit; numeric?: Intl.RelativeTimeFormatNumeric; style?: Intl.RelativeTimeFormatStyle }`
+  - El valor predeterminado de `unit` es `"second"`.
+
+Ejemplos:
+
+```ts
+import { relativeTime } from "intlayer";
+
+const now = new Date();
+const in3Days = new Date(now.getTime() + 3 * 864e5);
+relativeTime(now, in3Days, { unit: "day" }); // "in 3 days"
+
+const twoHoursAgo = new Date(now.getTime() - 2 * 3600e3);
+relativeTime(now, twoHoursAgo, { unit: "hour", numeric: "auto" }); // "2 hours ago"
+```
+
+### `units(value, options?)`
+
+Formatea un valor numérico como una cadena de unidad localizada usando `Intl.NumberFormat` con `style: 'unit'`.
+
+- **value**: `number | string`
+- **options**: `Intl.NumberFormatOptions & { locale?: LocalesValues }`
+  - Campos comunes: `unit` (por ejemplo, `"kilometer"`, `"byte"`), `unitDisplay` (`"short" | "narrow" | "long"`)
+  - Valores predeterminados: `unit: 'day'`, `unitDisplay: 'short'`, `useGrouping: false`
+
+Ejemplos:
+
+```ts
+import { units } from "intlayer";
+
+units(5, { unit: "kilometer", unitDisplay: "long", locale: "en-GB" }); // "5 kilometers"
+units(1024, { unit: "byte", unitDisplay: "narrow" }); // "1,024B" (dependiente del locale)
+```
+
+### `compact(value, options?)`
+
+Formatea un número usando notación compacta (por ejemplo, `1.2K`, `1M`).
+
+- **value**: `number | string`
+- **options**: `Intl.NumberFormatOptions & { locale?: LocalesValues }` (utiliza `notation: 'compact'` internamente)
+
+Ejemplos:
+
+```ts
+import { compact } from "intlayer";
+
+compact(1200); // "1.2K"
+compact("1000000", { locale: "fr", compactDisplay: "long" }); // "1 millón"
+```
+
+## Notas
+
+- Todos los helpers aceptan entradas de tipo `string`; internamente se convierten a números o fechas.
+- El locale por defecto es el configurado en `internationalization.defaultLocale` si no se proporciona.
+- Estas utilidades son envoltorios ligeros; para formateos avanzados, pase las opciones estándar de `Intl`.
+
+## Puntos de entrada y re-exportaciones (`@index.ts`)
+
+Los formateadores residen en el paquete core y se re-exportan desde paquetes de nivel superior para mantener las importaciones ergonómicas en diferentes entornos:
+
+Ejemplos:
+
+```ts
+// Código de la aplicación (recomendado)
+import { number, currency, date, Intl } from "intlayer";
+```
+
+### React
+
+Componentes cliente:
+
+```ts
+import { useNumber, useCurrency, useDate } from "react-intlayer/format";
+// o en aplicaciones Next.js
+import { useNumber, useCurrency, useDate } from "next-intlayer/client/format";
+```
+
+Componentes servidor (o runtime React Server):
+
+```ts
+import { useNumber, useCurrency, useDate } from "intlayer/server/format";
+// o en aplicaciones Next.js
+import { useNumber, useCurrency, useDate } from "next-intlayer/server/format";
+```
+
+> Esos hooks considerarán el locale desde el `IntlayerProvider` o `IntlayerServerProvider`
+
+## Historial de la documentación
+
+| Versión | Fecha      | Cambios                                |
+| ------- | ---------- | -------------------------------------- |
+| 5.8.0   | 2025-08-18 | Añadida documentación de formateadores |