Glosario

Un archivo de glosario impone terminología consistente en las traducciones. Defina cómo deben traducirse términos específicos — o mantenerse sin traducir — y yaku inyecta estas reglas en el prompt del LLM.

Inicio rápido

Cree un archivo llamado .yaku-glossary.yaml en su directorio de trabajo:

es:
  deployment: despliegue    # siempre traducir así
  container: contenedor
  Kubernetes: ~             # mantener tal cual
  Docker: ~                 # mantener tal cual

Ahora traduzca como de costumbre. yaku carga el glosario automáticamente:

yaku --to es -f docs.en.md

El LLM recibe instrucciones como:

“Use these specific translations: deployment → despliegue, container → contenedor”
“Keep these terms in their original language (do NOT translate them): Kubernetes, Docker”

Formato del archivo

Los archivos de glosario usan YAML. Los términos se agrupan por código de idioma destino:

<idioma-destino>:
  <término>: <traducción>     # traducir a este valor
  <término>: ~                # mantener en idioma original (null de YAML)

Puede incluir secciones para múltiples idiomas en un archivo:

en:
  contenedor: container
  Kubernetes: ~

es:
  container: contenedor
  Kubernetes: ~

yaku solo carga la sección que coincide con su idioma destino --to (coincidencia insensible a mayúsculas). Por ejemplo, --to es coincide con es:, ES:, o Es:. Si no hay sección que coincida, yaku usa un glosario vacío.

Entradas de traducción

Proporcione un valor de cadena para definir cómo debe traducirse un término:

es:
  software: software
  database: base de datos
  machine learning: aprendizaje automático

Cuando yaku traduce a es, inyecta estos términos en el prompt del LLM como traducciones requeridas.

Entradas de mantener original

Use ~ (null de YAML) para indicar a yaku que mantenga un término en su idioma original:

es:
  Kubernetes: ~
  Docker: ~
  API: ~
  GitHub: ~

Esto es útil para nombres de marca, nombres propios y términos técnicos que no deben cambiarse durante la traducción.

Búsqueda de archivos

Cuando usa --glossary <ruta>, yaku carga solo ese archivo. De lo contrario, yaku verifica ambas ubicaciones predeterminadas y las fusiona (los términos de archivos posteriores sobrescriben a los anteriores):

~/.config/yaku/glossary.yaml — términos globales compartidos entre todos los proyectos (se carga primero)
.yaku-glossary.yaml en el directorio de trabajo actual — términos por proyecto (se carga último, tiene prioridad)

Ambos archivos se cargan si existen. Cuando el mismo término aparece en ambos, el archivo por proyecto tiene prioridad.

Para omitir la carga del glosario completamente:

yaku --to es --no-glossary -f docs.en.md

Ejemplo: glosario por proyecto + global

Configure un glosario global para nombres de marca que nunca quiere cambiar:

en:
  GitHub: ~
  Docker: ~
  Kubernetes: ~

es:
  GitHub: ~
  Docker: ~
  Kubernetes: ~

Luego agregue términos específicos del proyecto en cada proyecto:

es:
  container: contenedor
  deployment: despliegue
  service: servicio

Cuando ejecuta yaku --to es desde /ruta/a/mi-proyecto/, ambos archivos se cargan. El glosario global mantiene los nombres de marca sin cambios; el glosario del proyecto impone los términos de dominio.

Ruta explícita de glosario

yaku --to es --glossary ~/trabajo/terminos-compartidos.yaml -f docs.en.md

Cuando se usa --glossary, solo ese archivo se carga — las rutas predeterminadas se omiten.

Cómo funciona

Carga — yaku lee los archivos de glosario y busca la sección del idioma --to.
Inyección — Las entradas de traducción se convierten en "Use these specific translations: software → software". Las entradas de mantener original se convierten en "Keep these terms in their original language: Kubernetes, Docker".
Traducción — El LLM ve las instrucciones del glosario junto con el texto.
Verificación — Después de la traducción, yaku ejecuta una verificación de seguridad (EnforceKeepOriginal) para confirmar que los términos marcados con ~ siguen presentes en la salida. Esta es una red de seguridad — la imposición principal ocurre a través del prompt.

El enfoque de inyección en el prompt significa que el glosario funciona con todos los backends (Gemini, OpenAI, Anthropic, hosted) y todos los formatos (texto, Markdown, JSON, YAML).

Ejemplo completo: traducir un blog de cocina

es:
  # Mantener nombres de platos en su idioma original
  ratatouille: ~
  croissant: ~
  miso: ~
  dashi: ~

  # Estandarizar términos de cocina
  sauté: saltear
  julienne: cortar en juliana
  mise en place: mise en place

en:
  ratatouille: ~
  croissant: ~
  sauté: sauté
  julienne: julienne

yaku --to es -f recipe.en.md -o recipe.es.md

Cuándo usar un glosario

Proyectos de código abierto — mantener nombres de marca y términos técnicos consistentes entre traducciones.
Sitios de documentación — imponer terminología estándar (ej., siempre usar “contenedor” para “container”).
Industrias reguladas — fijar traducciones de términos legales o médicos.
Flujos de trabajo con múltiples traductores — asegurar que todos usen el mismo vocabulario.

Consejos

Empiece pequeño. Agregue términos solo cuando note inconsistencias. Un glosario con 10-20 términos cubre la mayoría de los proyectos.
Use ~ para nombres de marca. Términos como “GitHub”, “Kubernetes” y “Docker” casi siempre deben permanecer sin cambios.
Use el glosario global para términos universales. Ponga nombres de marca y términos técnicos comunes en ~/.config/yaku/glossary.yaml para que se apliquen en todas partes.
Coloque el glosario por proyecto en el directorio de trabajo. yaku busca .yaku-glossary.yaml en el directorio donde ejecuta el comando.
Combine con --context. El glosario maneja términos específicos; --context establece el tono y dominio general.