@intlayer/docs 9.4.1 → 9.4.3

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)