chore(translations): add locale parity guard and contributor policy - #63
Merged
Conversation
Extend tests/test_translation_keys_in_sync.py beyond en.json so every file in translations/ is checked. Locale files must be valid JSON and must not declare keys absent from strings.json, since a stale key left behind by a rename never renders. Missing keys are reported as a TranslationDriftWarning rather than a failure: Home Assistant falls back to English per key, so a lagging locale is cosmetic, and the author of a feature PR is usually not the person able to translate it. Gating merges on it would tax feature contributions to no user benefit. Use -W error::UserWarning to promote it for a single run. Locales are discovered by glob so the next translation is covered on arrival, and test_locales_discovered fails if that glob ever matches nothing rather than silently collecting no cases. Document the policy in CONTRIBUTING.md and add .github/CODEOWNERS so the zh-Hans translator is asked to review edits to their own file. Assisted-by: Claude:claude-opus-5
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Follow-up to #58. The translation parity test only guarded
translations/en.json, sozh-Hans.jsoncould silently drift as new config-flow steps landed. This extends the guard across every locale file, and settles the policy question that comes with it: what should a lagging translation do to CI?The split follows who can fix the failure. A stale or misspelled key is the PR author's own doing and is always fixable by them, so it fails. A missing key usually cannot be fixed by whoever added the string, so it warns.
strings.json↔en.jsonparitystrings.jsonstrings.jsonTranslationDriftWarningGating merges on translation completeness would tax feature PRs for no user benefit — Home Assistant falls back to English per key, so a lagging locale is cosmetic.
-W error::UserWarningpromotes the warning to a failure for a single run if you want to audit.Locales are found by glob rather than listed, so the next translation is covered the moment it lands.
Changes
tests/test_translation_keys_in_sync.py— three new checks (test_locales_discovered,test_translation_has_no_unknown_keys,test_translation_completeness); the two existing English checks are untouched.CONTRIBUTING.md— new "Translations" section: what is enforced, what is best-effort, and how to add a locale..github/CODEOWNERS(new) —zh-Hans.jsonowned by @MF-142, scoped to the locale file rather thanstrings.jsonso translators aren't pinged on every feature PR.translationslabel was created on the repo (not part of this diff).Test Plan
pytest tests -qpasses — 478 passed (was 475)ruff check custom_components/ tests/ scripts/passesruff format --diff custom_components/ tests/ scripts/is cleanmypy custom_components/cap_alertspassesBoth new hard checks were negative-tested: injecting an unknown key and deleting an existing one from
zh-Hans.jsonproduced the intended failure and warning respectively, and the file was restored.Related Issues
Follow-up to #58.
Assisted-by: Claude:claude-opus-5