Hermes Sprachpakete: so sprechen CLI, Gateway und Desktop Ihre Sprache

Die Hälfte Ihres Teams liest ein Terminal auf Englisch, die andere Hälfte nicht – also werden jede Woche ein paar Prompts falsch gelesen. Einer davon war eine lange englische Approval-Zeile vor einem gefährlichen Befehl: überflogen und dann mit der falschen Taste beantwortet. Eine andere Entwicklerin wollte die Oberfläche mit hermes config set display.language pl auf ihre eigene Sprache umstellen und bekam ✗ Unknown language 'pl' zurück. Hermes bringt 17 UI-Sprachen mit, und Polnisch, Koreanisch oder brasilianisches Portugiesisch sind nicht dabei – kein Config-Wert kann sie herbeizaubern. Ein Sprachpaket löst das: ein Plugin aus YAML-Dateien, das die statischen UI-Texte der CLI-Approval-Prompts, der Antworten des Messaging-Gateways, der Tool-Verben, der Tipps, der hermes --tui-Oberfläche und der Desktop-App austauscht – und dafür braucht es keine Zeile Python-Code.

Hermes bringt 17 UI-Sprachen mit, aber die Liste ist erweiterbar

Mitgeliefert werden 17 Sprachen, ausgewählt über display.language. Ihre Kataloge liegen in locales/ als af, ar, de, en, es, fr, ga, hu, it, ja, ko, pt, ru, tr, uk, zh-hant und zh.

hermes config set display.language akzeptiert jede id, die eine der Ebenen liefern kann. Eine id, die niemand kennt, wird rundheraus abgelehnt – mit ausgeschriebener Liste der verfügbaren Sprachen:

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

Die Fehlermeldung nennt bereits beide Auswege: ein Sprachpaket-Plugin installieren oder eine eigene Overlay-Datei ablegen. Und noch etwas, das alle überrascht, die gerade „Ich habe es geändert, warum ist nichts anders“ debuggen – HERMES_LANGUAGE in der .env überschreibt weiterhin display.language.

All das beruht auf der Arbeit an v0.22.0: PR #126296 hat jeden benutzersichtbaren String in der CLI, im Messaging-Gateway, in der TUI und im Desktop durch einen einzigen Übersetzungskatalog geleitet – genau das gibt einem Paket den Punkt zum Einhaken. Die Release-Seite zu v0.22.0 behandelt das Release selbst.

Ein Paket in zwei Befehlen installieren

Ein Sprachpaket installiert sich wie jedes andere Plugin. Falls Hermes noch nicht installiert ist, beginnen Sie mit der Installationsanleitung. Dann:

hermes plugins install hermes-lang-pt-br   # ein Katalogname oder eine Repo-URL
hermes config set display.language pt-br

Am 14. Oktober 2026 sind zwei Pakete in den offiziellen Katalog eingeflossen: hermes-lang-ko für Koreanisch und hermes-lang-pt-br für brasilianisches Portugiesisch. Die Doku führt durch hermes plugins install https://github.com/teknium1/hermes-lang-pl, wenn Sie sehen wollen, wie ein Paket in freier Wildbahn aussieht. Erkennung und Installation laufen genau wie bei jedem anderen Plugin – was der Plugin-Katalog-Leitfaden von Anfang bis Ende erklärt.

Starten Sie nach der Installation ein laufendes Gateway oder eine laufende TUI neu, damit das Paket erneut geladen wird. Die Sprachumschalter von TUI und Desktop listen mitgelieferte Sprachen, Ihre eigenen Overlay-Sprachen und jedes installierte Paket unter ihrem einheimischen Namen auf – dem Endonym, etwa Polski – und nicht unter ihrem Code.

Wo ein UI-String tatsächlich herkommt

Wenn Hermes einen String nachschlägt, geht es diese Ebenen von oben durch und nimmt den ersten Treffer:

  1. Plugin-Sprachpakete – jedes installierte Plugin, das provides_locales deklariert (decken zwei Pakete denselben Key ab, gewinnt das zuletzt geladene)
  2. Ihr Overlay – <HERMES_HOME>/locales/<lang>.yaml, pro Profil, ein benanntes Profil liest also ~/.hermes/profiles/<name>/locales/
  3. Mitgeliefert – die mit Hermes ausgelieferten Kataloge locales/<lang>.yaml

Hat keine dieser drei Ebenen den Key, werden dieselben drei Ebenen für Englisch durchprobiert – erst dann erscheint der rohe Key auf dem Bildschirm. Jede Ebene darf unvollständig sein: Ein Paket braucht nur die Keys, die es ändern will, keine vollständige Kopie des Katalogs.

Ein Paket schreiben, ohne Python zu schreiben

Nichts davon braucht Python-Code. Ein minimales Paket sieht so aus:

hermes-lang-pl/
  plugin.yaml
  locales/
    pl.yaml            # Kern: approval.*, gateway.*, cli.*, display.*, slash.*, tips.*, ...
    pl.tui.yaml        # optional: Strings für hermes --tui
    pl.desktop.yaml    # optional: Strings der Desktop-App

Das Manifest deklariert, welche Sprache das Paket mitbringt:

name: hermes-lang-pl
version: 1.0.0
description: Polish language pack for Hermes
provides_locales:
  - id: pl            # BCP-47-artiges Tag in Kleinschreibung: pl, pt-br, zh-hant
    endonym: Polski   # wird in den Sprachumschaltern angezeigt
    rtl: false        # true für Rechts-nach-links-Schriften; spiegelt das Desktop-Layout

provides_locales-Einträge dürfen auch einfache ids sein (- pl); das Endonym entspricht dann der id. Sobald dieser Block existiert, registriert der Plugin-Loader jede locales/<lang>[.tui|.desktop].yaml im Paket automatisch – es bleibt nichts zu verdrahten.

Plugins, die bereits Python-Code haben, können stattdessen eigene Kataloge registrieren: ctx.register_locale("pl", path_or_mapping, endonym="Polski", rtl=False, surface="core"), wobei surface für core, tui oder desktop steht, oder ctx.register_locale_dir(dir), um einen ganzen Ordner auf einmal zu registrieren. Die Registrierung wird beim Entladen des Plugins rückgängig gemacht, und display.language ändert sie nie.

Validieren – und auf die Platzhalter achten

Führen Sie den Validator aus, bevor Sie ausliefern:

hermes plugins validate ./hermes-lang-pl

Er prüft, dass jede deklarierte id eine passende locales/<id>.yaml hat, dass jede Datei geparst werden kann und dass jeder Wert Text ist – eine Zahl, eine Liste, true/false oder ein leerer Wert ist ein Fehler, keine Warnung. Keys, die es im englischen Katalog für diese Oberfläche nicht gibt, erzeugen nur eine Warnung samt Liste: Sie sind harmlos, bewirken aber nichts. Und halten Sie beim Schreiben YAML-reservierte Wörter als Keys fern – on, off, yes und no.

Platzhalter sind die zweite Falle. Core-Strings (Python-Seite) verwenden benannte Platzhalter: Steht im englischen Wert {count}, muss die Übersetzung {count} beibehalten. Fällt er weg oder ist er falsch geschrieben, greift dieser Key still auf den unübersetzten String zurück. TUI- und Desktop-Einträge, deren englischer Wert Argumente entgegennimmt, nutzen dagegen positionale Platzhalter, {0} und {1}.

Eine Zeile überschreiben, ohne ein Paket zu bauen

Um ein oder zwei Sätze zu ändern, überspringen Sie das Plugin komplett und legen eine Teil-Datei in Ihrem Hermes-Home ab:

# ~/.hermes/locales/en.yaml — nur die Keys, die Sie ändern wollen
approval:
  denied: "      ✗ Nope."

Das Overlay gilt nur für dieses Profil (ein benanntes Profil liest ~/.hermes/profiles/<name>/locales/). Overlay-Dateien für eine Sprache, die Hermes nicht mitbringt, machen diese Sprache ebenfalls auswählbar. Änderungen greifen beim nächsten Start oder beim nächsten Wechsel von display.language.

Was ein Sprachpaket nicht übersetzt

Alles, was ein Paket anfasst, ist statischer UI-Text: CLI-Approval-Prompts, Gateway-Antworten, Tool-Verben, Tipps, die TUI und die Desktop-App. Agent-Antworten, Tool-Ausgaben, Logs und die Namen von Slash-Befehlen werden überhaupt nicht übersetzt. Soll der Agent selbst in einer anderen Sprache antworten, sagen Sie es in Ihrem Prompt – das ist etwas anderes als die Sprache der Oberfläche.

Wenn es trotzdem falsch aussieht

  • Unknown language ... for display.language heißt: Das Paket ist nicht installiert oder nicht aktiviert (hermes plugins list verrät es Ihnen), oder die id in provides_locales passt nicht zum Dateinamen – eine id pl braucht eine locales/pl.yaml.
  • Ein String, der weiterhin auf Englisch erscheint, heißt: Dieser Key fehlt im englischen Katalog (der Validator listet sie auf), oder die Platzhalter-Menge weicht vom englischen Wert ab.
  • Eine Sprache, die in der Liste auftaucht, während TUI oder Desktop englisch bleiben, heißt: Dem Paket fehlen die .tui.yaml / .desktop.yaml; diese Oberflächen rendern Englisch plus das, was das Paket liefert.

Weitere Artikel zu Konfiguration und Nutzung finden Sie im Blog.