Pacotes de idioma do Hermes: faça o CLI, o gateway e o Desktop falarem a sua língua

Metade do seu time lê um terminal em inglês e a outra metade não, então toda semana alguns prompts são mal interpretados. Um deles era uma linha de aprovação longa em inglês antes de um comando perigoso — lida na diagonal, respondida com a tecla errada. Outro engenheiro tentou mudar a interface para o próprio idioma com hermes config set display.language pl e recebeu de volta ✗ Unknown language 'pl'. O Hermes vem com 17 idiomas de interface, e polonês, coreano ou português do Brasil não estão entre eles, então nenhum valor de configuração vai fazer aparecer um. Um pacote de idioma resolve isso: um plugin feito de arquivos YAML que troca o texto estático da interface — os prompts de aprovação do CLI, as respostas do gateway de mensagens, os verbos das ferramentas, as dicas, a interface do hermes --tui e o app Desktop — e nada disso precisa de código Python.

O Hermes vem com 17 idiomas de interface, mas a lista é plugável

O conjunto embutido tem 17 idiomas, escolhidos com display.language. Os catálogos deles ficam em locales/ como af, ar, de, en, es, fr, ga, hu, it, ja, ko, pt, ru, tr, uk, zh-hant e zh.

hermes config set display.language aceita qualquer id que uma das camadas consiga fornecer. Um id que ninguém reconhece é recusado na hora, com os idiomas disponíveis impressos em seguida:

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

A mensagem de erro já aponta as duas saídas: instalar um plugin de pacote de idioma ou colocar um arquivo overlay seu. Mais uma coisa que surpreende quem está depurando “mudei e nada mudou” — o HERMES_LANGUAGE no .env ainda tem precedência sobre o display.language.

Tudo isso se apoia no trabalho da v0.22.0: o PR #126296 passou todas as strings voltadas ao usuário no CLI, no gateway de mensagens, na TUI e no Desktop por um único catálogo de tradução, e é isso que dá a um pacote um ponto onde se conectar. A página de release da v0.22.0 cobre a release em si.

Instale um pacote em dois comandos

Um pacote de idioma é instalado como qualquer outro plugin. Se o Hermes ainda não está instalado, comece pelo guia de instalação. Depois:

hermes plugins install hermes-lang-pt-br   # um nome de catálogo, ou uma URL de repositório
hermes config set display.language pt-br

Dois pacotes foram incorporados ao catálogo oficial em 14 de outubro de 2026: hermes-lang-ko para coreano e hermes-lang-pt-br para português do Brasil. A documentação mostra o caminho com hermes plugins install https://github.com/teknium1/hermes-lang-pl caso você queira ver como um pacote se parece na prática. A descoberta e a instalação funcionam exatamente como em qualquer outro plugin, o que o guia do catálogo de plugins explica de ponta a ponta.

Reinicie qualquer gateway ou TUI em execução depois de instalar, para que ele recarregue o pacote. Os seletores de idioma da TUI e do Desktop listam os idiomas embutidos, os seus idiomas de overlay e todos os pacotes instalados pelo nome nativo — o endônimo, como Polski — e não pelo código.

De onde uma string da interface realmente vem

Quando o Hermes procura uma string, ele percorre estas camadas, de cima para baixo, e fica com a primeira que encontrar:

  1. Pacotes de idioma de plugins — qualquer plugin instalado que declare provides_locales (se dois pacotes cobrirem a mesma chave, vence o que foi carregado por último)
  2. O seu overlay — <HERMES_HOME>/locales/<lang>.yaml, por profile, então um profile nomeado usa ~/.hermes/profiles/<name>/locales/
  3. Embutido — os catálogos locales/<lang>.yaml que acompanham o Hermes

Se nenhuma das três tiver a chave, as mesmas três camadas são testadas para o inglês e só então a chave crua aparece na tela. Toda camada pode ser parcial: um pacote só precisa das chaves que quer mudar, não de uma cópia completa do catálogo.

Escreva um pacote sem escrever Python

Nada disso exige código Python. Um pacote mínimo é assim:

hermes-lang-pl/
  plugin.yaml
  locales/
    pl.yaml            # core: approval.*, gateway.*, cli.*, display.*, slash.*, tips.*, ...
    pl.tui.yaml        # opcional: strings do hermes --tui
    pl.desktop.yaml    # opcional: strings do app Desktop

O manifesto declara qual idioma o pacote fornece:

name: hermes-lang-pl
version: 1.0.0
description: Polish language pack for Hermes
provides_locales:
  - id: pl            # tag minúsculo no estilo BCP-47: pl, pt-br, zh-hant
    endonym: Polski   # mostrado nos seletores de idioma
    rtl: false        # true para escritas da direita para a esquerda; inverte o layout do Desktop

As entradas de provides_locales também podem ser ids simples (- pl), e aí o endônimo assume o id por padrão. Assim que esse bloco existe, o loader de plugins registra automaticamente todos os locales/<lang>[.tui|.desktop].yaml do pacote — não sobra nada para ligar na mão.

Plugins que já têm código Python podem, em vez disso, registrar os próprios catálogos: ctx.register_locale("pl", path_or_mapping, endonym="Polski", rtl=False, surface="core"), em que surface é core, tui ou desktop, ou ctx.register_locale_dir(dir) para registrar uma pasta inteira de uma vez. O registro é desfeito quando o plugin é descarregado, e ele nunca altera o display.language.

Valide o pacote e fique atento aos placeholders

Rode o validador antes de publicar:

hermes plugins validate ./hermes-lang-pl

Ele verifica se cada id declarado tem um locales/<id>.yaml correspondente, se cada arquivo é parseável e se todo valor é texto — número, lista, true/false ou valor vazio é erro, não aviso. Chaves que não existem no catálogo em inglês daquela surface só geram um aviso com a lista anexada: são inofensivas, mas não fazem nada. Enquanto escreve, evite palavras reservadas do YAML como chaves — on, off, yes e no.

Os placeholders são a segunda armadilha. As strings de core (do lado Python) usam placeholders nomeados: se o valor em inglês diz {count}, a tradução precisa manter {count}. Se você esquecer ou escrever errado, aquela chave cai silenciosamente de volta na string não traduzida. Entradas da TUI e do Desktop cujo valor em inglês recebe argumentos usam placeholders posicionais, {0} e {1}.

Sobrescreva uma linha sem montar um pacote

Para mudar uma ou duas frases, pule o plugin e coloque um arquivo parcial no seu Hermes home:

# ~/.hermes/locales/en.yaml — apenas as chaves que você quer mudar
approval:
  denied: "      ✗ Nope."

O overlay vale só para aquele profile (um profile nomeado lê ~/.hermes/profiles/<name>/locales/). Arquivos de overlay para um idioma que o Hermes não traz de fábrica tornam esse idioma selecionável também. As edições entram em vigor no próximo início ou na próxima mudança de display.language.

O que um pacote de idioma não traduz

Tudo o que um pacote toca é texto estático da interface: prompts de aprovação do CLI, respostas do gateway, verbos das ferramentas, dicas, a TUI e o app Desktop. Respostas do agente, saída das ferramentas, logs e os nomes dos comandos slash não são traduzidos de forma alguma. Se você quer que o próprio agente responda em outro idioma, diga isso no seu prompt — é uma coisa separada do idioma da interface.

Quando ainda parece errado

  • Unknown language ... for display.language significa que o pacote não está instalado nem habilitado (hermes plugins list vai dizer), ou que o id em provides_locales não bate com o nome do arquivo — um id pl precisa de locales/pl.yaml.
  • Uma string que continua aparecendo em inglês significa que aquela chave não está no catálogo em inglês (o validador lista essas), ou que o conjunto de placeholders difere do valor em inglês.
  • Um idioma que aparece na lista enquanto a TUI ou o Desktop continuam em inglês significa que o pacote não tem .tui.yaml / .desktop.yaml; essas surfaces renderizam inglês mais o que o pacote fornecer.

Mais textos sobre configuração e uso estão no blog.