Skip to content

Glosario ​

El glosario garantiza una terminología de producto coherente en todas las traducciones. Los usuarios pueden definir la traducción de un término en uno o varios idiomas, lo que permite al modelo de IA utilizar esta traducción predefinida en lugar de elegir una por sí mismo. También se puede utilizar para mantener ciertos términos, como los nombres de productos, sin cambios durante la traducción a otros idiomas.

Se envían dos tipos de indicaciones al modelo:

  • Filas de términos en glossary.userGlossary (y, para la documentación, JSON y SVG, las traducciones de UI existentes de cada bloque ui con uiGlossary activado). Una fila se incluye solo cuando ese término de origen aparece en el texto que se está traduciendo.
  • Archivos de contexto del proyecto en glossary.contextFiles. El resumen completo se inyecta en cada prompt de UI, documentación, JSON, SVG y revisión. Esa sección se encuentra a continuación.

Cómo funciona el glosario ​

De dónde provienen los términos ​

OrigenConfiguraciónUtilizado por
Catálogos de UIui[].uiGlossary (booleano, valor predeterminado true) — stringsJson de ese bloquetranslate-docs, translate-json, translate-svg
CSV de usuarioglossary.userGlossarytranslate-ui, proofread-ui, translate-docs, translate-json, translate-svg

init apunta glossary.userGlossary a glossary-user.csv y no crea ese archivo. Ejecuta glossary-generate cuando falte, y pon términos de dominio en él antes del primer translate-ui. Una segunda traducción de una cadena sin cambios puede volver redactada de forma diferente. El glosario es lo que hace que las dos ejecuciones coincidan.

Un bloque con uiGlossary: true reutiliza las traducciones ya almacenadas en su strings.json como sugerencias, de modo que la documentación, JSON y SVG se mantengan alineados con la UI. translate-ui y proofread-ui no leen esos catálogos; solo toman sugerencias del CSV de usuario, por lo que una traducción de UI incorrecta no se reintroduce como el término preferido. Establezca uiGlossary en false en un bloque que no deba influir en otros pipelines. Cuando varios bloques comparten un término de origen, el bloque anterior completa un locale y los bloques posteriores solo añaden los locales que aún faltan. El CSV de usuario prevalece sobre cualquier catálogo de UI. Una fila cuyo locale es un código específico reemplaza tanto la fila * como la traducción del catálogo de UI para ese locale. Un locale de * aplica la misma traducción a cada locale de destino que aún no tenga una proveniente de un catálogo de UI.

Las abreviaturas compactas de etiquetas de UI (un punto final como Alm., o una compresión corta de un solo token como Size → Tam) siguen disponibles para la traducción de la UI. Los prompts de documentos las omiten, de modo que no empujan a los modelos a inventar tokens {{…}} en markdown o MDX.

Un prefijo de varias palabras compartido por dos o más claves de catálogo se añade como un término propio cuando ese prefijo no es ya una clave. Para cada configuración regional, la traducción es el inicio compartido de esas traducciones de catálogo, cortado en un límite de palabra, y solo cuando ese inicio compartido tiene al menos cuatro caracteres. Cursor Models run out y Cursor Models at renewal pueden producir Cursor Models cuando ambas cadenas en alemán empiezan con Cursor-Modelle. Una fila CSV de usuario para la misma fuente reemplaza esa traducción preestablecida.

Cuándo se envía un término ​

La coincidencia no distingue mayúsculas de minúsculas y se detiene en un límite de palabra (espacio en blanco o puntuación). Se prefieren los términos más largos y se descartan las coincidencias superpuestas. Cuando un término coincide con el lote actual, el prompt recibe una sugerencia como "dashboard" → "Tableau". Si esa fila tiene una nota de Context, la nota se añade solo para esa coincidencia.

Contexto es una guía de uso en el idioma de origen (lo que significa el término o cómo usarlo). No es una traducción. Cambiar una nota de Contexto, o cualquier contenido de glossary.contextFiles, actualiza las traducciones en caché para la configuración regional afectada en la siguiente ejecución; no necesita --force. Cambiar solo la Traducción preferida en una fila que no está Forzada mantiene la caché existente hasta que pase --force o --force-update. Una fila Forzada (nueva, editada o borrada) no usa la caché solo para los segmentos cuyo origen contiene ese término, y solo cuando el texto almacenado no incluye ya la traducción forzada. Deje Contexto vacío en esa fila para esta actualización limitada; una nota de Contexto sigue actualizando toda la configuración regional. Las filas que editó en el panel de control permanecen como user-edited.

La traducción de Markdown verifica una etiqueta de interfaz de usuario de dos a cinco palabras cuando la fuente la cita como el fragmento completo en negrita o en código en línea, en un encabezado, o en una línea que contiene solo esa etiqueta. Una frase más larga en negrita que contiene el término es una pista, por lo que **Ask for target language** no requiere la forma de catálogo de Target language. Las pistas de una sola palabra aún pueden estar flexionadas. Una pista de CSV de usuario que no es también una etiqueta de interfaz de usuario sigue siendo una pista. La verificación ignora las mayúsculas y minúsculas y busca la redacción del catálogo como una subcadena, por lo que una forma flexionada aún puede fallar. Intenta con el siguiente modelo hasta que el mismo error de calidad haya ocurrido tres veces o la lista de modelos se agote, y no divide el segmento por una falta de etiqueta. Si esos intentos fallan solo en esa verificación, la ejecución mantiene el intento con menos fallos, escribe el documento y almacena en caché el segmento con una advertencia de etiqueta de glosario. El resumen enumera esas advertencias, y cacheDir recibe glossary-review-*.md, una instrucción que puedes pegar a una IA para marcar cada fallo como un falso positivo o un fallo real. El código de salida permanece en 0 cuando el único problema es esa advertencia.

Un falso positivo se puede omitir con glossary.labelCheckSkips en la configuración del proyecto (la pestaña Glosario del panel de control edita la misma lista). Cada entrada nombra el term en inglés, el locales a omitir (* significa cada configuración regional), y globs files opcionales. El término sigue siendo una pista de instrucción. --recheck-glossary-warnings traduce los segmentos marcados de nuevo y borra la marca cuando la verificación ahora pasa. --force los vuelve a traducir con cada otro segmento. El markdown en caché se vuelve a verificar cuando se procesa el archivo (--force-update); un archivo que el seguimiento de archivos omite se deja tal cual hasta que un término Force en ese archivo falta en la salida, o hasta que --recheck-glossary-warnings abre un archivo que tiene un segmento marcado. Se requiere una traducción de catálogo que difiera de la fuente dondequiera que se cite esa etiqueta, incluido un nombre de producto traducido. Mantén la ortografía de la fuente con una fila Force cuya traducción sea igual a la fuente.

Force ​

Cuando Force es true, yes o 1, el término de origen se extrae del texto antes de que el modelo lo vea y la traducción preferida se reescribe después. La redacción es exacta, no una sugerencia. Se aplican las mismas reglas de límite de palabra y coincidencia más larga. Deja Force vacío (o false) cuando el modelo deba preferir la traducción pero aún pueda flexionarla.

Generar un glosario ​

glossary-generate escribe un CSV vacío con el encabezado estándar. Utiliza glossary.userGlossary de la configuración, o glossary-user.csv cuando esa clave no está establecida. Se niega a sobrescribir un archivo que ya existe (código de salida 1).

bash
ai-i18n-tools glossary-generate
# or: ai-i18n-tools glossary-generate -o i18n/glossary.csv

Apunta la configuración al archivo:

json
{
  "glossary": {
    "userGlossary": "i18n/glossary.csv"
  }
}

También puede crear el archivo de glosario CSV directamente desde el panel de control. La primera acción de Añadir en la pestaña Glosario creará el archivo si se especifica glossary.userGlossary y el archivo aún no existe. Cuando glossary.autoAddUserEditedToGlossary es true (el valor predeterminado), corregir una cadena de la interfaz de usuario en el panel de control puede añadir ese cambio al CSV durante la siguiente ejecución de translate-ui. El panel de control también funciona como editor del glosario CSV, lo que le permite añadir, editar o filtrar filas dentro de la interfaz.

Columnas CSV ​

Fila de encabezado:

text
Original language string,locale,Translation,Force,Context

en o English se acepta en lugar de Original language string. Notes se acepta en lugar de Context.

ColumnaSignificado
Cadena de idioma originalTérmino o frase de origen, en la configuración regional de origen
configuración regionalCódigo de configuración regional de destino, o * para todos los destinos
TraducciónTraducción preferida
Forzartrue, yes o 1 para exigir esta redacción; de lo contrario, una sugerencia
ContextoExplicación opcional en el idioma de origen. Solo se envía cuando este término coincide

Ejemplos ​

Un término de producto para cada configuración regional, una etiqueta alemana forzada y una fila en francés que explica una palabra que el modelo podría interpretar literalmente:

csv
"Original language string","locale","Translation","Force","Context"
"dashboard","*","Tableau","false","The analytics home, not a vehicle panel"
"Save","de","Speichern","true",""
"workspace","fr","espace de travail","false","A user's project container, not an office"

Combinado con un resumen del proyecto:

json
{
  "glossary": {
    "userGlossary": "i18n/glossary.csv",
    "contextFiles": ["i18n/product-context.md"],
    "contextMaxChars": 12000
  }
}

Referencia del campo: glossary en Configuración. Referencia del comando: glossary-generate.

Archivos de contexto del proyecto ​

glossary.contextFiles es para la orientación a nivel de producto que no pertenece a una sola fila CSV: qué es el producto, para quién es, el tono y los términos que son fáciles de traducir mal. Apunte la configuración a uno o más archivos .md / .txt relativos al directorio de trabajo; se concatenan en el orden indicado y se inyectan en cada interfaz de usuario, documentos, JSON, SVG y solicitud de revisión.

json
{
  "glossary": {
    "userGlossary": "i18n/glossary.csv",
    "contextFiles": ["i18n/product-context.md"]
  }
}

Escriba el resumen en la configuración regional de origen, manténgalo muy por debajo de glossary.contextMaxChars (predeterminado 12000) y guárdelo fuera de docs[].contentPaths a menos que también desee que se traduzca ese archivo. Consulte glossary en Configuración.

Generar un archivo de contexto con un agente de IA ​

Pida a un agente (Cursor, Claude Code, Copilot y similares) que lea el repositorio y escriba el resumen. Pegue una instrucción como esta:

text
Create a translation-context Markdown file for this repository at i18n/product-context.md.

This file is injected verbatim into every ai-i18n-tools translation prompt (UI strings, docs, JSON, SVG, proofread). It must stay in the source language of the project (do not translate it). Translators already receive a glossary of preferred term mappings; this file should explain meaning, audience, and register — not duplicate every glossary row.

Requirements:
- Concise: aim for 1–4 KB, hard limit 8000 characters. No full manuals, README dumps, or changelog history.
- Source-language only. Short headings, bullet lists, and a few example sentences are enough.
- No secrets, API keys, credentials, personal data, internal URLs, or unpublished commercial figures.
- Do not invent product facts. If something is unclear, omit it or mark it as unknown.
- Do not put this file under a path that is also listed in docs[].contentPaths.

Cover, in this order:
1. Product in one paragraph: what it is, who uses it, and the default tone (formal / informal / technical).
2. Domain and disambiguation: terms that look ordinary in English but have a product-specific meaning (for example “dashboard” as an analytics home, not a vehicle panel).
3. Features or areas that change register (billing vs. onboarding vs. admin).
4. Things translators must preserve exactly: brand names, CLI flags, config keys, code identifiers, placeholder tokens.
5. Locale notes only when they affect meaning for every target (for example “use formal you”). Do not list per-locale translations here.

Write only the Markdown file. Afterward, remind me to add it to glossary.contextFiles in ai-i18n-tools.config.json if it is not already listed.

Revise el archivo antes de la siguiente ejecución de sync / translate-*. Cambiar el archivo invalida las traducciones en caché para cada configuración regional en esa ejecución, así que mantenga el resumen estable una vez que la calidad sea buena.

Publicado bajo la licencia MIT.