Inicio rápido
Esta página guía un proyecto de un solo idioma a sus primeros archivos traducidos. Es para una aplicación JS/TS, una aplicación Python, una aplicación .NET, un sitio web o un sitio de documentación, o un README de repositorio y otros archivos Markdown. Se asume que:
- Node.js
>=22.16.0, o el ejecutable independiente para un proyecto de Python o .NET. - Una clave de API para un proveedor de LLM, o una instalación local de Ollama.
- El proyecto está en control de versiones, para que puedas revisar lo que escribe la herramienta.
Dos cosas difieren entre proyectos: cómo la herramienta encuentra tu texto y cómo tu aplicación carga el resultado. Elige tu ruta a continuación te envía a la guía correcta para ello.
Ejemplos ejecutables
¿Prefieres ver un proyecto terminado primero? Copia uno sin clonar el repositorio:
npx degit wsj-br/ai-i18n-tools/examples/console-app console-app
cd console-app
pnpm install
pnpm run i18n:syncReemplaza console-app con cualquier otro ejemplo de Node.js. Los ejemplos de Python y .NET no tienen package.json; cópiatelos de la misma manera. Los cuatro ejemplos de Python también están en ai-i18n-tools-python-examples.zip en la versión de GitHub, y los dos ejemplos de .NET están en ai-i18n-tools-dotnet-examples.zip. La lista completa, con lo que muestra cada uno, está en la página de Ejemplos.
Instalar
pnpm add -D ai-i18n-toolsnpm install --save-dev ai-i18n-tools y yarn add --dev ai-i18n-tools también funcionan. Los proyectos de Python y .NET instalan el ejecutable independiente y no necesitan Node.js. Linux y macOS: curl -fsSL https://raw.githubusercontent.com/wsj-br/ai-i18n-tools/main/install.sh | bash. Windows PowerShell: irm https://raw.githubusercontent.com/wsj-br/ai-i18n-tools/main/install.ps1 | iex. Otras opciones de instalación: Instalación.
Proveedor y clave API
Cada comando que llama a un LLM (translate-ui, translate-docs, translate-json, translate-svg y sync) necesita ambas cosas:
- Al menos un proveedor en
ai-i18n-tools.config.json: un bloqueproviders.<name>contranslationModels, y una claveproviderde nivel superior cuando se configura más de un proveedor.init -P <provider>genera ese preajuste. Para añadir proveedores, consulta Proveedores de LLM. Para elegir la lista de modelos, consulta Modelos de IA. - La clave API correspondiente en tu entorno, o en
.env/.env.localjunto aai-i18n-tools.config.jsoncuando no hay una clave API de proveedor ya configurada. Cada preajuste integrado lee una variable con nombre de la tabla de preajustes, por ejemplo,OPENROUTER_API_KEYcon-P openrouteroOPENAI_API_KEYcon-P openai. Ollama utiliza un punto final local y no necesita clave.
export OPENROUTER_API_KEY=sk-or-v1-your-key-hereextract, status y otros comandos que no llaman al LLM no necesitan ninguna de las dos cosas. Más información sobre archivos de entorno y PATH: Instalación.
Elige tu ruta
Encuentra lo que tienes, ejecuta los comandos en su bloque y luego continúa en la guía enlazada.
Una aplicación JS/TS
Tus botones y mensajes siguen siendo texto plano en el código fuente, por lo que la herramienta aún no tiene nada que encontrar. Primero deben envolverse en t(), y la aplicación necesita un pequeño archivo de configuración de i18next.
ai-i18n-tools init -P openrouter
ai-i18n-tools suggest-models --applyLuego sigue Añadir i18n a una aplicación JS/TS. Cubre el paso de envoltura, con un prompt de agente, antes de extract y translate-ui.
Una aplicación Python
ai-i18n-tools init -t ui-python -P openrouter
ai-i18n-tools suggest-models --applyLuego siga Añada i18n a una aplicación Python.
Una aplicación Django, Flask con catálogos Flask-Babel, o una aplicación que ya llama a gettext mantiene esas llamadas. Genere la estructura con ui-python-django, ui-python-flask, o ui-python-gettext en su lugar, luego siga Añada i18n a una aplicación Django / Python gettext.
Una aplicación .NET
ai-i18n-tools init -t ui-dotnet -P openrouter
ai-i18n-tools suggest-models --applyLuego siga Añadir i18n a una aplicación .NET. Una aplicación que ya usa ResourceManager o IStringLocalizer usa ui-dotnet-resx en su lugar, luego Añadir i18n a una aplicación .NET ResourceManager. migrate-dotnet-i18n reescribe T($"…") en llamadas {0} numeradas. --wrap audita las etiquetas XAML y C# sin marcar. El informe enumera las claves resx con nombre, como Resources.LoginButton, como sugerencias y no edita esas líneas.
Un sitio web o de documentación
Elige la plantilla para tu framework:
| Su sitio | Plantilla |
|---|---|
| Astro Starlight | ui-starlight |
| Docusaurus | ui-docusaurus |
| VitePress | ui-vitepress |
| Nextra | ui-nextra |
| Fumadocs | ui-fumadocs |
| Sitio web Astro simple | ui-astro-website |
| Páginas HTML simples | ui-plain-html o docs-plain-html |
ai-i18n-tools init -t ui-vitepress -P openrouterA continuación, siga Añadir i18n a un sitio web o sitio de documentación. Su prompt de agente habilita el enrutamiento i18n del framework. Ejecute sync después de revisar ese trabajo.
Un README o documentos Markdown
La mayoría de los repositorios quieren esto junto con la aplicación: la plantilla ui-markdown predeterminada ya incluye un bloque README plano. Para cualquier otra plantilla, añada --with-readme. Un repositorio con solo Markdown usa docs-markdown.
ai-i18n-tools init -P openrouter
ai-i18n-tools init -t ui-python -P openrouter --with-readme
ai-i18n-tools init -t ui-dotnet -P openrouter --with-readme
ai-i18n-tools init -t docs-markdown -P openrouterLuego siga Añadir i18n a su README y documentos Markdown. Pegue el marcador de lista de idiomas en README.md antes de sync. La ruta de la aplicación, si tiene una, sigue siendo Añadir i18n a una aplicación JS/TS, Añadir i18n a una aplicación Python, o Añadir i18n a una aplicación .NET.
Algo más
- JSON i18next anidado que permanece tal cual:
ai-i18n-tools init -t ui-json-bundles -P openrouter, luego JSON. - Diagramas SVG con etiquetas de texto: Traducción de SVG.
- Dejar de usar Intlayer: Migrar de Intlayer.
- Mantener Intlayer y solo rellenar sus traducciones: Traducir Intlayer in situ.
La lista completa de plantillas, con cada opción init, se encuentra en la referencia de configuración de la CLI.
Ejecución y verificación
Cuando su proyecto esté listo:
ai-i18n-tools doctor
ai-i18n-tools sync
ai-i18n-tools statusdoctor comprueba que la configuración, las rutas, los proveedores y el entorno estén listos. También verifica los ID de modelo con el proveedor a menos que pase --local. sync ejecuta cada paso que su configuración habilita, en orden. status muestra lo que se traduce por configuración regional. Una primera ejecución en un proyecto en el que la herramienta no puede ver texto finaliza sin error y no escribe nada útil, así que si status no muestra cadenas, vuelva a la guía para su ruta.
suggest-models clasifica los modelos de chat del proveedor activo según las pruebas de rendimiento publicadas. suggest-models --apply reemplaza a translationModels y no modifica uiModels ni localeModels. La misma clasificación se encuentra en la pestaña Modelos del panel de control. Cómo funciona la clasificación y por qué la lista contiene más de un modelo: Modelos de IA. Referencia de comandos: suggest-models.
Mantenerlo traducido
Vuelva a ejecutar sync cada vez que cambie el texto fuente. Una caché de SQLite significa que solo el texto nuevo o modificado va al modelo, por lo que las nuevas ejecuciones son económicas. Ejecutar sync en CI evita que las traducciones se desvíen. ai-i18n-tools dashboard abre el Panel de traducción para revisar y editar las traducciones en caché.
Scripts recomendados para package.json
Con el paquete instalado localmente, los scripts resuelven ai-i18n-tools desde node_modules/.bin sin configuración adicional del shell. Para un shell interactivo, configure PATH primero: consulte Uso de la CLI.
{
"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:status": "ai-i18n-tools status",
"i18n:statistics": "ai-i18n-tools statistics",
"i18n:dashboard": "ai-i18n-tools dashboard",
"i18n:cleanup": "ai-i18n-tools cleanup"
}Prefiera sync en lugar de encadenar los scripts de traducción individuales. Utilice los scripts de un solo paso solo cuando necesite un paso de forma aislada.
Para mostrar la salida de la CLI y el panel de control en otro idioma, pase -L <code> o establezca AI_I18N_LANG: consulte Idioma de la interfaz de usuario de la herramienta.
¿Está traduciendo más de un tipo de contenido, como cadenas de aplicaciones y un sitio de documentación juntos? Consulte Combinación de pipelines.
A continuación: la guía para su ruta en Elija su ruta.