Cadenas de la interfaz de usuario
Referencia para extract y translate-ui, el pipeline que convierte las llamadas a t() en catálogos por configuración regional. ¿Añadiendo i18n a una aplicación por primera vez? Comienza en 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. Cubren el paso de envoltura y luego te envían de vuelta aquí para los Pasos 2 a 4.
Este pipeline es compatible con proyectos JS/TS (React, componentes de cliente y de servidor de Next.js, servicios de Node.js, HTML plano, sitios web de Astro y herramientas CLI), aplicaciones Python y aplicaciones .NET. JS/TS busca cadenas con i18next después de que el código fuente llama a t(). Python llama a t() o a gettext a través de un i18n.py generado (Django mantiene el gettext de Django). .NET llama a T() a través de un I18n.cs generado.
Qué guía leer
| Su aplicación | Leer a continuación |
|---|---|
JS/TS con cadenas de texto incrustadas, sin t() todavía | Añadir i18n a una aplicación JS/TS |
React / Next.js / Node, t() ya en el código fuente | Configurar i18next |
Python (t(), _(), gettext, Jinja, Django) | Aplicaciones Python. Inicialización: ui-python, ui-python-gettext, ui-python-flask, o ui-python-django. Ayudante: i18n.py. Para añadir configuraciones regionales a una aplicación existente, consulta Añadir i18n a una aplicación Python, o Añadir i18n a una aplicación Django / Python gettext cuando la aplicación usa gettext. |
.NET (T(), Tn, Tp, XAML loc:Tr) | Aplicaciones .NET. Inicialización: ui-dotnet (I18n.cs) o ui-dotnet-resx (Añadir i18n a una aplicación .NET ResourceManager). Para añadir configuraciones regionales a una aplicación existente, consulta Añadir i18n a una aplicación .NET. |
HTML plano (sin t() en el marcado) | Aplicaciones HTML planas |
| Sitio de marketing de Astro (híbrido) | Sitio web de Astro |
Reglas de t(), interpolación, plurales | Llamadas a t() y plurales |
| Selector de idioma / RTL | Selector de idioma y RTL |
| Firmas de API en tiempo de ejecución | Ayudantes en tiempo de ejecución |
Diccionarios Intlayer .content.ts, migrando de Intlayer | Migrar desde Intlayer |
Diccionarios Intlayer .content.ts, manteniendo Intlayer | Traducir Intlayer in situ |
Paso 1: Inicializar
ai-i18n-tools init -P openrouterEsto escribe ai-i18n-tools.config.json con la plantilla ui-markdown (incluyendo el bloque provider / providers para ese preajuste). Esa plantilla también activa la traducción de documentos para README.md, escritos como archivos planos bajo translated-docs/. Los repositorios solo con README usan init -t docs-markdown en su lugar. Consulte Añadir i18n a su README y documentos Markdown. Antes de ejecutar translate-ui o sync, establezca la clave de API para ese proveedor en el entorno o .env — excepto Ollama; consulte Proveedor y clave de API. Cuatro claves son importantes para las cadenas de la interfaz de usuario:
sourceLocale: el código BCP-47 del idioma en el que está escrito su texto fuente. Cualquier idioma es válido;"en-GB"es solo un ejemplo. Debe coincidir conSOURCE_LOCALEexportado desde su archivo de configuración de i18n en tiempo de ejecución (src/i18n.ts/src/i18n.js). La cadena dentro det()es ese idioma fuente, y los archivos de configuración regional planos lo usan como clave.targetLocales: códigos BCP-47 para sus idiomas de destino (por ejemplo,["de", "fr", "pt-BR"]). Ejecutegenerate-ui-languagespara crear el manifiestoui-languages.jsona partir de esta lista.ui.sourceRoots: directorios o patrones glob para escanear en busca de llamadas at("…")(por ejemplo,["src/"]).ui.stringsJsonyui.flatOutputDir: dónde se escriben el catálogo maestro y los archivos por configuración regional (de.json,pt-BR.json).
Todas las demás claves, incluyendo providers.<active>.uiModels, se encuentran en Configuración.
Paso 2: Extraer cadenas
extract no hace nada útil hasta que existan esas llamadas a t() / i18n.t(). Encapsule el texto incrustado primero: Añadir i18n a una aplicación JS/TS.
ai-i18n-tools extractEscanea archivos bajo ui.sourceRoots en busca de llamadas a t("literal") y i18n.t("literal"). Escribe (o fusiona en) ui.stringsJson.
El escáner es configurable: añade nombres de funciones personalizadas a través de ui.uiExtractor.funcNames (o el legado ui.reactExtractor.funcNames). Para páginas y componentes de Astro, añade .astro a ui.uiExtractor.extensions. Para HTML plano, consulta Aplicaciones HTML planas.
Qué escanea la extracción
- Las extensiones predeterminadas son solo
.js,.jsx,.tsy.tsx..mjs,.cjs,.mtsy.ctsse incluyen solo cuando las añade aui.uiExtractor.extensions. - Una clave no literal como
t(variable)o un literal de plantilla se omite sin advertencia. package.jsondescriptionse incluye por defecto (ui.uiExtractor.includePackageDescription).- Los componentes de archivo único de Vue y Svelte no son compatibles. Añadir
.vueo.svelteaextensionsno extrae el texto de la plantilla. No hay un analizador SFC.
Paso 3: Traducir cadenas de la interfaz de usuario
ai-i18n-tools translate-uiLee strings.json, envía lotes a los modelos en el proveedor de LLM activo para cada configuración regional de destino, escribe archivos JSON planos (de.json, fr.json, etc.) en ui.flatOutputDir. La selección del modelo utiliza la cadena de interfaz de usuario: localeModels(locale) → uiModels → translationModels (véase Modelos de IA). Dentro de una configuración regional, se ejecutan hasta uiBatchConcurrency lotes a la vez (predeterminado: 2; véase Configuración — uiBatchConcurrency). -j sigue paralelizando únicamente las configuraciones regionales de destino. Cada lote exitoso se escribe en strings.json y en el archivo de configuración regional plano antes de que comience el siguiente lote, por lo que detener la ejecución o un error posterior de la API mantiene los lotes ya finalizados.
Base de datos de traducciones (strings.json)
Para cada entrada, translate-ui almacena el ID de modelo del proveedor activo que tradujo con éxito cada idioma en un objeto models opcional (las mismas claves de idioma que translated). Las cadenas editadas en el Panel de traducción se marcan con el valor centinela user-edited en models para ese idioma. Los archivos planos por idioma en ui.flatOutputDir permanecen solo como cadena de origen → traducción; no incluyen models (por lo que los paquetes en tiempo de ejecución permanecen sin cambios).
Nota: Las ediciones del panel de control en las cadenas de la interfaz de usuario residen en
strings.json, no en la caché de documentación de SQLite. Ejecutasyncotranslate-uisin opciones especiales (sin indicador especial) para reescribir los archivos de configuración regional planos desde el catálogo —--force-updateno se reenvía al paso de la interfaz de usuario. Evita--forceen los comandos de la interfaz de usuario después de las ediciones manuales: vuelve a traducir cada entrada y puede sobrescribir tus filasuser-edited. Las filas del catálogo cuya traducción almacenada no supera la comprobación del sistema de escritura de la configuración regional (por ejemplo, hindi romanizado parahi) se tratan como ausentes y se vuelven a traducir sin--force.
Paso 4: Usar la salida en su aplicación
translate-ui solo escribe archivos. La aplicación tiene que cargarlos.
- JS/TS: configura i18next con los ayudantes de tiempo de ejecución, carga el archivo de configuración regional que el usuario elija y añade un selector de idioma. Consulta Conectar i18next y Selector de idioma y RTL.
- Python: usa el
i18n.pygenerado o tus catálogos gettext. Consulta Aplicaciones Python. - .NET: usa el
I18n.csgenerado, oI18nResx.cscuando la aplicación ya usaResourceManager. Consulta Aplicaciones .NET y Añadir i18n a una aplicación .NET ResourceManager.migrate-dotnet-i18nreescribe argumentosT()no seguros.--wrapaudita etiquetas sin marcar. - HTML plano: carga el script de tiempo de ejecución junto a la página. Consulta Aplicaciones HTML plano.
- Astro: consulta Sitio web de Astro.
Opcional
Anulaciones de modelo por configuración regional
Algunos modelos traducen mejor ciertos idiomas que otros. Por ejemplo, los modelos qwen y z-ai suelen funcionar bien con los idiomas asiáticos. Añade entradas providers.<active>.localeModels para proporcionar una lista de modelos priorizada para cada configuración regional BCP-47. Esas listas se prueban antes que uiModels y translationModels para esa configuración regional. Las etiquetas de configuración regional coinciden sin distinguir entre mayúsculas y minúsculas (zh-cn y ZH-CN son equivalentes). Si no hay ninguna entrada coincidente, la herramienta utiliza el orden predeterminado de uiModels y translationModels. El mismo mecanismo localeModels se aplica a la traducción de documentos, JSON y SVG.
Exportación a XLIFF 2.0
Para entregar las cadenas de la interfaz a un proveedor de traducción, un sistema de gestión de traducción (TMS) o una herramienta CAT, exporta el catálogo como XLIFF 2.0 (un archivo por configuración regional de destino). Este comando es de solo lectura: no modifica strings.json ni llama a ninguna API.
ai-i18n-tools export-ui-xliffPor defecto, los archivos se escriben junto a ui.stringsJson, con nombres como strings.de.xliff, strings.pt-BR.xliff (nombre base de tu catálogo + configuración regional + .xliff). Usa -o / --output-dir para escribir en otra ubicación. Las traducciones existentes de strings.json aparecen en <target>; las configuraciones regionales faltantes usan state="initial" sin <target> para que las herramientas puedan completarlas. Usa --untranslated-only para exportar solo las unidades que aún necesitan traducción para cada configuración regional (útil para lotes enviados a proveedores). --dry-run muestra las rutas sin escribir archivos.