x18n: un toolkit universal para la internacionalización y el linting de traduccionesNota · digest del 9 de noviembre
Interfaz de consola del toolkit x18n en la pantalla oscura de un portátil con resultados de linting de idiomas junto a tarjetas de diccionarios en, ru y de sobre un escritorio de madera.
Nota3 secciones≈ 5 min

x18n: un toolkit universal para la internacionalización y el linting de traducciones

¿Con qué frecuencia revisas manualmente los archivos de idioma del proyecto antes de enviar un pull request, para que a un usuario extranjero no le aparezca una clave técnica sin procesar en el botón de pago en lugar de un texto comprensible? Normalmente editamos el diccionario base, comprobamos la página en el navegador y fusionamos la rama, confiando en el bundler y los tests.

El problema es que el compilador es ciego a las traducciones: para él, un identificador de cadena es solo texto, aunque no exista esa entrada en otro idioma. ¿Cómo poner orden en las traducciones de una aplicación web y evitar que se pierdan claves en el pipeline de integración continua (CI)? Esta tarea la resuelve el toolkit abierto x18n (el código fuente está abierto en x18n-dev/x18n y destacado en Best of JS), un conjunto de herramientas modular para la internacionalización (i18n, es decir, la adaptación de un programa a varios idiomas).

Por qué la gestión manual de idiomas convierte los diccionarios en un almacén de claves olvidadas

La mecánica de la localización se parece a un guardarropa con fichas numeradas y libros de registro en papel. En el código no se escriben las frases directamente: el programador coloca en el marcado una «ficha» con la dirección de la casilla, por ejemplo t('settings.billing.card_expired'), y la aplicación busca la cadena por ese número en el cuaderno inglés, ruso o alemán.

En un proyecto web en Vue y Nuxt con 3 idiomas (en, ru, de) y 400 claves de traducción en archivos JSON, el control manual falla rápidamente. Al refactorizar los pagos y el perfil, el equipo renombra 12 constantes de cadena en los componentes y actualiza solo locales/en.json. Como resultado, en ru.json y de.json se pierden 12 claves nuevas (los clientes ven la ruta sin procesar settings.billing.card_expired), 12 cadenas antiguas quedan como peso muerto en el bundle, las frases originales modificadas y los marcadores {name} quedan desactualizados en otros idiomas, y en las plantillas se cuela texto hardcodeado.

Cómo el núcleo modular de x18n, los presets incluidos y el linter CLI detectan discrepancias

Te preguntarás: «Pero si para los editores ya existe desde hace tiempo el plugin i18n-ally, ¿por qué hizo falta una herramienta nueva?» Yo también me hice esa pregunta al estudiar la documentación. El creador del plugin original, Anthony Fu, lo construyó en torno a la API interna de VS Code, por lo que no se podía llevar la comprobación a la terminal en un servidor de CI ni conectarlo a otros editores.

En x18n dividieron el sistema en capas independientes. El núcleo @x18n/core construye un grafo de relaciones entre el código y los diccionarios, detecta textos fuente desactualizados (stale detection) e incluye 45+ presets de frameworks con soporte para JSON, YAML, PO, Fluent e INI. La carpeta locales/ se detecta automáticamente sin configuración, y sobre el motor funcionan el servidor de lenguaje @x18n/lsp y un panel para el navegador.

Para interceptar la pérdida de esas 12 constantes en nuestro proyecto de Vue y Nuxt con 3 idiomas y 400 claves, ejecutamos el linter de consola @x18n/cli:

pnpx @x18n/cli check --strict --json
pnpx @x18n/cli usages common.buttons.submit

En nuestro escenario, el paso pnpx @x18n/cli check --strict en el pipeline de CI detiene la compilación con código 1, bloqueando el despliegue de un formulario de pago roto. La terminal muestra las 12 claves faltantes en ru.json y de.json y las 12 cadenas antiguas para eliminar, mientras que el flag --json devuelve un informe con números de línea para scripts y agentes de IA. Tras añadir las traducciones, la comprobación devuelve el código 0 (All i18n checks passed).

Limitaciones de la detección automática y costes adicionales al integrarlo

Antes de integrarlo, conviene tener en cuenta los límites del toolkit. Para ejecutar la CLI hace falta Node.js versión 18.0.0 o superior (el análisis se realiza en local sin enviar archivos a la red, aunque no se deben guardar secretos en los diccionarios). Para formatos corporativos poco comunes hará falta un plugin propio para @x18n/core, y para guardar diccionarios tipados dentro de las carpetas de los componentes en lugar de archivos JSON compartidos encaja mejor la internacionalización por componentes en Intlayer.

Si se usan wrappers personalizados en lugar de t(), la detección automática no verá las llamadas y marcará las claves como «muertas». Para definir tus propias funciones y excluir los tests en un proyecto con Vue y Nuxt, añadimos x18n.config.ts:

import { defineConfig } from '@x18n/core'

export default defineConfig({
  sourceLocale: 'en',
  resources: [{ pattern: 'locales/{locale}.json' }],
  usage: {
    include: ['src/**/*.vue', 'src/**/*.ts'],
    exclude: ['**/*.spec.ts', '**/*.test.ts'],
    calls: [{ callee: ['t', '$t', 'i18n.t'] }],
  },
})

Con esta configuración y el script "lint:i18n": "x18n check --strict" en package.json, el escáner ignora los tests *.spec.ts, detecta las llamadas a i18n.t y mantiene las 400 claves en los 3 idiomas bajo la protección del CI. Y si ahora mismo ejecutas pnpx @x18n/cli check en tu repositorio de trabajo, ¿cuántas claves olvidadas y discrepancias silenciosas entre idiomas saldrán a la luz en la terminal?

Quiero un análisis detalladoLos votos ayudan a elegir qué analizar a fondo. Este material tiene 0 votos.
Fuentes · 5