From c4b287ba539de06f79b867319568a4aa8c02a5ac Mon Sep 17 00:00:00 2001
From: Oleksii Lisikh <oleksii.lisikh@gmail.com>
Date: Tue, 5 May 2026 17:44:43 +0200
Subject: [PATCH] feat(i18n): add Ukrainian locale

---
 agent/i18n.py                            |  5 +++--
 hermes_cli/config.py                     |  2 +-
 locales/en.yaml                          |  2 +-
 locales/uk.yaml                          | 24 ++++++++++++++++++++++++
 tests/agent/test_i18n.py                 |  4 ++++
 website/docs/user-guide/configuration.md |  4 ++--
 6 files changed, 35 insertions(+), 6 deletions(-)
 create mode 100644 locales/uk.yaml

diff --git a/agent/i18n.py b/agent/i18n.py
index c700491522..fff0577cc1 100644
--- a/agent/i18n.py
+++ b/agent/i18n.py
@@ -25,7 +25,7 @@ Language resolution order:
     3. ``display.language`` from config.yaml
     4. ``"en"`` (baseline)
 
-Supported languages: en, zh, ja, de, es, fr.  Unknown values fall back to en.
+Supported languages: en, zh, ja, de, es, fr, uk.  Unknown values fall back to en.
 """
 
 from __future__ import annotations
@@ -39,7 +39,7 @@ from typing import Any
 
 logger = logging.getLogger(__name__)
 
-SUPPORTED_LANGUAGES: tuple[str, ...] = ("en", "zh", "ja", "de", "es", "fr")
+SUPPORTED_LANGUAGES: tuple[str, ...] = ("en", "zh", "ja", "de", "es", "fr", "uk")
 DEFAULT_LANGUAGE = "en"
 
 # Accept a few natural aliases so users who type "chinese" / "zh-CN" / "jp"
@@ -51,6 +51,7 @@ _LANGUAGE_ALIASES: dict[str, str] = {
     "german": "de", "deutsch": "de", "de-de": "de",
     "spanish": "es", "español": "es", "espanol": "es", "es-es": "es", "es-mx": "es",
     "french": "fr", "français": "fr", "france": "fr", "fr-fr": "fr", "fr-be": "fr", "fr-ca": "fr", "fr-ch": "fr",
+    "ukrainian": "uk", "ukrainisch": "uk", "українська": "uk", "uk-ua": "uk", "ua": "uk",
 }
 
 _catalog_cache: dict[str, dict[str, str]] = {}
diff --git a/hermes_cli/config.py b/hermes_cli/config.py
index 1ac9881d89..1d9f88e593 100644
--- a/hermes_cli/config.py
+++ b/hermes_cli/config.py
@@ -784,7 +784,7 @@ DEFAULT_CONFIG = {
         # UI language for static user-facing messages (approval prompts, a
         # handful of gateway slash-command replies).  Does NOT affect agent
         # responses, log lines, tool outputs, or slash-command descriptions.
-        # Supported: en, zh, ja, de, es.  Unknown values fall back to en.
+        # Supported: en, zh, ja, de, es, fr, uk.  Unknown values fall back to en.
         "language": "en",
         # TUI busy indicator style: kaomoji (default), emoji, unicode (braille
         # spinner), or ascii.  Live-swappable via `/indicator <style>`.
diff --git a/locales/en.yaml b/locales/en.yaml
index 10c522dd25..e84af4d031 100644
--- a/locales/en.yaml
+++ b/locales/en.yaml
@@ -7,7 +7,7 @@
 #
 # Keys are dotted paths; nesting below is purely for readability.  Values may
 # contain {placeholder} tokens for str.format substitution.  When adding a
-# new key, add it to EVERY locale file (en/zh/ja/de/es/fr) in the same commit --
+# new key, add it to EVERY locale file (en/zh/ja/de/es/fr/uk) in the same commit --
 # tests/agent/test_i18n.py asserts catalog parity.
 
 approval:
diff --git a/locales/uk.yaml b/locales/uk.yaml
new file mode 100644
index 0000000000..fce0dc0a6f
--- /dev/null
+++ b/locales/uk.yaml
@@ -0,0 +1,24 @@
+# Каталог статичних повідомлень Hermes -- Українська
+# See locales/en.yaml for the source of truth; keep keys in sync.
+
+approval:
+  dangerous_header: "⚠️  НЕБЕЗПЕЧНА КОМАНДА: {description}"
+  choose_long:     "      [o]один раз  |  [s]сеанс  |  [a]завжди  |  [d]відхилити"
+  choose_short:    "      [o]один раз  |  [s]сеанс  |  [d]відхилити"
+  prompt_long:     "      Вибір [o/s/a/D]: "
+  prompt_short:    "      Вибір [o/s/D]: "
+  timeout:         "      ⏱ Час очікування вичерпано — команду відхилено"
+  allowed_once:    "      ✓ Дозволено один раз"
+  allowed_session: "      ✓ Дозволено для цього сеансу"
+  allowed_always:  "      ✓ Додано до постійного списку дозволених команд"
+  denied:          "      ✗ Відхилено"
+  cancelled:       "      ✗ Скасовано"
+  blocklist_message: "Ця команда є в безумовному списку блокування, її не можна схвалити."
+
+gateway:
+  approval_expired: "⚠️ Час схвалення минув (агент більше не очікує). Попросіть агента спробувати ще раз."
+  draining:         "⏳ Очікування завершення {count} активних агент(ів) перед перезапуском..."
+  goal_cleared:     "✓ Ціль очищено."
+  no_active_goal:   "Немає активної цілі."
+  config_read_failed: "⚠️ Не вдалося прочитати config.yaml: {error}"
+  config_save_failed: "⚠️ Не вдалося зберегти конфігурацію: {error}"
diff --git a/tests/agent/test_i18n.py b/tests/agent/test_i18n.py
index 1f00e97d45..f233a27358 100644
--- a/tests/agent/test_i18n.py
+++ b/tests/agent/test_i18n.py
@@ -89,6 +89,9 @@ def test_normalize_lang_accepts_aliases():
     assert i18n._normalize_lang("Deutsch") == "de"
     assert i18n._normalize_lang("español") == "es"
     assert i18n._normalize_lang("jp") == "ja"
+    assert i18n._normalize_lang("Ukrainian") == "uk"
+    assert i18n._normalize_lang("uk-UA") == "uk"
+    assert i18n._normalize_lang("ua") == "uk"
 
 
 def test_normalize_lang_unknown_falls_back():
@@ -126,6 +129,7 @@ def test_default_when_nothing_set(monkeypatch):
 def test_t_explicit_lang():
     assert i18n.t("approval.denied", lang="en").endswith("Denied")
     assert i18n.t("approval.denied", lang="zh").endswith("已拒绝")
+    assert i18n.t("approval.denied", lang="uk").endswith("Відхилено")
 
 
 def test_t_formats_placeholders():
diff --git a/website/docs/user-guide/configuration.md b/website/docs/user-guide/configuration.md
index b370c628e2..246c0ff49b 100644
--- a/website/docs/user-guide/configuration.md
+++ b/website/docs/user-guide/configuration.md
@@ -1167,14 +1167,14 @@ display:
   show_cost: false        # Show estimated $ cost in the CLI status bar
   tool_preview_length: 0  # Max chars for tool call previews (0 = no limit, show full paths/commands)
   runtime_metadata_footer: false  # Gateway: append a runtime-context footer to final replies
-  language: en            # UI language for static messages (approval prompts, some gateway replies). en | zh | ja | de | es
+  language: en            # UI language for static messages (approval prompts, some gateway replies). en | zh | ja | de | es | fr | uk
 ```
 
 ### UI language for static messages
 
 The `display.language` setting translates a small set of static user-facing messages — the CLI approval prompt, a handful of gateway slash-command replies (e.g. restart-drain notices, "approval expired", "goal cleared"). It does **not** translate agent responses, log lines, tool output, error tracebacks, or slash-command descriptions — those stay in English. If you want the agent itself to reply in another language, just tell it in your prompt or system message.
 
-Supported values: `en` (default), `zh` (Simplified Chinese), `ja` (Japanese), `de` (German), `es` (Spanish). Unknown values fall back to English.
+Supported values: `en` (default), `zh` (Simplified Chinese), `ja` (Japanese), `de` (German), `es` (Spanish), `fr` (French), `uk` (Ukrainian). Unknown values fall back to English.
 
 You can also set this per-session with the `HERMES_LANGUAGE` env var, which overrides the config value.