Skip to content

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ónLeer a continuación
JS/TS con cadenas de texto incrustadas, sin t() todavíaAñadir i18n a una aplicación JS/TS
React / Next.js / Node, t() ya en el código fuenteConfigurar 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, pluralesLlamadas a t() y plurales
Selector de idioma / RTLSelector de idioma y RTL
Firmas de API en tiempo de ejecuciónAyudantes en tiempo de ejecución
Diccionarios Intlayer .content.ts, migrando de IntlayerMigrar desde Intlayer
Diccionarios Intlayer .content.ts, manteniendo IntlayerTraducir Intlayer in situ

Paso 1: Inicializar ​

bash
ai-i18n-tools init -P openrouter

Esto 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 con SOURCE_LOCALE exportado desde su archivo de configuración de i18n en tiempo de ejecución (src/i18n.ts / src/i18n.js). La cadena dentro de t() 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"]). Ejecute generate-ui-languages para crear el manifiesto ui-languages.json a partir de esta lista.
  • ui.sourceRoots: directorios o patrones glob para escanear en busca de llamadas a t("…") (por ejemplo, ["src/"]).
  • ui.stringsJson y ui.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.

bash
ai-i18n-tools extract

Escanea 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, .ts y .tsx. .mjs, .cjs, .mts y .cts se incluyen solo cuando las añade a ui.uiExtractor.extensions.
  • Una clave no literal como t(variable) o un literal de plantilla se omite sin advertencia.
  • package.json description se incluye por defecto (ui.uiExtractor.includePackageDescription).
  • Los componentes de archivo único de Vue y Svelte no son compatibles. Añadir .vue o .svelte a extensions no extrae el texto de la plantilla. No hay un analizador SFC.

Paso 3: Traducir cadenas de la interfaz de usuario ​

bash
ai-i18n-tools translate-ui

Lee 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. Ejecuta sync o translate-ui sin opciones especiales (sin indicador especial) para reescribir los archivos de configuración regional planos desde el catálogo — --force-update no se reenvía al paso de la interfaz de usuario. Evita --force en los comandos de la interfaz de usuario después de las ediciones manuales: vuelve a traducir cada entrada y puede sobrescribir tus filas user-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 para hi) 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.

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.

bash
ai-i18n-tools export-ui-xliff

Por 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.

Publicado bajo la licencia MIT.