Paquetes de idioma de Hermes: haz que la CLI, el gateway y el escritorio hablen tu idioma

La mitad de tu equipo lee la terminal en inglés y la otra mitad no, así que cada semana alguien malinterpreta algún prompt. Uno de esos casos fue una larga línea de aprobación en inglés antes de un comando peligroso: se leyó en diagonal y se respondió con la tecla equivocada. Otro ingeniero intentó cambiar la interfaz a su propio idioma con hermes config set display.language pl y recibió de vuelta ✗ Unknown language 'pl'. Hermes incluye 17 idiomas de interfaz, y el polaco, el coreano o el portugués de Brasil no están entre ellos, así que ningún valor de configuración puede inventarlos. Un paquete de idioma lo resuelve: un plugin hecho de archivos YAML que sustituye el texto estático de la interfaz — las líneas de aprobación de la CLI, las respuestas del gateway de mensajería, los verbos de las herramientas, los consejos, la interfaz de hermes --tui y la app de escritorio — y nada de eso necesita código Python.

Hermes incluye 17 idiomas de interfaz, pero la lista es ampliable

El conjunto incluido son 17 idiomas, que se seleccionan con display.language. Sus catálogos viven en locales/ como af, ar, de, en, es, fr, ga, hu, it, ja, ko, pt, ru, tr, uk, zh-hant y zh.

hermes config set display.language acepta cualquier id que pueda aportar alguna de las capas. Un id que nadie reconoce se rechaza de plano, imprimiendo a continuación los idiomas disponibles:

$ hermes config set display.language pl
✗ Unknown language 'pl' for display.language. Available: en, af, ar, de, es, ...
  Install a language pack plugin (hermes plugins install <pack>) or drop <HERMES_HOME>/locales/<id>.yaml to add one.

El mensaje de error ya nombra las dos salidas: instalar un plugin de paquete de idioma, o dejar caer un archivo overlay propio. Y una cosa más que sorprende a quien está depurando el clásico «lo cambié, ¿por qué no cambia nada?»: HERMES_LANGUAGE en .env sigue teniendo prioridad sobre display.language.

Todo esto se apoya en el trabajo de la v0.22.0: el PR #126296 hizo pasar cada cadena visible al usuario en la CLI, el gateway de mensajería, la TUI y el escritorio por un único catálogo de traducción, que es justo lo que le da a un paquete un punto donde engancharse. La página de la release v0.22.0 cubre la release en sí.

Instala un paquete con dos comandos

Un paquete de idioma se instala como cualquier otro plugin. Si aún no tienes Hermes instalado, empieza por la guía de instalación. Después:

hermes plugins install hermes-lang-pt-br   # un nombre del catálogo, o una URL de repositorio
hermes config set display.language pt-br

Dos paquetes se integraron en el catálogo oficial el 14 de octubre de 2026: hermes-lang-ko para el coreano y hermes-lang-pt-br para el portugués de Brasil. La documentación explica paso a paso hermes plugins install https://github.com/teknium1/hermes-lang-pl por si quieres ver cómo es un paquete real. El descubrimiento y la instalación funcionan exactamente igual que con cualquier otro plugin, algo que la guía del catálogo de plugins explica de principio a fin.

Reinicia cualquier gateway o TUI que esté en marcha después de instalar, para que recargue el paquete. Los selectores de idioma de la TUI y del escritorio listan los idiomas incluidos, los de tus propios overlays y los de cada paquete instalado por su nombre nativo —el endónimo, como Polski— en lugar de por su código.

De dónde sale realmente una cadena de la interfaz

Cuando Hermes busca una cadena, recorre estas capas empezando por arriba y se queda con la primera coincidencia:

  1. Paquetes de idioma de plugins — cualquier plugin instalado que declare provides_locales (si dos paquetes cubren la misma clave, gana el que se cargó en último lugar)
  2. Tu overlay — <HERMES_HOME>/locales/<lang>.yaml, por perfil, de modo que un perfil con nombre usa ~/.hermes/profiles/<name>/locales/
  3. Incluidos — los catálogos locales/<lang>.yaml que vienen con Hermes

Si ninguna de esas tres tiene la clave, se prueban esas mismas tres capas para el inglés y solo entonces aparece la clave en bruto en pantalla. Todas las capas pueden ser parciales: un paquete solo necesita las claves que quiere cambiar, no una copia completa del catálogo.

Escribe un paquete sin escribir Python

Nada de esto necesita código Python. Un paquete mínimo tiene este aspecto:

hermes-lang-pl/
  plugin.yaml
  locales/
    pl.yaml            # core: approval.*, gateway.*, cli.*, display.*, slash.*, tips.*, ...
    pl.tui.yaml        # opcional: cadenas de hermes --tui
    pl.desktop.yaml    # opcional: cadenas de la app de escritorio

El manifiesto declara qué idioma aporta el paquete:

name: hermes-lang-pl
version: 1.0.0
description: Polish language pack for Hermes
provides_locales:
  - id: pl            # etiqueta en minúsculas estilo BCP-47: pl, pt-br, zh-hant
    endonym: Polski   # se muestra en los selectores de idioma
    rtl: false        # true para escrituras de derecha a izquierda; invierte el layout del escritorio

Las entradas de provides_locales también pueden ser ids simples (- pl), y entonces el endónimo toma el id por defecto. En cuanto existe ese bloque, el cargador de plugins registra automáticamente todos los locales/<lang>[.tui|.desktop].yaml del paquete: no queda nada más que cablear.

Los plugins que ya tienen código Python pueden registrar sus propios catálogos en su lugar: ctx.register_locale("pl", path_or_mapping, endonym="Polski", rtl=False, surface="core"), donde surface es core, tui o desktop, o bien ctx.register_locale_dir(dir) para registrar una carpeta entera de una vez. El registro se deshace cuando el plugin se descarga, y nunca cambia display.language.

Valídalo y cuidado con los marcadores de posición

Ejecuta el validador antes de publicar:

hermes plugins validate ./hermes-lang-pl

Comprueba que cada id declarado tenga su locales/<id>.yaml correspondiente, que cada archivo se parsee y que todos los valores sean texto: un número, una lista, un true/false o un valor vacío son un error, no un aviso. Las claves que no existen en el catálogo inglés de esa superficie solo generan un aviso con la lista adjunta: son inofensivas, pero no hacen nada. Mientras escribes, mantente lejos de las palabras reservadas de YAML como claves: on, off, yes y no.

Los marcadores de posición son la segunda trampa. Las cadenas de core (lado Python) usan marcadores con nombre: si el valor inglés dice {count}, la traducción debe conservar {count}. Si lo eliminas o lo escribes mal, esa clave vuelve silenciosamente a la cadena sin traducir. Las entradas de la TUI y del escritorio cuyo valor inglés recibe argumentos usan en cambio marcadores posicionales, {0} y {1}.

Sustituye una línea sin crear un paquete

Para cambiar una o dos frases, puedes prescindir del plugin por completo y dejar un archivo parcial en tu directorio de Hermes:

# ~/.hermes/locales/en.yaml — solo las claves que quieres cambiar
approval:
  denied: "      ✗ Nope."

El overlay se aplica solo a ese perfil (un perfil con nombre lee ~/.hermes/profiles/<name>/locales/). Los archivos overlay de un idioma que Hermes no incluye también hacen que ese idioma se pueda seleccionar. Los cambios se recogen en el siguiente arranque, o en el siguiente cambio de display.language.

Lo que un paquete de idioma no traduce

Todo lo que toca un paquete es texto estático de la interfaz: las líneas de aprobación de la CLI, las respuestas del gateway, los verbos de las herramientas, los consejos, la TUI y la app de escritorio. Las respuestas del agente, la salida de las herramientas, los logs y los nombres de los slash commands no se traducen en absoluto. Si quieres que el propio agente responda en otro idioma, dilo en tu prompt: eso es algo distinto del idioma de la interfaz.

Cuando aun así algo no cuadra

  • Unknown language ... for display.language significa que el paquete no está instalado o no está habilitado (hermes plugins list te lo dirá), o que el id de provides_locales no coincide con el nombre del archivo: un id pl necesita locales/pl.yaml.
  • Que una cadena siga apareciendo en inglés significa que esa clave no está en el catálogo inglés (el validador las lista), o que el conjunto de marcadores difiere del valor inglés.
  • Que un idioma aparezca en la lista mientras la TUI o el escritorio siguen en inglés significa que el paquete no tiene .tui.yaml / .desktop.yaml; esas superficies muestran el inglés más lo que aporte el paquete.

Hay más artículos de configuración y uso en el blog.