feat: add complete Klingon localization

[kingpanther13]

What does this PR do?

Adds a complete Klingon (tlh) localization across all four required surfaces:

• Settings UI: 419 messages, 29 renderable tool groups, and 87 tool title/description pairs
• Home Assistant custom component: all 93 scalar translation leaves, including the 16 localized options-form strings introduced by feat: add the Spanish (es) locale across all four translated surfaces #2055
• Stable add-on: all 32 scalar translation leaves
• Development add-on: all 52 scalar translation leaves

That is 799 translated values across the four catalogs. The language selector displays tlhIngan Hol (Klingon). Every catalog section is populated; no HA/MCP prose is deliberately deferred to an English fallback. Product names, protocol names, paths, environment variables, tool identifiers, and other technical tokens remain unchanged where translating them would be incorrect.

This branch is rebased onto the merged #2055 localization contract. The surrounding prose is Klingon, while references that must match fixed UI controls remain exact: Local network is the visible bind-host option and HA-MCP File & YAML Tools is the created config-entry title. The Home Assistant action label corresponding to “Add entry” remains translated, matching the established locales.

Translation provenance and QA

This went substantially beyond generating prose and checking that the JSON parsed:

• Surveyed existing Klingon language packs and selected the strongest sources by domain. The primary web-UI translation memory is Lieven L. Litaer's human-authored Foswiki catalog, whose source commit reports 1,205/1,232 strings (97.8%). Because it is GPL-2.0-or-later, it was used for terminology and short matching UI phrases rather than copied wholesale.
• Reused the manually maintained Blockly Klingon terminology for technical UI concepts. Blockly's documentation explicitly warns against generic machine translation for Klingon.
• Reused the Python Humanize Klingon catalog for time units and relative-time vocabulary.
• Audited core vocabulary against current source-tagged boQwI' canonical data and KLI confirmed vocabulary. The audit used the 2026.07.24a boQwI' data snapshot.
• Surveyed Apache OpenOffice's much larger-looking Klingon tree and rejected it as the primary source after measuring only about 1,137/27,584 non-empty UI entries (roughly 4.12%) and no translated Help corpus.
• Built a source-attested UI glossary for settings, save, restore, update, confirm, remove/delete, enable/disable, server, network, file, software, trust, security, access, search, defaults, and time units, then normalized all four catalogs to it.
• Ran an explicit false-friend audit. This caught and removed superficially plausible but canonically wrong choices such as words meaning “leak” for automatic generation, “lame” for sensitive, “condemn” for execute, “sparkle” for trust, “fuel” for age, and “federation” for confirmation.
• Removed every bare verb-root -ghach nominalization flagged by the Klingon Corpus grammar rules, corrected noun plural classes, and reviewed formal lu-/tI- verb-prefix agreement for plural objects.
• Ran the Klingon prose for all 799 final values through the Klingonia proofreader and iterated until it returned zero non-UNKNOWN grammar diagnostics. The sole sentence grammatically adapted after feat: add the Spanish (es) locale across all four translated surfaces #2055's final merge was rechecked separately with the same result. Remaining UNKNOWN notices are deliberate product, protocol, path, code, placeholder, and identifier tokens.
• Rechecked key, type, placeholder, inline markup, panel-link, URL, schema, and stable/development shared-string parity after the grammar corrections.
• Aligned the settings catalog with feat: add the Spanish (es) locale across all four translated surfaces #2055's catalog-to-runtime checks: it contains exactly the 29 headings that can become a tool's primary group and all 87 tools, with translated titles and descriptions checked against both feature-gated English stubs and parsed docstrings.
• Applied the merged untranslated-text ceilings: 5% for settings messages, tool text, and both add-ons; 15% for the component. The Klingon catalogs are complete rather than relying on those ceilings.
• Updated the documented shipped-locale list so tlh is covered by the merged documentation-parity assertion alongside es.

Type of change

• 🐛 Bug fix
• ✨ New feature
• 📚 Documentation
• 🔧 Maintenance/refactor
• 🧪 Tests only
• 💥 Breaking change

Testing

• I have tested these changes with a LLM agent
• All automated tests pass (uv run pytest)
• Code follows style guidelines (uv run ruff check)

Current post-rebase local validation:

• git diff --check
• JSON/YAML parsing plus settings-catalog loader validation
• Exact assertions from the merged locale-parity contract executed against the source catalogs: passed (93 component leaves, 29 renderable groups, 87 tools, four-surface parity, placeholders, English-copy ceilings, fixed literals, baseline, and AGENTS documentation)
• pytest -q tests/addon/test_addon_structure.py (14 passed)
• Klingon picker assertions: tlhIngan Hol (Klingon), ltr, and actions.save = pol
• ruff check tests/src/unit/test_settings_ui_i18n.py
• ruff format --check tests/src/unit/test_settings_ui_i18n.py
• Klingonia proofreader workflow: 799 localized values, zero non-UNKNOWN grammar diagnostics
• GitHub Actions on rebased head ceb76d58: 31 successful checks, 2 expected skips, 0 failures

The bare Termux global Python environment does not contain the project's Starlette or FastMCP runtime dependencies, so the focused settings-UI pytest file and normal pytest collection of test_locale_parity.py are left to GitHub CI. No dependencies were installed solely to reproduce CI locally.

Checklist

• I have updated documentation if needed

[ghhamcp]

@codex review — apply the review criteria in .gemini/styleguide.md in addition to AGENTS.md guidance

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Already looking forward to the next diff.

Reviewed commit: 6d88f4b907

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[kingpanther13]

Implementation Summary

• Added the tlh / tlhIngan Hol locale to all four required localization surfaces plus a settings-UI registration test.
• Used only 10 complete, context-matched UI translations from Lieven L. Litaer's established Foswiki catalog; no machine translation or newly composed Klingon prose remains.
• Preserved English fallback for HA/MCP-specific text. The partial settings catalog omits untranslated keys so it inherits current runtime copy; component and add-on catalogs retain complete English passthroughs where schema parity requires them.
• Reverted an otherwise attested Update translation because its source context was an action button, not Home Assistant's noun-like update entity name.
• Fixed a pre-PR audit issue where copied tool metadata would have overridden the live fallback with truncated snapshots.
• All GitHub Actions checks are green, including Ruff, Mypy, unit tests, builds, CodeQL, E2E, and all HAOS lanes. Automated review found no major issues.
• The PR remains draft for review and completion by a qualified Klingon translator.

[kingpanther13]

Lol wow I tried codex on this one just to see what it would produce. It's so lazy it decided to defer to a "qualified translator." Incredible.

[kingpanther13]

Superseding implementation summary

This comment supersedes the earlier partial-locale implementation summary. The locale is now complete; no HA/MCP translation work is deferred.

Coverage

Surface	Complete coverage
Settings UI messages	419
Settings UI renderable tool groups	29
Settings UI tools	87 title/description pairs
Custom-component leaves	77
Stable add-on leaves	32
Development add-on leaves	52

The selector label is tlhIngan Hol (Klingon).

Translation provenance

• Foswiki's 97.8% human-authored Klingon web-UI catalog was used as the primary terminology/translation-memory source.
• Google's manually maintained Blockly Klingon pack supplied technical UI terminology.
• Python Humanize supplied reviewed time and duration vocabulary.
• Current source-tagged boQwI' data and KLI-confirmed vocabulary were used as the lexical authority.
• Sparse or unreliable packs and generic Klingon machine translation were rejected rather than blended into the locale.

Grammar and semantic audit

• Removed every identified canonical false friend, including incorrect words for automatic generation, sensitive tools, code execution, trust, object age, and confirmation.
• Removed all bare verb-root -ghach nominalizations.
• Corrected object/abstract plural classes and formal lu-/tI- agreement for plural objects.
• Kept destructive meanings distinct: remove, discard stored content, and destroy use different attested verbs.
• Submitted all 788 localized values to the Klingonia proofreader; the final catalogs have zero non-UNKNOWN grammar diagnostics. Remaining UNKNOWN notices are product names, protocols, paths, code, and identifiers.

Validation

• Exact key/type/placeholder/markup/link/URL/schema parity passed.
• The catalog carries exactly the 29 runtime-reachable primary tool groups required by PR feat: add the Spanish (es) locale across all four translated surfaces #2055's forthcoming parity checks.
• The documented locale list includes tlh, ready for PR feat: add the Spanish (es) locale across all four translated surfaces #2055's catalog/documentation parity assertion.
• Stable and development add-on shared strings remain identical.
• Ruff and both permitted proxy mypy scopes passed.
• Focused locale/add-on tests: 31 passed.
• GitHub Actions is being monitored on the rewritten branch head.

[kingpanther13]

Post-#2055 rebase update — this supersedes my earlier implementation summaries; I am leaving those comments untouched.

• Rebased onto merged master at 8a855bf4; the branch now applies cleanly and includes Spanish and Klingon in the documented locale set.
• Added Klingon for all 16 common.* options-form strings introduced by feat: add the Spanish (es) locale across all four translated surfaces #2055, bringing the component catalog from 77 to 93 scalar leaves.
• Adapted connect_local_lan to the final merged source and retained the exact visible Local network option. Also retained the fixed HA-MCP File & YAML Tools config-entry title in the three user-facing references while keeping the surrounding prose—and the Home Assistant “Add entry” action—translated.
• Revalidated the merged contract: 419 settings messages, exactly 29 renderable groups, all 87 tools with translated title/description pairs, 93 component leaves, 32 stable add-on leaves, and 52 development add-on leaves (799 translated values total).
• Exact merged locale-parity assertions pass locally, all 14 add-on structure tests pass, the picker is pinned to tlhIngan Hol (Klingon), and the changed Python test file passes Ruff check/format.
• The full source/glossary/false-friend/morphology review remains intact. The post-merge sentence adaptation was rechecked with Klingonia and produced zero non-UNKNOWN grammar diagnostics; expected unknowns are fixed product/code/placeholder tokens.
• Every rewritten/new commit has both author and committer set to kingpanther13 <kingpanther13@users.noreply.github.com>.

The PR remains a draft while the fresh CI run completes.

[kingpanther13]

When reviewing this one keep in mind it's really more for fun. If this will add any kind of maintenance burden, footguns, or etc, or will make any other localization more difficult to handle then I will consider closing it.

[Patch76]

I'll add Esperanto too 😺

[Patch76]

The provenance section is what I would want every locale PR to carry: surveying the Foswiki, Blockly and humanize catalogs, rejecting the OpenOffice tree on a measured coverage figure, and running an explicit false-friend audit is a stronger sourcing story than the existing catalogs have behind them.

The branch is 12 commits behind master, and one of them changes what this PR has to satisfy. #2063 merged test_one_english_string_reads_the_same_on_every_surface, which compares every English string shipped from more than one surface against its translation on the others. The 31 green checks on ceb76d58 predate it.

Concern 1: I replicated that check against the catalogs at ceb76d58, and tlh diverges in 34 of the 53 shared groups — 46 values, 33 in homeassistant-addon-dev, 12 in homeassistant-addon, 1 in the component. The same run reports 0 for de, es, fr, ru and zh-Hans. It is the drift #2063 documents for de (25 groups) and zh-Hans (18): the settings UI and the add-on options word the same switch differently. The 34 groups cover 18 add-on options — among them enable_tool_search, tool_search_max_results, enable_tool_security_policies, read_only_mode, enable_mandatory_bps, enable_strict_mandatory_bps, the beta and YAML toggles and both snapshot-deletion fields — plus the component's extra_yaml_keys against the settings UI's extra_yaml_write_keys. All 34 have a settings UI member, so the tie-break the test names resolves every one of them: that is the wording the other surfaces follow.

Concern 2: test_tlh_catalog_loads_and_is_registered re-adds a per-locale copy of the kind #2055 replaced. Catalogs are discovered from the directory rather than registered, so the file test_every_locale_ships_on_every_surface already requires is what puts tlh in CATALOGS; test_shipped_catalog_loads_and_is_registered is parametrized over those and asserts native_name, dir, tool_groups and tools for tlh today. test_native_names_name_their_own_language pins the name's distinctness and test_agents_md_lists_every_shipped_locale the documentation line. An empty messages is caught by test_settings_catalog_is_not_a_copy_of_english, which counts a missing key as untranslated for exactly that reason. What the new test adds beyond all of those is three literal pins: the exact native_name, dir fixed to ltr rather than either direction, and actions.save. The docstring on the parametrized test gives the reason the four earlier copies were removed: they had drifted, ru had no copy at all and de asserted neither tool_groups nor tools.

Concern 3 is a scope question rather than a defect. tlh is not a Home Assistant language code: cv.language is vol.In(LANGUAGES) over homeassistant/generated/languages.py, which lists 64 codes and not this one, and the frontend's translationMetadata.json offers the same 64. The component catalog and both add-on catalogs — 177 of the 801 values — therefore have no path to being selected from the Home Assistant UI; only the settings UI carries its own picker. The four-surface rule requires shipping them either way, so the decision is whether a language Home Assistant itself cannot select should ship on the surfaces Home Assistant owns.

One minor point: the five existing catalogs use a bare endonym for meta.native_name, and this one appends an English gloss.

Unrelated to the above, #2062 edits the same AGENTS.md locale line, so whichever of the two lands second rebases it.

[kingpanther13]

I will mark ready for review when I'm ready. Going to let the other language stuff merge first.

[kingpanther13]

After doing a simple docs PR that involved having the AI hand-edit multiple files, I definitely think we need to redo how our translations work before implementing this or any other fun languages. I'll file an issue a bit later about my thoughts/research (once session limit resets lol), but it seems like we can edit just English and then essentially have CI automatically generate changes to the other languages instead of having to hand edit.

[Patch76]

Yeah, this idea—which is great in theory—has turned into a bit of a nightmare. If something's missing here, something's missing there, and vice versa—it's kind of annoying, actually.

[kingpanther13]

See issue #2083 , I still need to properly research it but it should be the solution to our problems.