fix: pin the English tool texts that translations are written against (#2064)

* fix: pin the English tool texts that translations are written against

en.json leaves `tools` empty — English for the 87 titles and descriptions
comes from the tool definitions at runtime — so those 174 strings lived in no
catalog, and locale_source_baseline.json never hashed them. Editing a
docstring moved the English out from under every locale with nothing going
red, which is the exact failure the baseline exists to prevent for the four
surfaces it already covered.

It has happened twice. ha_dev_manage_settings gained "and the
Tools/Policies/Backups surfaces", ha_report_issue gained "and templates". de,
ru and zh-Hans were written before those edits and still describe the old
behaviour; fr was written after and copied the older wording from a sibling
catalog, which no timestamp comparison can see. Walking the history of the
generated site/src/data/tools.json shows these are the only two English tool
texts that have moved at all since the first catalog landed, so the eight
entries fixed here are the whole backlog rather than a sample of it.

english_sources now hashes the tool texts as their own surface: 174 rendered
strings plus the six docstring renderings that differ from their
FEATURE_GATED_TOOLS stub, because a setting decides which of the two the UI
shows and either can move. Everything else about the baseline is unchanged,
and scripts/update_locale_baseline.py regenerated it.

The eight translations are assembled from vocabulary already in the repo
rather than invented: each locale's own tab labels supply the surface names,
and its existing tool descriptions supply the word for templates and the
sentence form each catalog uses — infinitive in ru, third person in de and
fr, verb-first in zh-Hans. The wording was cross-checked against Home
Assistant's own shipped UI catalogs, which agree on every term except one:
HA calls the backup panel "Резервное копирование" while this catalog says
"Резервные копии". That difference is left alone; it is a noun-versus-gerund
choice a Russian speaker should make, not a drift fix.

* test: hash the summary paragraph, not the displayed first line

The tool descriptions went into the baseline as the settings UI row renders
them — settings.js cuts the docstring at the first newline, then at 120
characters — so any part of a summary that wraps onto a second line stayed
unpinned.

It is one tool of the 87: ha_config_set_helper wraps "(28 types, unified
interface)." off its first line, and zh-Hans is the catalog that translates
that clause. The count could have moved to 30 with the Chinese still saying
28 and nothing going red, which is the failure this baseline exists to
prevent.

Hashing the summary paragraph instead closes it and changes exactly one
recorded hash; the other 86 tools have their whole summary on the first line
already. The copy checks keep comparing against the displayed line, because
a paste is of what was on screen.

Verified by injection: editing the clause to "(30 types, unified interface)."
reddens test_translations_are_checked_against_current_english naming
ha_config_set_helper.description, and the same edit against the previous
commit passes.

* fix: complete the report-issue titles and the displayed-text check

Three catalogs advertised one of that tool's two paths. `ha_report_issue`
is "Report Issue or Feedback" in English, while de, fr and ru named the
problem half only — an incomplete translation rather than drift the
baseline missed, and pinning the title would have frozen it in place.

The paste check compared a translated value against the description's
full first line, while settings.js renders that line cut at 120
characters. For the two descriptions that outrun the cut, ha_get_state at
130 and ha_search at 171, a paste of exactly what was on screen therefore
byte-differed from the text it was pasted from and passed.
`_english_tool_texts` now models both halves of the cut.

Two guards for discriminations the pin relies on and nothing checked: one
fails once no summary paragraph outruns its first physical line, the
other once a feature-gated tool whose stub equals its parsed first line
starts wrapping its summary — the case where the else arm would pin text
the UI never shows.

The `(docstring)` suffix becomes `(parsed)`, which is what it means for
`ha_config_set_yaml.title`: a `title=` kwarg, not a docstring. German
`Bereiche` becomes `Abschnitte`, this catalog's word for a settings
section — `Bereich` is how it renders a Home Assistant area. AGENTS.md
now states that a tool docstring is one of the English strings the
Translations section governs, which was written entirely about catalog
files.

Both guards verified by injection: making `_summary_paragraph` return the
first line reddens the first, and giving ha_read_file a wrapping summary
reddens the second naming that tool. The 120-character cut was verified
the same way — a pasted on-screen ha_get_state description is flagged
with it and passes without it.

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

* test: cut the gated stub to the width its row shows

`_render_stub` feeds a feature-gated tool's stub through the same
`description` field a docstring goes through, so settings.js applies the
same 120-character cut to it. `_english_tool_texts` cut the docstring
branch only, leaving the stub compared at a width the row never renders.
No stub reaches 120 characters today — the longest is 84 — so this moves
no hash and changes no comparison; it stops the two branches from
modelling different things.

The gated-stub guard now measures "the summary wraps" against the
physical first line rather than the cut one, matching its sibling: a wrap
is a property of the docstring, not of the display width.

Both guards re-verified by injection after the change, and the
regenerated baseline is byte-identical.

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: Patch76

AGENTS.md

@@ -759,6 +759,15 @@ each translation was written against, because key parity cannot see a string
 whose meaning changed: #1993 flipped a policy string from ALL-match to
 ANY-match and left the Chinese text asserting the opposite.
 
+**A tool docstring is one of those English strings.** `en.json` ships `tools`
+empty, so the English a `tools` entry translates is read from the tool
+definition in `src/ha_mcp/tools/` — the `title=` kwarg and the summary
+paragraph of the docstring, or the `FEATURE_GATED_TOOLS` stub where a gated
+tool shows one instead. Editing
+that summary therefore moves the English out from under five catalogs and goes
+red here, in the PR that edits it, rather than leaving every locale describing
+the old behaviour.
+
 The Webhook Proxy add-on and its bundled integration stay **English-only by
 decision** — not worth the upkeep. The test records that, so any other new
 catalog directory fails until it is either translated everywhere or listed as

src/ha_mcp/settings_ui/locales/de.json

@@ -550,7 +550,7 @@
     },
     "ha_dev_manage_settings": {
       "title": "Server-Einstellungen verwalten (dev)",
-      "description": "Ändert ha-mcp-Einstellungen direkt im Entwicklermodus."
+      "description": "Verwaltet die ha-mcp-Servereinstellungen und die Abschnitte Tools/Richtlinien/Backups (Entwicklermodus)."
     },
     "ha_get_device": {
       "title": "Gerät abrufen",
@@ -789,8 +789,8 @@
       "description": "Wertet ein Jinja2-Template mit der Home-Assistant-Engine aus."
     },
     "ha_report_issue": {
-      "title": "Problem melden",
-      "description": "Sammelt Diagnosen für einen Fehlerbericht oder Feedback."
+      "title": "Problem melden oder Feedback geben",
+      "description": "Liefert Diagnoseinformationen und Vorlagen für Fehlerberichte oder Feedback."
     },
     "ha_get_zone": {
       "title": "Zonen abrufen",

src/ha_mcp/settings_ui/locales/fr.json

@@ -550,7 +550,7 @@
     },
     "ha_dev_manage_settings": {
       "title": "Gérer les paramètres du serveur (dev)",
-      "description": "Modifie directement les paramètres ha-mcp en mode développeur."
+      "description": "Gère les paramètres du serveur ha-mcp et les sections Outils/Politiques/Sauvegardes (mode développeur)."
     },
     "ha_get_device": {
       "title": "Obtenir l'appareil",
@@ -789,8 +789,8 @@
       "description": "Évalue un modèle Jinja2 avec le moteur Home Assistant."
     },
     "ha_report_issue": {
-      "title": "Signaler un problème",
-      "description": "Recueille les diagnostics pour un rapport de bogue ou un retour d'information."
+      "title": "Signaler un problème ou envoyer un retour",
+      "description": "Fournit des informations de diagnostic et des modèles pour signaler un problème ou envoyer un retour."
     },
     "ha_get_zone": {
       "title": "Obtenir les zones",

src/ha_mcp/settings_ui/locales/ru.json

@@ -479,7 +479,7 @@
     "ha_config_set_dashboard": {"title": "Создать или изменить панель", "description": "Создать новую или обновить существующую панель Home Assistant."},
     "ha_config_set_dashboard_resource": {"title": "Задать ресурс панели", "description": "Создать или обновить ресурс панели из кода или внешнего URL."},
     "ha_dev_manage_server": {"title": "Управлять MCP-сервером (dev)", "description": "Управлять запущенным сервером ha-mcp в режиме разработчика."},
-    "ha_dev_manage_settings": {"title": "Управлять настройками сервера (dev)", "description": "Напрямую изменять настройки ha-mcp в режиме разработчика."},
+    "ha_dev_manage_settings": {"title": "Управлять настройками сервера (dev)", "description": "Управлять настройками сервера ha-mcp и разделами «Инструменты», «Политики безопасности», «Резервные копии» (режим разработчика)."},
     "ha_get_device": {"title": "Получить устройство", "description": "Получить сведения об устройствах, включая Zigbee, Z-Wave и Matter."},
     "ha_remove_device": {"title": "Удалить устройство", "description": "Удалить осиротевшее устройство из реестра Home Assistant."},
     "ha_set_device": {"title": "Изменить устройство", "description": "Обновить имя, зону, метки и другие свойства устройства."},
@@ -539,7 +539,7 @@
     "ha_remove_todo_item": {"title": "Удалить задачу", "description": "Удалить задачу из списка дел Home Assistant."},
     "ha_set_todo_item": {"title": "Создать или изменить задачу", "description": "Создать новую или обновить задачу в списке дел."},
     "ha_eval_template": {"title": "Вычислить шаблон", "description": "Вычислить Jinja2-шаблон с помощью движка Home Assistant."},
-    "ha_report_issue": {"title": "Сообщить о проблеме", "description": "Собрать диагностику для отчёта об ошибке или обратной связи."},
+    "ha_report_issue": {"title": "Сообщить о проблеме или отправить отзыв", "description": "Получить диагностические сведения и шаблоны для отчёта об ошибке или обратной связи."},
     "ha_get_zone": {"title": "Получить зоны", "description": "Показать все географические зоны или сведения об одной зоне."},
     "ha_remove_zone": {"title": "Удалить зону", "description": "Удалить географическую зону Home Assistant."},
     "ha_set_zone": {"title": "Создать или изменить зону", "description": "Создать новую или обновить географическую зону Home Assistant."}

src/ha_mcp/settings_ui/locales/zh-Hans.json

@@ -490,7 +490,7 @@
     },
     "ha_report_issue": {
       "title": "报告问题或反馈",
-      "description": "收集诊断信息以提交问题报告或反馈。"
+      "description": "获取诊断信息和用于提交问题报告或反馈的模板。"
     },
     "ha_config_get_calendar_events": {
       "title": "获取日历事件",
@@ -586,7 +586,7 @@
     },
     "ha_dev_manage_settings": {
       "title": "管理服务器设置（开发者）",
-      "description": "直接管理 ha-mcp 服务器设置（开发者模式）。"
+      "description": "管理 ha-mcp 服务器设置以及“工具”/“工具安全策略”/“备份”页面（开发者模式）。"
     },
     "ha_dev_manage_server": {
       "title": "管理 MCP 服务器（开发者）",

tests/src/unit/locale_source_baseline.json

@@ -182,6 +182,188 @@
     "configuration.verify_ssl.description": "f7da6ad6ed2f93d1",
     "configuration.verify_ssl.name": "b5a42c87a2f2def2"
   },
+  "settings UI tool titles and descriptions": {
+    "ha_bulk_control.description": "387d4ed7116097e3",
+    "ha_bulk_control.title": "190bca20de2f1453",
+    "ha_call_event.description": "12e6ed8f553d1408",
+    "ha_call_event.title": "a387066396d34c39",
+    "ha_call_service.description": "84cb1198577c60b3",
+    "ha_call_service.title": "d4972c7cbdf02589",
+    "ha_config_delete_dashboard.description": "8b317bc0887bad8e",
+    "ha_config_delete_dashboard.title": "d1534bc866402d63",
+    "ha_config_delete_dashboard_resource.description": "6fa48aa44cbbe9ca",
+    "ha_config_delete_dashboard_resource.title": "2a2c433fdd354574",
+    "ha_config_get_automation.description": "9e6dd9ab06735341",
+    "ha_config_get_automation.title": "af4a53803d0f5669",
+    "ha_config_get_calendar_events.description": "d5bd458f93bd002b",
+    "ha_config_get_calendar_events.title": "27ff0c5e3717652d",
+    "ha_config_get_category.description": "d8c1839f95761f49",
+    "ha_config_get_category.title": "bffaa3e7e9ff776d",
+    "ha_config_get_dashboard.description": "ecc5416bf7eecdd0",
+    "ha_config_get_dashboard.title": "6beacbd4a64fb980",
+    "ha_config_get_label.description": "2b477940c613dfac",
+    "ha_config_get_label.title": "2c4087261bc05295",
+    "ha_config_get_scene.description": "1e6ecf8ff63edc16",
+    "ha_config_get_scene.title": "5276861c95b6ff37",
+    "ha_config_get_script.description": "701ded70f7484789",
+    "ha_config_get_script.title": "a60b9c6c5580888c",
+    "ha_config_get_yaml.description": "a013708e3387c037",
+    "ha_config_get_yaml.description (parsed)": "90565082b9a86541",
+    "ha_config_get_yaml.title": "5d28192cf5347f7d",
+    "ha_config_list_dashboard_resources.description": "f94702be3d92b966",
+    "ha_config_list_dashboard_resources.title": "0be6e1e3619b1a55",
+    "ha_config_list_groups.description": "89dc939dccce56f1",
+    "ha_config_list_groups.title": "90f498b0a0bb4d37",
+    "ha_config_list_helpers.description": "c7c393786080f87e",
+    "ha_config_list_helpers.title": "18f4715f708d3c23",
+    "ha_config_remove_automation.description": "85826ea0bf238fe5",
+    "ha_config_remove_automation.title": "117124f5f2e46917",
+    "ha_config_remove_calendar_event.description": "088c357160202397",
+    "ha_config_remove_calendar_event.title": "0fffc60ff9a63800",
+    "ha_config_remove_category.description": "7bc50d16723e7d33",
+    "ha_config_remove_category.title": "b933ad92d2b6118d",
+    "ha_config_remove_group.description": "25a32c92a343b2aa",
+    "ha_config_remove_group.title": "9bd301e8905145c5",
+    "ha_config_remove_label.description": "84f92cff6f6c238b",
+    "ha_config_remove_label.title": "5ef2ed74031c0d53",
+    "ha_config_remove_scene.description": "7ac27f802ff4bf4f",
+    "ha_config_remove_scene.title": "2f3e2b8cf41a8e8c",
+    "ha_config_remove_script.description": "9ff186eebe40f529",
+    "ha_config_remove_script.title": "da272fc8a2d83b1b",
+    "ha_config_set_automation.description": "5a03af00fd40aa70",
+    "ha_config_set_automation.title": "fa4dd9829953e8c3",
+    "ha_config_set_calendar_event.description": "a4175b012ffa3df5",
+    "ha_config_set_calendar_event.title": "b2524c68b2f716b8",
+    "ha_config_set_category.description": "37cfa0cb43c3e038",
+    "ha_config_set_category.title": "3fb808e352f31c67",
+    "ha_config_set_dashboard.description": "fba214864a08f835",
+    "ha_config_set_dashboard.title": "c024fbd91b38a335",
+    "ha_config_set_dashboard_resource.description": "9ada7c5ca0ddc0b2",
+    "ha_config_set_dashboard_resource.title": "af331cb18e4fe3d4",
+    "ha_config_set_group.description": "d2e4e23ad266ff07",
+    "ha_config_set_group.title": "3a0142e4e8142c5e",
+    "ha_config_set_helper.description": "4643b704ddedec21",
+    "ha_config_set_helper.title": "1b7e4b0dd4292fc8",
+    "ha_config_set_label.description": "1275fc40f9541cd7",
+    "ha_config_set_label.title": "6535f8c94a624e30",
+    "ha_config_set_scene.description": "c87735076ad6f62f",
+    "ha_config_set_scene.title": "d8fb041ca0ecfd52",
+    "ha_config_set_script.description": "7f91f69c18551205",
+    "ha_config_set_script.title": "96c8cd0cc316517a",
+    "ha_config_set_yaml.description": "0ff1f8ed1ed3431d",
+    "ha_config_set_yaml.description (parsed)": "3e3b58435e467c8d",
+    "ha_config_set_yaml.title": "7fd880cb59aba371",
+    "ha_config_set_yaml.title (parsed)": "7ba7fd3361c68c99",
+    "ha_delete_file.description": "db17dce1f3af40f6",
+    "ha_delete_file.description (parsed)": "207283b4421b1c91",
+    "ha_delete_file.title": "e1e5fe2043bd3003",
+    "ha_dev_manage_server.description": "67dd412bd6e9cc99",
+    "ha_dev_manage_server.title": "75b8873d3fd57ebd",
+    "ha_dev_manage_settings.description": "bc70a0167bd4664d",
+    "ha_dev_manage_settings.title": "01f5baef30656b27",
+    "ha_eval_template.description": "2c68f7351b2696b6",
+    "ha_eval_template.title": "95c41aa00509c0b1",
+    "ha_get_addon.description": "c5aa23962092e9ed",
+    "ha_get_addon.title": "d480bc41a5bbb41a",
+    "ha_get_automation_traces.description": "c614cf5261c9d4a7",
+    "ha_get_automation_traces.title": "ea9223fa5156dac4",
+    "ha_get_blueprint.description": "e79011ef0adb2d3d",
+    "ha_get_blueprint.title": "8815e4e4a549a441",
+    "ha_get_camera_image.description": "6bcbe41edd6adbcb",
+    "ha_get_camera_image.title": "d37c27c11d587850",
+    "ha_get_dashboard_screenshot.description": "765881d3de2b0f4e",
+    "ha_get_dashboard_screenshot.title": "71406e9773c5091f",
+    "ha_get_device.description": "0862b5101322e6f9",
+    "ha_get_device.title": "2b0de73e67ffd224",
+    "ha_get_entity.description": "2a231fb397767055",
+    "ha_get_entity.title": "b45fa0a3f7336193",
+    "ha_get_entity_exposure.description": "99a81cfc7b96a30f",
+    "ha_get_entity_exposure.title": "8b6e7a2d595c35dc",
+    "ha_get_hacs_info.description": "7081a8cbfee4bf39",
+    "ha_get_hacs_info.title": "90cd63432e3cd07e",
+    "ha_get_history.description": "1c60812a1472f711",
+    "ha_get_history.title": "733f3bced52102ae",
+    "ha_get_integration.description": "6a4ce14b7679d1aa",
+    "ha_get_integration.title": "401f9da0a9245eaa",
+    "ha_get_logs.description": "24879e9b17469232",
+    "ha_get_logs.title": "f8eec17b7014bad2",
+    "ha_get_operation_status.description": "24400f873a53a367",
+    "ha_get_operation_status.title": "da9421d4d0060026",
+    "ha_get_overview.description": "99615a64e3fe6421",
+    "ha_get_overview.title": "29fea93257774ed5",
+    "ha_get_state.description": "1c08533d780f28ad",
+    "ha_get_state.title": "bd66bc891a50e1a2",
+    "ha_get_system_health.description": "2417e2a8735bc896",
+    "ha_get_system_health.title": "974211e1ec579e02",
+    "ha_get_todo.description": "7bef59bc7f4591f3",
+    "ha_get_todo.title": "33c95385f3ec4bad",
+    "ha_get_zone.description": "00a28e389ec1f3a1",
+    "ha_get_zone.title": "4d3f8587f60088f8",
+    "ha_import_blueprint.description": "76840fddcdda38c8",
+    "ha_import_blueprint.title": "06965a3a7777d158",
+    "ha_list_files.description": "a27efdac3a411ad5",
+    "ha_list_files.description (parsed)": "5741646e06bbc9a0",
+    "ha_list_files.title": "3ab99410333f6cfe",
+    "ha_list_floors_areas.description": "1c1039a7f6b0220d",
+    "ha_list_floors_areas.title": "021a324dfe12f1ff",
+    "ha_list_services.description": "6134a8712d232b6a",
+    "ha_list_services.title": "adf19e0a4adc195c",
+    "ha_manage_addon.description": "8eb592f6fcf2743f",
+    "ha_manage_addon.title": "fe41453c7e364189",
+    "ha_manage_backup.description": "710fe0b0a022443b",
+    "ha_manage_backup.title": "27453f0f8a6fe48f",
+    "ha_manage_custom_tool.description": "2d11294916b08404",
+    "ha_manage_custom_tool.description (parsed)": "17e6987cfd85fe0d",
+    "ha_manage_custom_tool.title": "608a0065a471cdef",
+    "ha_manage_energy_prefs.description": "4a35a74f842a9bc1",
+    "ha_manage_energy_prefs.title": "c7972fa209551faa",
+    "ha_manage_hacs.description": "7304221f871c99e7",
+    "ha_manage_hacs.title": "89133d319e5c723e",
+    "ha_manage_pipeline.description": "0dcb88eb7b6a5333",
+    "ha_manage_pipeline.title": "f3d098a7f07d762f",
+    "ha_manage_radio.description": "687614bb176863e5",
+    "ha_manage_radio.title": "d3652e3015043e14",
+    "ha_manage_theme.description": "dc3486b249ee7541",
+    "ha_manage_theme.title": "bbd7cc9b1ccae800",
+    "ha_manage_updates.description": "2817b1e7b6351e97",
+    "ha_manage_updates.title": "67e75eabd230e0a9",
+    "ha_read_file.description": "ba58369170e20ea9",
+    "ha_read_file.title": "fb9b615c6b482637",
+    "ha_reload_core.description": "b0d5fdbcae77df01",
+    "ha_reload_core.title": "ba94c7af815af3e1",
+    "ha_remove_area_or_floor.description": "fa94b6736ba94fe5",
+    "ha_remove_area_or_floor.title": "04ddbf264fa33fe7",
+    "ha_remove_device.description": "238310aca64b2a66",
+    "ha_remove_device.title": "ff1be38ef77e59ee",
+    "ha_remove_entity.description": "527a3c6b48da227f",
+    "ha_remove_entity.title": "80737ebedb1b140a",
+    "ha_remove_helpers_integrations.description": "5fc1934068cd4ade",
+    "ha_remove_helpers_integrations.title": "71083f9458c3fa4c",
+    "ha_remove_todo_item.description": "6f6a491ef57afa55",
+    "ha_remove_todo_item.title": "933e6852dfe873e1",
+    "ha_remove_zone.description": "2db5dff5b5551e3b",
+    "ha_remove_zone.title": "589352bbb6c2571b",
+    "ha_report_issue.description": "1dbf25d2c2446aab",
+    "ha_report_issue.title": "57f1a5769847a69b",
+    "ha_restart.description": "c69f717cedf3639f",
+    "ha_restart.title": "891201143db59eb4",
+    "ha_search.description": "c159533226ed4970",
+    "ha_search.title": "49c266baaaa70981",
+    "ha_set_area_or_floor.description": "7bd888c56f1efd77",
+    "ha_set_area_or_floor.title": "d032f7c5cee00c4f",
+    "ha_set_device.description": "b1f06dedc0bd7f96",
+    "ha_set_device.title": "ad1a0c3ff512be01",
+    "ha_set_entity.description": "8b8bf5ab3191abbf",
+    "ha_set_entity.title": "80157db7ff1b868d",
+    "ha_set_integration.description": "ac5ee695ffeef5ce",
+    "ha_set_integration.title": "a86d452343e3bb4f",
+    "ha_set_todo_item.description": "f2d74959003ae95c",
+    "ha_set_todo_item.title": "0510f2eaaf39e38f",
+    "ha_set_zone.description": "289a61496ac6cfbb",
+    "ha_set_zone.title": "c8801b98d9cbb605",
+    "ha_write_file.description": "daa1c68dc53febd4",
+    "ha_write_file.title": "d78cd87c20261047"
+  },
   "src/ha_mcp/settings_ui/locales": {
     "messages.accessibility.colors.accent": "a5c6fb18c9af89b2",
     "messages.accessibility.colors.background": "ea2b8a878841df59",