i18next-cli

i18next-cli 🚀

Una CLI unificada y de alto rendimiento para i18next, impulsada por SWC.

---

Por defecto, i18next-cli solo extrae claves de traducción de archivos JavaScript y TypeScript (.js, .jsx, .ts, .tsx). Para extraer de otros tipos de archivo (como .pug, .vue, .svelte, etc.), debes usar o crear un plugin. Especificar extensiones de archivo adicionales en la configuración extract.input no es suficiente por sí solo: se requieren plugins para formatos que no sean JS/TS. Consulta la sección Sistema de Plugins para obtener detalles y ejemplos.

i18next-cli es una reinvención completa de la cadena de herramientas de análisis estático para el ecosistema i18next. Consolida la extracción de claves, la generación de seguridad de tipos, la sincronización de locales, el linting y las integraciones en la nube en una única CLI coherente y ultrarrápida.

🚀 ¡Pruébalo Ahora - Sin Configuración!

Puedes obtener un análisis instantáneo de tu proyecto i18next existente sin ninguna configuración. Solo ejecuta este comando en el directorio raíz de tu repositorio:

npx i18next-cli status

O encuentra cadenas hardcodeadas:

npx i18next-cli lint

Consejo:

Si buscas un backend gestionado para complementar i18next-cli, echa un vistazo a Locize — i18next-cli ya incluye los comandos locize-download, locize-sync y locize-migrate. Creado por el mismo equipo detrás de i18next, con entrega mediante CDN, traducción por IA, flujo de trabajo de revisión y sin necesidad de redespliegues para cambios de texto.

¿Por qué i18next-cli?

i18next-cli está construido desde cero para satisfacer las demandas del desarrollo web moderno.

• 🚀 Rendimiento: Al aprovechar un analizador nativo basado en Rust (SWC), ofrece un rendimiento órdenes de magnitud superior a los analizadores basados en JavaScript.
• 🧠 Inteligencia: Un analizador con estado y consciente del ámbito comprende correctamente patrones complejos como useTranslation('ns1', { keyPrefix: '...' }), getFixedT y funciones t con alias, minimizando la necesidad de soluciones manuales.
• ✅ Flujo de Trabajo Unificado: Una herramienta, un archivo de configuración, un flujo de trabajo integrado. Reemplaza varios scripts de sincronización.
• 🔌 Extensibilidad: Una arquitectura de plugins moderna permite que la herramienta se adapte a cualquier framework o flujo de trabajo personalizado.
• 🧑‍💻 Experiencia del Desarrollador: Un archivo de configuración completamente tipado, modos --watch en vivo, salida CLI y una migración desde herramientas heredadas.

Características

• Extracción de Claves: La extracción significa encontrar y recopilar automáticamente todas las claves de traducción utilizadas en tu código fuente (JavaScript/TypeScript, etc.) analizando la estructura del código (AST). Esto garantiza que cada cadena que necesita traducción sea identificada e incluida en tus archivos de traducción, reduciendo el trabajo manual y evitando claves faltantes.
• Seguridad de Tipos: Genera definiciones de TypeScript para autocompletado completo y seguridad de tipos.
• Sincronización de Locales: Mantén todos los archivos de idioma sincronizados con tu idioma principal.
• Linting de Código Preciso: Detecta cadenas hardcodeadas con alta precisión y reglas configurables.
• Estado de la Traducción: Obtén una visión general de alto nivel o un informe detallado, clave por clave, de la integridad de la traducción de tu proyecto.
• Sistema de Plugins: Arquitectura extensible para patrones de extracción y tipos de archivo personalizados (por ejemplo, HTML, Handlebars).
• Migración desde Versiones Anteriores: Migración automática desde configuraciones de i18next-parser.
• Integración en la Nube: Integración perfecta con la plataforma de gestión de traducciones Locize.

Instalación

npm install --save-dev i18next-cli

Inicio Rápido

De cero a localizado en un comando: ¿Empiezas desde una aplicación con cadenas hardcodeadas (por ejemplo, generada con v0, Lovable, Bolt o Cursor)? Ejecuta npx i18next-cli localize — detecta tu configuración, envuelve las cadenas hardcodeadas en llamadas t(), extrae claves, se conecta a Locize y traduce tu aplicación con IA. Consulta el comando localize. ¿Trabajas con un agente de codificación de IA (Claude Code, Cursor, ...)? npx i18next-cli localize --print-agent-prompt imprime el mismo flujo como un runbook de agente para copiar y pegar. Los pasos a continuación son la ruta manual.

1. Inicializar Configuración

Crea una configuración de forma interactiva:

npx i18next-cli init

O crea manualmente i18next.config.ts en la raíz de tu proyecto:

import { defineConfig } from 'i18next-cli';

export default defineConfig({
  locales: ['en', 'de'],
  extract: {
    input: ['src/**/*.{js,jsx,ts,tsx}'],
    output: 'public/locales/{{language}}/{{namespace}}.json',
  },
});

2. Verificar el Estado de tu Traducción

Obtén una visión general de la salud de localización de tu proyecto:

npx i18next-cli status

3. Extraer Claves de Traducción

npx i18next-cli extract

4. Generar Tipos (Opcional)

npx i18next-cli types

Comandos

init

Asistente de configuración interactivo para crear tu archivo de configuración.

npx i18next-cli init

Opciones:

• --ci: Omite la apertura del navegador cuando se selecciona un backend (por ejemplo, Locize); se imprime la URL de registro en su lugar. Útil para ejecuciones con scripts. El asistente también detecta automáticamente CI=true y recurre a imprimir la URL en Linux sin pantalla (sin DISPLAY/WAYLAND_DISPLAY), por lo que esta bandera rara vez se necesita explícitamente.
• --inlang: También prepara un proyecto inlang (project.inlang/settings.json) para que las herramientas de inlang — la extensión Sherlock de VS Code, el editor web Fink para traductores y el compilador Paraglide — funcionen directamente sobre tus archivos de traducción. Omite la pregunta correspondiente del asistente.

El asistente pregunta por el tipo de archivo de configuración, los locales, el glob de archivos fuente, la ruta de salida y finalmente "¿Backend de traducción?" con tres opciones:

• Solo archivos locales (predeterminado) — mantiene el flujo de trabajo local JSON actual.
• Locize (recomendado para equipos / flujos de producción) — abre la página de registro de Locize en tu navegador y luego solicita tu ID de proyecto y clave API. El asistente escribe un bloque locize en la configuración generada para que locize-sync funcione de inmediato. La solicitud de clave API se puede dejar vacía (modo de solo lectura); añádela más tarde mediante una variable de entorno LOCIZE_API_KEY.
• Otro / saltar — equivalente a "Solo archivos locales" a efectos del asistente.

Luego, el asistente ofrece configurar las herramientas de inlang (predeterminado: no — o pasa --inlang para omitir la pregunta). Si se acepta, prepara un project.inlang/settings.json que apunta el plugin i18next de inlang hacia tus archivos de traducción existentes: baseLocale/locales provienen de tu configuración, y pathPattern se deriva de extract.output (la forma de objeto con espacios de nombres cuando tu diseño usa {{namespace}}, con los espacios de nombres descubiertos en los archivos del idioma principal; de lo contrario, un patrón simple). También añade la extensión Sherlock a las recomendaciones de .vscode/extensions.json (fusionando con conciencia de comentarios, sin sobrescribir nunca las entradas existentes). Tus archivos JSON de i18next siguen siendo la única fuente de verdad: las herramientas de inlang los leen y escriben en su lugar, por lo que no hay un segundo catálogo que pueda desincronizarse. Un project.inlang/settings.json existente nunca se sobrescribe; volver a ejecutar init es seguro. Requiere archivos de recursos JSON. El plugin está fijado a una versión exacta verificada (@inlang/[email protected]) — actualiza la URL de modules en settings.json para obtener versiones más recientes del plugin. Solo se prepara settings.json por diseño: project.inlang/ es la forma de proyecto desempaquetada (amigable con git), y las herramientas de inlang generan y gestionan sus archivos restantes (.gitignore, README.md, cache/) en el primer uso — así que espera algunos archivos nuevos allí después de abrir el proyecto con Sherlock o Paraglide.

extract

Analiza archivos fuente, extrae claves y actualiza tus archivos de traducción JSON.

npx i18next-cli extract [options]

Opciones:

• --watch, -w: Vuelve a ejecutarse automáticamente cuando los archivos cambian
• --ci: Sale con un código de estado distinto de cero si se actualiza algún archivo (para CI/CD)
• --dry-run: No modifica ningún archivo - útil en combinación con --ci (para CI/CD)
• --sync-primary: Sincroniza los valores del idioma principal con los valores predeterminados del código
• --sync-all: Sincroniza los valores del idioma principal con los valores predeterminados del código Y limpia las claves sincronizadas en todos los demás locales (implica --sync-primary)
• --trust-derived: Cuando se usa con --sync-primary o --sync-all, también confía en los valores predeterminados inferidos de claves como t('Hello') o valores derivados de keyPrefix. Esto mantiene el comportamiento de sincronización predeterminado estricto a menos que se opte por ello.
• --with-types: Después de la extracción (y en cada re-ejecución en modo --watch), regenera las definiciones de TypeScript cada vez que los archivos de traducción cambian. Evita la necesidad de ejecutar extract -w y types -w como dos procesos separados.
• --quiet: Suprime el spinner y la salida no esencial (para CI o scripts)

Control de Salida del Spinner y el Logger

Todos los comandos que muestran spinners de progreso (extract, types, lint, sync) ahora admiten:

• La bandera --quiet para silenciar el spinner y la salida no esencial (para CI, scripts o captura de logs)
• Soporte de logger programático: pasa un objeto de logger personalizado para capturar la salida en tu propio formato o flujo

Ejemplo CLI:

npx i18next-cli extract --quiet

Ejemplo Programático:

import { runExtractor } from 'i18next-cli';
const logger = {
  info: (msg) => myLogStream.write(msg + '\n'),
  warn: (msg) => myWarnStream.write(msg + '\n'),
  error: (msg) => myErrStream.write(msg + '\n'),
};
await runExtractor(config, { quiet: false, logger });

Si pasas un logger, la salida del spinner y todos los mensajes de progreso/información se redirigen a tu logger en lugar del spinner interactivo.

Ejemplos:

# Extracción única
npx i18next-cli extract

# Modo watch para desarrollo
npx i18next-cli extract --watch

# Modo CI (falla si los archivos cambiaron)
npx i18next-cli extract --ci

# Sincronizar idioma principal con valores predeterminados del código
npx i18next-cli extract --sync-primary

# Sincronizar idioma principal y limpiar claves sincronizadas en todos los demás locales
npx i18next-cli extract --sync-all

# Sincronizar usando valores predeterminados explícitos más valores inferidos de claves
npx i18next-cli extract --sync-all --trust-derived

# Combinar opciones para un flujo de trabajo de desarrollo óptimo
npx i18next-cli extract --sync-primary --watch

# Mantener las definiciones de TypeScript sincronizadas desde un solo proceso (sin necesidad de un `types -w` separado)
npx i18next-cli extract --watch --with-types

status [locale]

Muestra una verificación de estado de la traducción de tu proyecto. Puede ejecutarse sin un archivo de configuración. Sale con un código de estado distinto de cero cuando faltan traducciones.

El idioma principal también se verifica: cualquier clave utilizada en tu código pero ausente en los archivos de traducción del idioma principal (un error tipográfico, o extract nunca se ejecutó) se informa y provoca un código de salida distinto de cero. Los marcadores de posición de cadena vacía escritos por extract se consideran presentes y no fallan la verificación. Ejecutar npx i18next-cli status <primaryLanguage> muestra las claves ausentes en detalle.

Opciones:

• --namespace <ns>, -n <ns>: Filtra el informe por un espacio de nombres específico.
• --hide-translated: Oculta las claves ya traducidas en la vista detallada, mostrando solo las traducciones faltantes.
• status.ignoreKeys (config): patrones glob para claves que no deben informarse (y no fallan la verificación), por ejemplo, claves que se dejan intencionalmente vacías en algunos locales. Prefijo ns: opcional (common:help.*-href). Solo afecta a status.
• --unused: Informa solo las claves de traducción no utilizadas — claves presentes en tus archivos de traducción que ya no se usan en tu código fuente (es decir, lo que extract con removeUnusedKeys eliminaría). Nunca modifica ningún archivo y sale con un código de estado distinto de cero cuando se encuentran claves no utilizadas, por lo que puede servir como una verificación de CI dedicada junto con la verificación regular de traducciones faltantes. Ten en cuenta que el análisis estático no puede detectar claves construidas dinámicamente (por ejemplo, t(`error.${code}`)); para encontrar claves que realmente no se usan en tiempo de ejecución, consulta encontrar traducciones no utilizadas con locize.

Ejemplos de uso:

# Obtener un resumen de alto nivel para todos los locales y espacios de nombres
npx i18next-cli status

# Obtener un informe detallado, clave por clave, para el locale 'de'
npx i18next-cli status de

# Obtener un resumen solo para el espacio de nombres 'common' en todos los locales
npx i18next-cli status --namespace common

# Obtener un informe detallado para el locale 'de', mostrando solo el espacio de nombres 'common'
npx i18next-cli status de --namespace common

# Mostrar solo las claves no traducidas para el locale 'de'
npx i18next-cli status de --hide-translated

# Combinar opciones para ver solo las traducciones faltantes en un espacio de nombres específico
npx i18next-cli status de --namespace common --hide-translated

# Informar solo claves no utilizadas en todos los locales (solo lectura, sale con 1 cuando se encuentra alguna)
npx i18next-cli status --unused

# Informar solo claves no utilizadas en los archivos 'en' — por ejemplo, como una verificación de CI separada
npx i18next-cli status en --unused

La vista detallada proporciona un resumen rico y de un vistazo para cada espacio de nombres, seguido de una lista de cada clave y su estado de traducción.

Ejemplo de Salida (npx i18next-cli status de):

Estado de las claves para "de":

General: [■■■■■■■■■■■■■■■■■■■■] 100% (12/12)

Espacio de nombres: common
Progreso del espacio de nombres: [■■■■■■■■■■■■■■■■■■■■] 100% (4/4)
  ✓ button.save
  ✓ button.cancel
  ✓ greeting
  ✓ farewell

Espacio de nombres: translation
Progreso del espacio de nombres: [■■■■■■■■■■■■■■■■□□□□] 80% (8/10)
  ✓ app.title
  ✓ app.welc

…

[truncado para la traducción]