Instalación

El paquete publicado es solo ESM. Utilice import/import() en Node.js o en su empaquetador; no use require('ai-i18n-tools'). El paquete declara engines.node >=22.16.0; no se admiten versiones antiguas de Node.js. El tarball de npm incluye archivos en inglés solo bajo docs/; las copias específicas de configuración regional bajo translated-docs/ están en el repositorio de GitHub.

npm install ai-i18n-tools
# or
pnpm add ai-i18n-tools
# or
yarn add ai-i18n-tools

ai-i18n-tools incluye su propio extractor de cadenas. Si anteriormente utilizaba i18next-scanner, babel-plugin-i18next-extract o similar, puede eliminar esas dependencias de desarrollo después de la migración. Los archivos JSON de espacio de nombres de i18next existentes pueden permanecer en la canalización JSON. Los diccionarios .content.ts de Intlayer se pueden importar con migrate-intlayer; consulte Migración desde Intlayer.

Uso de la CLI

Instale ai-i18n-tools como dependencia o devDependency en su proyecto (consulte Instalación arriba). El paquete declara una entrada bin que su gestor de paquetes enlaza a node_modules/.bin/ai-i18n-tools. Ese shim (bin/ai-i18n-tools.mjs dentro del paquete instalado) carga la CLI compilada.

Para escribir el comando simple ai-i18n-tools en un shell interactivo, configure una de las opciones siguientes. Sin configuración, el shell no puede encontrar el binario incluso después de una instalación local.

direnv — añádalo a un .envrc en la raíz del proyecto (bash/zsh; consulte direnv.net):

PATH_add node_modules/.bin

Después de direnv allow, el comando simple estará disponible cada vez que acceda al proyecto con cd.

Ruta manual — ejecute estos comandos desde la raíz del proyecto (el directorio que contiene node_modules/.bin). Los subdirectorios seguirán funcionando después, siempre que deje esa entrada PATH en su lugar; volver a ejecutar la exportación desde una carpeta anidada fallará porque $PWD ya no apunta a la raíz del proyecto.

# bash/zsh — from the project root
export PATH="$PWD/node_modules/.bin:$PATH"
ai-i18n-tools sync

# Windows PowerShell — from the project root
$env:Path = "$PWD\node_modules\.bin;$env:Path"
ai-i18n-tools sync

Instalación global — instale la CLI una vez e invóquela desde cualquier directorio:

npm install -g ai-i18n-tools
# or
pnpm add -g ai-i18n-tools

Con pnpm, ejecute pnpm setup una vez por máquina (y abra un nuevo shell) si faltan comandos globales; pnpm requiere su directorio bin global en PATH. Una instalación global utiliza la versión fijada globalmente. Para fijar la versión por proyecto, prefiera direnv o PATH manual para que node_modules/.bin se resuelva en la dependencia del proyecto.

package.json scripts — cuando npm o pnpm ejecutan un script, anteponen node_modules/.bin a PATH, por lo que el nombre del comando base funciona dentro de los scripts sin cambios en la ruta del shell. Prefiera sync en lugar de encadenar manualmente los pasos de traducción — el orden y las banderas de características son fáciles de confundir cuando se ejecutan manualmente:

"scripts": {
  "i18n:extract": "ai-i18n-tools extract",
  "i18n:sync": "ai-i18n-tools sync",
  "i18n:translate:ui": "ai-i18n-tools translate-ui",
  "i18n:translate:svg": "ai-i18n-tools translate-svg",
  "i18n:translate:docs": "ai-i18n-tools translate-docs",
  "i18n:translate:json": "ai-i18n-tools translate-json",
  "i18n:dashboard": "ai-i18n-tools dashboard"
}

Luego ejecute, por ejemplo, pnpm run i18n:sync. Consulte Scripts package.json recomendados para ver el conjunto completo recomendado.

Alternativas — si prefiere no ajustar PATH: npx ai-i18n-tools … (npm) o pnpm exec ai-i18n-tools … (pnpm). Para una instalación única sin entrada package.json: npx ai-i18n-tools <cmd> o pnpm dlx ai-i18n-tools <cmd>.

Monorepo ai-i18n-tools clonado

Al desarrollar el paquete o ejecutar los ejemplos del espacio de trabajo desde un clon completo de ai-i18n-tools:

• Ejemplos de espacio de trabajo (examples/console-app, examples/nextjs-app y los otros paquetes listados en pnpm-workspace.yaml) — ejecute pnpm install en la raíz del repositorio, luego cd examples/<name>. Utilice los scripts pnpm run i18n:* del ejemplo, o configure PATH (consulte Uso de la CLI) y ejecute ai-i18n-tools … directamente. El enlace ai-i18n-tools del espacio de trabajo overrides a su copia local.
• Raíz del repositorio — pnpm no vincula el propio bin del paquete raíz a node_modules/.bin. El .envrc de esta copia añade bin/ a PATH para que el wrapper bin/ai-i18n-tools comprometido (junto al shim bin/ai-i18n-tools.mjs publicado) proporcione el comando directo después de direnv allow. Sin direnv, use node bin/ai-i18n-tools.mjs …, ./bin/ai-i18n-tools … o los scripts pnpm i18n:* raíz (o un alias de shell / pnpm add -g . — consulte Guía de desarrollo).
• Fixtures independientes (multi-provider, test-markdown) — desde la carpeta de fixtures, use node ../../bin/ai-i18n-tools.mjs ….

Ejecuta pnpm run build en la raíz del repositorio después de cambiar el código fuente de la CLI. Consulta la Guía de desarrollo para ver los pasos de compilación y las soluciones alternativas opcionales de instalación global.

En Linux, macOS y WSL, las instalaciones desde el registro establecen automáticamente el bit ejecutable en el script de la CLI. En Windows, los gestores de paquetes generan shim .cmd y .ps1 que invocan Node explícitamente.

Los comandos de traducción (translate-ui, translate-docs, translate-json, translate-svg, sync) requieren configuración del proveedor en ai-i18n-tools.config.json y una clave API para el proveedor activo. Ejecute ai-i18n-tools init [-P <provider>] para generar un bloque de proveedor predeterminado (openrouter si se omite); edite provider / providers para cambiar los preajustes o modelos — vea Proveedores y modelos de LLM. Ollama es el único preajuste incorporado que no necesita una clave API.

Establezca la clave API que coincida con su proveedor activo (vea la tabla de preajustes):

# Default init (openrouter)
export OPENROUTER_API_KEY=sk-or-v1-your-key-here
# Example: init -P anthropic
# export ANTHROPIC_API_KEY=sk-ant-your-key-here

O crea un archivo .env en la raíz del proyecto:

OPENROUTER_API_KEY=sk-or-v1-your-key-here

Idioma de la interfaz de usuario de la herramienta

La CLI localiza su propio texto de ayuda, resúmenes de registro y el Panel de traducción independientemente de las configuraciones regionales que traduzca. De forma predeterminada, sigue la configuración regional de su sistema operativo. Anule con -L pt-BR, export AI_I18N_LANG=es o "uiLanguage" en la configuración. Consulte Idioma de la interfaz de usuario de la herramienta.