@intlayer/docs 9.4.2 → 9.4.4

package/blog/es/date_time_number_formatting_locales.md

@@ -0,0 +1,216 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: "Formatear fechas y números por idioma con Intl"
+description: Probablemente no necesitas una librería de formateo. Cómo maneja Intl fechas, números, monedas y listas por idioma, el costo de caché y el bug de zona horaria en producción.
+keywords:
+  - formatear fecha por idioma
+  - Intl.DateTimeFormat
+  - Intl.NumberFormat
+  - toLocaleDateString
+  - formato moneda locale
+  - formato tiempo relativo
+slugs:
+  - blog
+  - date-time-number-formatting-locales
+author: aymericzip
+---
+
+# Formatear fechas y números por idioma con Intl
+
+Traducir cadenas de texto es la mitad visible de la internacionalización. La otra mitad, la que suele saturar los reportes de errores, es el formateo: un usuario en Alemania que ve `1,234.56` en vez de `1.234,56`, un usuario en Japón que ve `08/02/2026` y asume que es agosto, o una fecha que se renderiza distinto en el servidor y en el navegador, rompiendo la hidratación en React.
+
+Nada de eso requiere dependencias externas. `Intl` ya está presente de forma nativa en cualquier entorno moderno.
+
+## Tabla de contenidos
+
+<TOC/>
+
+## Comienza eliminando tu helper de fechas
+
+Casi cualquier repositorio conserva una función `formatDate` escrita antes de contemplar la internacionalización. Suele forzar un orden rígido, un separador y, por lo general, nombres de meses en inglés.
+
+```ts
+// Lo que deberías borrar.
+const formatDate = (d: Date) =>
+  `${d.getMonth() + 1}/${d.getDate()}/${d.getFullYear()}`;
+```
+
+`Intl.DateTimeFormat` la reemplaza y resuelve el formato de manera adecuada en cada idioma:
+
+```ts
+new Intl.DateTimeFormat("de-DE", { dateStyle: "long" }).format(date);
+// "2. August 2026"
+new Intl.DateTimeFormat("ja-JP", { dateStyle: "long" }).format(date);
+// "2026年8月2日"
+```
+
+Lo mismo ocurre con los valores numéricos. `toFixed(2)` produce `1234.56` en todas partes, lo cual es incorrecto en casi toda Europa.
+
+## Qué cubre `Intl`
+
+| API                       | Caso de uso                                                        |
+| :------------------------ | :----------------------------------------------------------------- |
+| `Intl.DateTimeFormat`     | Fechas y horas, con ajustes predefinidos `dateStyle` / `timeStyle` |
+| `Intl.NumberFormat`       | Decimales, divisas, porcentajes, unidades, notación compacta       |
+| `Intl.RelativeTimeFormat` | "hace 3 días", "en 2 horas"                                        |
+| `Intl.ListFormat`         | "a, b y c" frente a "a, b, and c"                                  |
+| `Intl.PluralRules`        | Categoría de plural a la que pertenece un valor numérico           |
+| `Intl.Collator`           | Ordenación alfabética correcta según cada lengua                   |
+
+`Intl.Collator` es el gran olvidado. Ejecutar `array.sort()` sobre cadenas utiliza el orden de los puntos de código Unicode, de modo que los caracteres con tilde terminan ordenados tras la `z` y la `ö` sueca se sitúa en un lugar erróneo. Si ordenas listas que los usuarios van a leer, utiliza siempre un collator.
+
+```ts
+["zebra", "édouard", "apple"].sort(new Intl.Collator("es").compare);
+// ["apple", "édouard", "zebra"]
+```
+
+## Prefiere preajustes antes que opciones construidas a mano
+
+`dateStyle` y `timeStyle` dejan que el locale determine el orden lógico y los separadores pertinentes. Especificar `year`, `month` y `day` por separado otorga un control que rara vez conviene tener, ya que el orden correcto cambia por región y terminas sobreescribiendo los datos de CLDR con tus propias suposiciones.
+
+```ts
+// El idioma determina la estructura.
+new Intl.DateTimeFormat(locale, { dateStyle: "medium" }).format(d);
+
+// Forzaste la estructura, y te equivocarás en otra región.
+new Intl.DateTimeFormat(locale, {
+  year: "numeric",
+  month: "2-digit",
+  day: "2-digit",
+}).format(d);
+```
+
+Usa componentes explícitos únicamente cuando el diseño visual exija con exactitud un ancho fijo, como en una columna de tabla estrecha.
+
+## Crear formateadores es costoso
+
+Este es un detalle de rendimiento clave. Construir un `Intl.NumberFormat` implica cargar datos de locale en memoria, y es una operación mucho más pesada que la subsiguiente llamada a `.format()`. Hacerlo dentro de un bucle de renderizado sobre mil filas genera un impacto medible.
+
+```ts
+// Reconstruye el formateador en cada iteración.
+rows.map((r) => new Intl.NumberFormat(locale).format(r.total));
+
+// Construye una vez y reutiliza.
+const nf = new Intl.NumberFormat(locale);
+rows.map((r) => nf.format(r.total));
+```
+
+`toLocaleDateString()` y `toLocaleString()` esconden exactamente el mismo problema: cada invocación genera un nuevo formateador. Son tolerables para un dato aislado, pero pésimos para una lista.
+
+Guárdalos en caché mediante la combinación de idioma y opciones:
+
+```ts
+const cache = new Map<string, Intl.NumberFormat>();
+
+const getNumberFormat = (
+  locale: string,
+  options: Intl.NumberFormatOptions = {}
+) => {
+  const key = `${locale}:${JSON.stringify(options)}`;
+  let formatter = cache.get(key);
+  if (!formatter) {
+    formatter = new Intl.NumberFormat(locale, options);
+    cache.set(key, formatter);
+  }
+  return formatter;
+};
+```
+
+## El bug de zona horaria que solo salta en producción
+
+Este problema ha costado tardes enteras. El servidor genera una fecha durante el SSR, el navegador la hidrata en el cliente, y React lanza un error de hydration mismatch porque ambas partes generaron un texto diferente.
+
+La raíz del problema radica en que `Intl.DateTimeFormat` recurre a la zona horaria del sistema operativo cuando no se especifica ninguna. Tu servidor en producción corre bajo UTC, mientras que tu ordenador local está en otra zona horaria. Como resultado, el fallo es invisible en local y solo estalla en producción.
+
+```ts
+// Un servidor en UTC y un navegador en UTC+9 difieren. Error de hidratación.
+new Intl.DateTimeFormat(locale, { dateStyle: "short" }).format(d);
+
+// Ambos coinciden sin ambigüedades.
+new Intl.DateTimeFormat(locale, { dateStyle: "short", timeZone: "UTC" }).format(
+  d
+);
+```
+
+Tres soluciones prácticas:
+
+- **Fijar la zona horaria** en el servidor y pasarla explícitamente. Determinista, pero todo el mundo ve la hora en UTC.
+- **Renderizar solo en el cliente**, manteniendo un placeholder estable durante el SSR. Preciso para el usuario, aunque añade un pequeño parpadeo.
+- **Guardar la zona horaria del usuario** y pasarla en ambos entornos. La mejor experiencia, con algo más de trabajo de sincronización.
+
+Elijas la que elijas, define siempre `timeZone` de forma explícita en cualquier fecha que se renderice tanto en el servidor como en el cliente. Una fecha sin zona horaria asignada es una fecha con dos valores contradictorios.
+
+## Una divisa necesita una divisa, no un idioma
+
+El idioma y la divisa son independientes. `fr-FR` no implica euros de forma estricta: un usuario francés puede estar revisando una factura en dólares estadounidenses.
+
+```ts
+new Intl.NumberFormat("fr-FR", { style: "currency", currency: "USD" }).format(
+  1234.5
+);
+// "1 234,50 $US"
+```
+
+El locale define los separadores, los grupos de dígitos y la posición del símbolo. La moneda proviene de tus datos de negocio. Deducir una a partir de la otra genera incidencias en facturación.
+
+Considera también la opción `currencyDisplay`. En interfaces donde conviven varias monedas que usan el signo de dólar, `"code"` despeja la ambigüedad entre dólares estadounidenses, canadienses y australianos.
+
+## El tiempo relativo es más legible que una marca temporal absoluta
+
+Para sucesos recientes, "hace 2 horas" supera a cualquier fecha estática, e `Intl.RelativeTimeFormat` se encarga de localizarlo adecuadamente.
+
+```ts
+new Intl.RelativeTimeFormat("es", { numeric: "auto" }).format(-1, "day");
+// "ayer"
+```
+
+`numeric: "auto"` es la clave para obtener "ayer" en lugar de "hace 1 día". Sin esta opción obtendrás la forma numérica estricta en cada idioma, lo que resulta artificial.
+
+## Qué aporta Intlayer
+
+Intlayer envuelve estas APIs en utilidades con caché integrada para que no tengas que mantener un mapa manual, aplicando el idioma activo de forma predeterminada sin requerir pasarlo en cada invocación.
+
+```ts
+import {
+  number,
+  currency,
+  date,
+  relativeTime,
+  units,
+  compact,
+  list,
+} from "intlayer";
+
+number(1234.5); // "1.234,5"
+currency(1234.5, { currency: "EUR" }); // "1.234,50 €"
+date(new Date(), "short");
+relativeTime(now, twoHoursAgo, { unit: "hour", numeric: "auto" }); // "hace 2 horas"
+units(5, { unit: "kilometer", unitDisplay: "long" }); // "5 kilómetros"
+compact(1200); // "1,2 K"
+list(["manzana", "plátano", "naranja"]); // "manzana, plátano y naranja"
+```
+
+La función `date()` admite preajustes (`"short"`, `"long"`, `"dateOnly"`, `"timeOnly"`, `"full"`), de manera que los casos habituales no precisen de un objeto de opciones extenso. Existen equivalentes para React y Vue como hooks y composables que resuelven el idioma activo directamente desde el contexto de la aplicación.
+
+Esto representa una capa de caché y resolución de locale por defecto construida sobre las APIs estándar de la plataforma. La lógica de formateo sigue siendo la de `Intl`. Puedes consultar las firmas completas en la [documentación de formateadores](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/formatters.md).
+
+## Errores habituales
+
+- **`toLocaleDateString()` sin indicar locale.** Toma la configuración regional del host, que en un servidor depende de cómo se construyó el contenedor.
+- **Formatear dentro de un bucle.** La instanciación del formateador concentra casi todo el costo. Construye una sola vez.
+- **Omitir `timeZone` en fechas isomórficas.** Desencadena errores de hidratación imposibles de reproducir en tu máquina local.
+- **Inferir la moneda a partir del idioma.** `fr-FR` no implica automáticamente euros.
+- **Usar `sort()` directo sobre texto visible.** Emplea siempre `Intl.Collator`.
+- **Escribir meses o días fijos en el código.** Ya están disponibles en CLDR para cada idioma.
+- **Mantener `numeric: "always"` en tiempo relativo.** Provoca "hace 1 día" en lenguas que cuentan con una palabra específica como ayer.
+
+## Para profundizar
+
+- [Formateadores y utilidades de idioma: `number`, `currency`, `date`, `relativeTime`, `list`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/formatters.md)
+- [Referencia de configuración](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/configuration.md)
+- [Informes de benchmark entre frameworks](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/benchmark/index.md)
+- [Adaptador de compatibilidad react-intl](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/compat/react-intl.md)
+- [Formato de mensajes ICU: plurales, selección y esqueletos numéricos](https://github.com/aymericzip/intlayer/blob/main/docs/blog/es/icu_message_format.md)
+- [Cómo probar traducciones, incluyendo formateadores y plurales](https://github.com/aymericzip/intlayer/blob/main/docs/blog/es/i18n_testing_strategies.md)
+- [Qué abarca realmente la internacionalización](https://github.com/aymericzip/intlayer/blob/main/docs/blog/es/what_is_internationalization.md)

package/blog/es/detecting_missing_translations.md

@@ -0,0 +1,202 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: "Cómo detectar traducciones faltantes antes de que lo hagan tus usuarios"
+description: Las traducciones faltantes fallan en silencio. Por qué el fallback las oculta, las cuatro capas de detección efectivas y cómo bloquear una compilación por una clave no traducida.
+keywords:
+  - encontrar traducciones faltantes
+  - claves de traducción faltantes
+  - auditoría i18n
+  - cadenas no traducidas
+  - cobertura de traducción
+  - lint i18n
+slugs:
+  - blog
+  - detecting-missing-translations
+author: aymericzip
+---
+
+# Cómo detectar traducciones faltantes antes de que lo hagan tus usuarios
+
+Una traducción faltante casi nunca genera una excepción explícita. Según tu configuración, le muestra el texto en inglés a un usuario en Japón, o imprime `checkout.summary.total` en plena pantalla en producción. Ambos problemas se despliegan, ambos pasan la revisión de código sin alertas, y ambos terminan siendo descubiertos por un cliente antes que por ti.
+
+## Tabla de contenidos
+
+<TOC/>
+
+## Esto aplica sin importar la biblioteca que utilices
+
+Nada de lo expuesto aquí depende de una tecnología en particular. Las capas de detección funcionan igual en i18next, react-i18next, next-intl, react-intl, vue-i18n, next-translate o Lingui, porque todas resuelven las claves y fallan bajo la misma lógica.
+
+Las herramientas también son portables. Si tus mensajes están hoy en catálogos JSON, el [plugin Sync JSON](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/plugins/sync-json.md) conecta Intlayer a esos archivos para que obtengas los comandos de auditoría, autocompletado y pruebas sin mover tu contenido ni alterar un solo import:
+
+```ts fileName="intlayer.config.ts"
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+const config = {
+  plugins: [
+    syncJSON({
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      format: "i18next", // o "icu" para next-intl / react-intl
+    }),
+  ],
+};
+
+export default config;
+```
+
+Si prefieres mantener idéntica la API en tiempo de ejecución, los [adaptadores de compatibilidad](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/compat/index.md) crean alias para `useTranslation`, `$t` y similares en el empaquetador. En cualquier caso, toma los comandos siguientes como una implementación concreta de la idea, no como una imposición.
+
+## Por qué son invisibles
+
+Cada biblioteca de i18n resuelve una clave mediante la misma cadena: buscar en el locale activo, recurrir a un valor predeterminado por fallback y, si eso falla, devolver la clave literal. Este último paso es el verdadero problema. No hay error, no hay advertencia en producción y ningún test falla, porque nada en la canalización considera anormal una clave no traducida.
+
+El fallback empeora las cosas en lugar de solucionarlas. Una página que se muestra silenciosamente en inglés luce impecable para un desarrollador que habla inglés y para cada verificación automatizada de tu CI. El error solo es perceptible para la persona que no comprende el resultado.
+
+Así que la pregunta no es "cómo manejo las traducciones faltantes en tiempo de ejecución". Es "cómo hago que sea imposible hacer merge de una traducción faltante".
+
+## Los cuatro lugares donde puedes detectarlas
+
+Cada capa detecta situaciones que las otras ignoran. Necesitas más de una.
+
+| Capa            | Detecta                                      | Pasa por alto                                  |
+| :-------------- | :------------------------------------------- | :--------------------------------------------- |
+| Tipos           | Claves que no existen en absoluto            | Clave existente pero sin traducir en `ja`      |
+| Linter          | Cadenas fijas nunca enviadas a traducir      | Claves omitidas de un catálogo                 |
+| Auditoría       | Cobertura de locales en cada clave declarada | Textos que nunca se prepararon para traducir   |
+| Tests de render | Claves que se resuelven pero se muestran mal | Todo lo no cubierto explícitamente por un test |
+
+La brecha habitual en la mayoría de los equipos está en la tercera fila: saben que sus claves son válidas, pero nada comprueba que los dieciocho idiomas cuenten efectivamente con un valor.
+
+## Capa 1: haz que la clave sea un tipo, no un string
+
+`t("checkout.summry.total")` es un simple error tipográfico que compila sin problemas. Si tus claves son cadenas planas, cada cambio de nombre es un riesgo en producción y cada eliminación deja una clave huérfana.
+
+Las claves tipadas convierten ese error en un fallo de compilación. `react-i18next` lo soporta mediante declaration merging, `next-intl` lo infiere de la estructura de mensajes, Lingui deriva identificadores del texto de origen e Intlayer genera tipos a partir de los archivos de declaración. Todos cumplen su propósito; lo que cambia es la cantidad de código de configuración que debes escribir.
+
+Esta capa es necesaria pero no suficiente. Los tipos describen la estructura del catálogo por defecto. No dicen nada sobre si el coreano tiene un valor asignado para esa clave.
+
+## Capa 2: inspecciona con linter las cadenas que nunca llegaron a ser claves
+
+La traducción que no encuentras suele ser la que nunca se externalizó. Un texto hardcodeado dentro de un componente es invisible para cualquier auditoría de catálogo, porque para las herramientas simplemente no existe.
+
+El plugin de ESLint de Intlayer cubre esto con `no-raw-text`, sumado a `no-unused-content` para el caso inverso: contenido declarado que ya no se utiliza en ninguna parte.
+
+```js fileName="eslint.config.mjs"
+import intlayer from "@intlayer/eslint-plugin";
+
+export default [
+  intlayer.configs.recommended,
+  {
+    rules: {
+      "@intlayer/no-raw-text": "error",
+      "@intlayer/no-unused-content": "warn",
+    },
+  },
+];
+```
+
+`no-unused-content` evita que los catálogos crezcan descontroladamente. Las claves muertas no rompen la aplicación, pero engrosan innecesariamente las facturas de traducción. Revisa la lista de reglas en la [documentación del plugin ESLint](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/eslint.md).
+
+## Capa 3: audita la cobertura de locales
+
+Esta capa responde directamente a la pregunta principal. Intlayer la incluye como comando de CLI:
+
+```bash packageManager="npm"
+npx intlayer content test
+```
+
+Lee los idiomas configurados y los diccionarios declarados, e informa con precisión qué claves faltan en qué idiomas y en qué archivo.
+
+Un detalle crucial antes de incorporarlo en tus pipelines: **el CLI imprime un reporte pero devuelve código de salida cero.** Si lo agregas esperando que bloquee un build defectuoso, obtendrás una ejecución verde con un informe que nadie leerá. Para bloquear builds, utiliza la API programática que se detalla a continuación.
+
+## Capa 4: compruébalo mediante aserciones en la suite de pruebas
+
+`listMissingTranslations()` te devuelve la misma auditoría estructurada como datos, ideal para crear una barrera de compilación.
+
+```ts fileName="i18n.test.ts"
+/* @vitest-environment node */
+import { listMissingTranslations } from "intlayer/cli";
+import { describe, expect, it } from "vitest";
+
+describe("translations", () => {
+  it("no tiene locales requeridos faltantes", async () => {
+    const result = await listMissingTranslations();
+
+    if (result.missingRequiredLocales.length > 0) {
+      console.log(result.missingTranslations);
+    }
+
+    expect(result.missingRequiredLocales).toHaveLength(0);
+  });
+});
+```
+
+Se devuelven tres campos y la distinción es importante:
+
+- `missingTranslations`: por cada clave, qué idiomas faltan y en qué archivo se encuentran. Esto es lo que imprimes si la prueba falla.
+- `missingLocales`: la unión de idiomas faltantes en todas las claves.
+- `missingRequiredLocales`: limitado a los `requiredLocales` de tu configuración, o todos si no definiste la propiedad.
+
+## `requiredLocales` es el parámetro que hace viable el control
+
+Soportar dieciocho idiomas no significa que todos deban estar completos al 100% para poder desplegar. Casi todos los equipos tienen un nivel crítico que bloquea el lanzamiento y otro nivel que se completa progresivamente.
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.JAPANESE,
+      Locales.POLISH,
+    ],
+    requiredLocales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+Sin `requiredLocales`, cada idioma configurado se vuelve obligatorio y tu build permanecerá roto hasta que llegue la última traducción. Esa es la razón por la que los equipos terminan desactivando el chequeo por completo, lo cual es peor que no tenerlo.
+
+## Encontrar las omisiones que ya están en producción
+
+Las capas anteriores evitan nuevas omisiones. Para una aplicación que ya está en vivo, dos estrategias resultan muy útiles.
+
+**Pseudolocalización.** Ejecuta un idioma ficticio donde cada cadena se modifique, por ejemplo `[!!! Ĉĥéçķöũţ !!!]`. Cualquier texto que permanezca en inglés normal está hardcodeado. Descubre en diez minutos lo que una auditoría de catálogo no puede ver por diseño, ya que analiza la página renderizada y no los archivos de datos.
+
+**Rastrea tu propio sitio.** Si manejas URLs localizadas, haz peticiones a páginas de muestra por cada idioma y busca en el HTML las cadenas de tu idioma base. Una página en `/ja/` que contiene "Add to cart" es una traducción faltante o un fallback no planificado.
+
+```bash
+curl -s https://example.com/ja/checkout | grep -c "Add to cart"
+```
+
+## Llenar los vacíos
+
+Cuando sabes qué falta, `intlayer fill` autocompleta las entradas vacías, y la opción `autoFill` genera archivos por idioma al declarar contenido. Consulta [autoFill](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/autoFill.md).
+
+Conviene ser realistas: las traducciones generadas automáticamente convierten una falta _visible_ en una falta _invisible_. La clave ahora tiene contenido, la auditoría se pone en verde y nadie ha revisado el texto. Úsalo para desbloquear entregas y luego envía las salidas a revisión humana en todo texto crítico para la toma de decisiones. Es una ayuda inicial, no un reemplazo.
+
+## Errores comunes
+
+- **Tratar el fallback como una funcionalidad de protección.** Es solo una estrategia de renderizado de emergencia, no una red de seguridad. Una página que calladamente sale en inglés es un bug que nadie reporta.
+- **Confiar en el reporte de CLI para bloquear CI.** `intlayer content test` sale con código cero. Usa una aserción en tests.
+- **Exigir todos los idiomas.** La comprobación se desactiva en cuanto frena una entrega por una traducción parcial.
+- **Auditar catálogos pero nunca la pantalla renderizada.** Las cadenas hardcodeadas son invisibles en los catálogos por definición.
+- **Comprobar únicamente el idioma por defecto.** Es el único que nunca va a faltar.
+- **Dar por cerrado el ciclo solo con autocompletado de IA.** Auditoría en verde con textos jamás revisados.
+
+## Para profundizar
+
+- [Probar el contenido: auditoría CLI, API programática y aserciones UI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/testing.md)
+- [Reglas del plugin ESLint, incluyendo `no-raw-text` y `no-unused-content`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/eslint.md)
+- [autoFill: generación de archivos de declaración por locale](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/autoFill.md)
+- [Referencia de configuración: `locales`, `requiredLocales`, `defaultLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/configuration.md)
+- [Informes de benchmark entre frameworks](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/benchmark/index.md)
+- [Adaptador de compatibilidad i18next](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/compat/i18next.md)
+- [Qué abarca realmente la internacionalización](https://github.com/aymericzip/intlayer/blob/main/docs/blog/es/what_is_internationalization.md)
+- [i18n por componente vs centralizada](https://github.com/aymericzip/intlayer/blob/main/docs/blog/es/per-component_vs_centralized_i18n.md)

package/blog/es/i18n_in_ci_cd_pipelines.md

@@ -0,0 +1,247 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: "Automatizar traducciones en CI/CD sin enviar textos defectuosos"
+description: Tres puntos clave para automatizar i18n, pre-push, pull request y runtime. Cómo bloquear una compilación por cobertura, autocompletar de forma segura y evitar el bucle infinito de commits.
+keywords:
+  - automatizar traducciones ci
+  - i18n ci cd
+  - github actions traducciones
+  - husky pre-push
+  - localización continua
+  - pipeline de traducción
+slugs:
+  - blog
+  - i18n-in-ci-cd-pipelines
+author: aymericzip
+---
+
+# Automatizar traducciones en CI/CD sin enviar textos defectuosos
+
+La traducción manual no sobrevive al ritmo ágil de despliegues. Alguien añade una cadena el viernes, la exportación se retrasa al siguiente sprint, y para entonces tres idiomas más están desactualizados. Automatizarlo es sencillo. Automatizarlo sin publicar silenciosamente contenido generado por máquinas a los usuarios es la parte que requiere verdadera atención.
+
+## Tabla de contenidos
+
+<TOC/>
+
+## No necesitas migrar para automatizar
+
+Los esquemas de pipeline descritos a continuación son independientes de la biblioteca utilizada, al igual que las herramientas. Si tus textos son catálogos JSON para i18next, next-intl, react-intl, vue-i18n o next-translate, el [plugin Sync JSON](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/plugins/sync-json.md) lee y escribe esos archivos directamente en su lugar:
+
+```ts fileName="intlayer.config.ts"
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+const config = {
+  plugins: [
+    syncJSON({
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      format: "i18next", // o "icu" para next-intl / react-intl
+    }),
+  ],
+};
+
+export default config;
+```
+
+Tu aplicación sigue importando lo mismo de siempre. Los procesos de CI completan y protegen tus catálogos existentes, y el diff que el revisor ve es una simple actualización en `locales/fr/checkout.json`, no una migración de arquitectura. Existe un [plugin Sync PO](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/plugins/sync-po.md) para flujos gettext, y [adaptadores de compatibilidad](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/compat/index.md) para mantener la API en tiempo de ejecución sin cambios.
+
+## Separa el control de bloqueo (gate) del llenado (fill)
+
+Dos tareas distintas se confunden continuamente.
+
+Un **gate** es una verificación que falla. Establece que esta compilación no debe desplegarse porque faltan idiomas requeridos. No escribe ningún archivo.
+
+Un **fill** es una mutación. Genera las traducciones faltantes y realiza un commit con ellas. Nunca hace fallar una compilación.
+
+Ejecutar únicamente un fill implica que nada se bloquea jamás y las traducciones generadas por máquina llegan a producción sin revisión. Ejecutar únicamente un gate hace que el build se ponga rojo y un humano tenga que intervenir cada vez. La mayoría de los equipos necesitan ambos vinculados a disparadores diferentes: fill en un pull request, gate al fusionar en la rama de lanzamiento.
+
+## Dónde ubicar la automatización
+
+| Etapa         | Disparador | Ideal para                                | Costo                                        |
+| :------------ | :--------- | :---------------------------------------- | :------------------------------------------- |
+| Hook pre-push | Git local  | Feedback rápido, cero minutos de CI       | Se ejecuta en la máquina y clave API del dev |
+| Pull request  | Job de CI  | Revisión previa al merge, un lugar seguro | Minutos de CI más llamadas al modelo por PR  |
+| Rama release  | Job de CI  | Bloqueo estricto por cobertura            | Económico, sin llamadas a modelos            |
+| Runtime       | CMS        | Cambios de contenido sin recompilar       | Dependencia de servicio alojado              |
+
+## Pre-push: el ciclo más rápido
+
+Husky ejecuta el llenado antes de que el código salga de la máquina, permitiendo que las traducciones lleguen en el mismo push que introdujo las nuevas cadenas.
+
+```bash fileName=".husky/pre-push"
+npx intlayer build
+npx intlayer fill --unpushed --mode complete
+```
+
+`--unpushed` limita el trabajo al contenido que aún no ha sido enviado, evitando esperas innecesarias en cada push. `--mode complete` rellena únicamente lo que falta sin reescribir entradas que ya tienen valor, garantizando que una traducción revisada nunca sea reemplazada en silencio.
+
+En un monorepo, delimita cada aplicación:
+
+```bash fileName=".husky/pre-push"
+npx intlayer build --base-dir ./app1
+npx intlayer fill --base-dir ./app1 --unpushed --mode complete
+npx intlayer build --base-dir ./app2
+npx intlayer fill --base-dir ./app2 --unpushed --mode complete
+```
+
+La desventaja es real: cada desarrollador requiere una clave de API, y el costo recae sobre quien envía el push. Por eso la mayoría de los equipos trasladan esto a la CI cuando crecen.
+
+## Pull request: generar donde se realiza la revisión
+
+El mismo trabajo en GitHub Actions, enfocado en el diff:
+
+```yaml fileName=".github/workflows/intlayer-translate.yml"
+name: Intlayer Auto-Fill
+on:
+  pull_request:
+    branches: ["main"]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: "autofill-${{ github.ref }}"
+  cancel-in-progress: true
+
+jobs:
+  autofill:
+    runs-on: ubuntu-latest
+    env:
+      AI_PROVIDER: openai
+      AI_MODEL: gpt-5-mini
+      AI_API_KEY: ${{ secrets.AI_API_KEY }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: true
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm install
+      - run: npx intlayer build
+      - run: npx intlayer fill --git-diff --mode complete --provider $AI_PROVIDER --model $AI_MODEL --api-key $AI_API_KEY
+      - name: Commit
+        run: |
+          if [ -n "$(git status --porcelain)" ]; then
+            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 }}
+          fi
+```
+
+Cuatro detalles son fundamentales aquí:
+
+- **`fetch-depth: 0`** es obligatorio para que funcione `--git-diff`. Un clon superficial no tiene una base contra la cual calcular el diff, por lo que el proceso no genera nada silenciosamente.
+- **`[skip ci]` en el mensaje de commit** evita que el flujo de trabajo se reactive a sí mismo en bucle infinito. Sin él, el commit inicia una ejecución que vuelve a hacer commit, agotando el presupuesto de CI en una noche.
+- **`concurrency` con `cancel-in-progress`** impide que dos pushes concurrentes compitan intentando escribir los mismos archivos a la vez.
+- **`--git-diff`** limita el autocompletado a lo modificado en el PR. Si lo omites, retraduces todo el catálogo en cada ejecución.
+
+Las traducciones se incorporan como un commit en la rama del PR, lo que significa que el revisor las ve en el diff. Ese es el beneficio principal de hacerlo aquí en lugar de después del merge.
+
+## Rama de release: el control de bloqueo (gate)
+
+El gate no requiere acceso a modelos y debe ser sumamente rápido.
+
+```yaml fileName=".github/workflows/ci.yml"
+- run: npm run test:i18n
+```
+
+Respaldado por una prueba que realiza aserciones sobre la cobertura en lugar del simple reporte de la terminal:
+
+```ts fileName="i18n.test.ts"
+import { listMissingTranslations } from "intlayer/cli";
+
+test("no tiene locales requeridos faltantes", async () => {
+  const result = await listMissingTranslations();
+  if (result.missingRequiredLocales.length > 0) {
+    console.log(result.missingTranslations);
+  }
+  expect(result.missingRequiredLocales).toHaveLength(0);
+});
+```
+
+`npx intlayer content test` imprime un informe pero devuelve código de salida cero, por lo que solo informa sin bloquear. Úsalo en local; usa la aserción en CI. Más detalles en [detectar traducciones faltantes](https://github.com/aymericzip/intlayer/blob/main/docs/blog/es/detecting_missing_translations.md).
+
+## `requiredLocales` hace viable el gate
+
+Un gate que exija dieciocho idiomas completos bloquea cada despliegue hasta que el idioma más rezagado esté listo, terminando por ser desactivado en menos de un mes.
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    requiredLocales: [Locales.ENGLISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+Declara los locales que soportas y exige como obligatorios solo aquellos que deben bloquear un lanzamiento. El resto se completa de forma asíncrona sin frenar tus entregas.
+
+## Desacoplar las traducciones del repositorio
+
+El otro enfoque consiste en declarar un idioma base en código y gestionar el resto de forma remota a través del CMS con Live Sync. Las modificaciones de contenido ya no requieren recompilación, separando el ritmo editorial del ciclo de despliegue técnico.
+
+```ts fileName="intlayer.config.ts"
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.SPANISH, Locales.FRENCH],
+    requiredLocales: [Locales.ENGLISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  editor: {
+    clientId: process.env.INTLAYER_CLIENT_ID,
+    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+    liveSync: true,
+  },
+};
+
+export default config;
+```
+
+Esto se adapta a equipos donde personas no técnicas gestionan los textos. Es un intercambio: ganas autonomía editorial y pierdes la propiedad de que un checkout de git describa con exactitud todo lo que la app renderiza. Detalles en la [documentación del CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/intlayer_CMS.md).
+
+Ten en cuenta que `clientSecret` es una credencial sensible de servidor. Pertenece a los secretos de CI y al entorno de tu servidor, nunca a nada que llegue al cliente.
+
+## La limitación honesta
+
+Todo lo anterior automatiza la _cobertura_, no la _calidad_. Un autocompletado por máquina convierte una ausencia visible en una invisible: la auditoría se vuelve verde porque la clave ya tiene un valor, pero nadie la ha leído.
+
+Esto es aceptable para herramientas internas, notas de versiones o locales en fase beta. No es aceptable para páginas de precios, avisos legales, mensajes de error de pago o cualquier texto que el usuario lea antes de tomar una decisión. En esos casos, canaliza el contenido mediante revisión humana y usa `--mode complete` para no sobrescribir cadenas ya revisadas.
+
+Proporciona contexto al modelo para que la salida sea consistente:
+
+```ts
+ai: {
+  applicationContext: "Aplicación de facturación B2B. Tono formal. Nunca traducir el nombre del producto.",
+}
+```
+
+## Errores comunes
+
+- **Omitir `[skip ci]` en el auto-commit.** El flujo se reactiva en un bucle sin fin.
+- **Clonado superficial con `--git-diff`.** No hay base para calcular diferencias, no se llena nada y no se genera aviso.
+- **Llenar todo el catálogo en cada ejecución.** Limita el alcance con `--git-diff` o `--unpushed` para controlar costos.
+- **Usar el reporte de CLI como gate.** Devuelve código de salida 0.
+- **Exigir todos los locales como requeridos.** El control se desactiva en el primer lanzamiento bloqueado.
+- **Un job de fill sin ningún gate.** Nada falla nunca, y textos no revisados van a producción.
+- **Claves de API de modelos en el repositorio.** Deben estar en secretos de CI, al igual que `clientSecret`.
+
+## Para profundizar
+
+- [CI/CD: autogeneración de traducciones con Husky, GitHub Actions y el CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/CI_CD.md)
+- [Probar el contenido y bloquear compilaciones por cobertura](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/testing.md)
+- [autoFill: generación de archivos de declaración por locale](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/autoFill.md)
+- [Referencia de configuración: `locales`, `requiredLocales`, `editor`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/configuration.md)
+- [Informes de benchmark entre frameworks](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/benchmark/index.md)
+- [Adaptador de compatibilidad i18next](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/compat/i18next.md)
+- [Cómo detectar traducciones faltantes](https://github.com/aymericzip/intlayer/blob/main/docs/blog/es/detecting_missing_translations.md)
+- [Cómo probar traducciones sin pruebas frágiles](https://github.com/aymericzip/intlayer/blob/main/docs/blog/es/i18n_testing_strategies.md)