Skip to content

feat: localization (en/es/fr/de) — supersedes #11#32

Merged
KadenThomp36 merged 1 commit into
mainfrom
feat/localization
May 13, 2026
Merged

feat: localization (en/es/fr/de) — supersedes #11#32
KadenThomp36 merged 1 commit into
mainfrom
feat/localization

Conversation

@KadenThomp36
Copy link
Copy Markdown
Owner

Closes #10. Supersedes PR #11.

Summary

Adds embedded localization for the card UI in English, Spanish, French, and German.

Spanish, French, and German translations were originally contributed by @b0rv3g4r4 on PR #11. PR #11 went stale (last activity 2026-03-06) and conflicts with main; this PR carries that work forward, addresses the four review comments left on the original PR, and rebases against the current code.

Changes vs. PR #11

PR #11 issue (from review) Resolution in this PR
Used `getConfigForm()` (legacy) — conflicts with v2.6.1's switch to `getConfigElement()` Rebased against current LitElement-based editor (`getConfigElement()`)
Async `fetch()` of JSON locale files adds first-render latency, brittle `document.currentScript` URL detection, requires HACS `dist/` restructuring Translations embedded as a `TRANSLATIONS` const. No fetch, no async init, no HACS restructuring
Removed the `setConfig` entity validation Validation preserved
Distribution setup needed (`dist/` directory) Not needed — single-file distribution unchanged

What's translated

  • Overall status badge (Excellent / Good / Moderate / Fair / Poor / etc.)
  • Recommendation strip (title + dynamic subtitle with `{value}` interpolation)
  • Radon advisory title
  • Visual editor labels and section titles (Additional Sensors / Outdoor Sensors / Advanced)

Not yet translated (will land in a follow-up so this PR stays scoped):

  • Per-sensor status labels (Safe / Low / Moderate / High / Dangerous) — these are produced via the `METRIC_DEFS` table from feat: per-metric custom thresholds #29, easier to translate once that's merged
  • Radon advisory subtitle prose (e.g. "EPA recommends mitigation above…") — partial translation only
  • Graph axis labels (CO, CO₂, etc.) — chemical names, mostly the same across languages

HA-native approach

  • `hass.locale.language` first, falls back to deprecated `hass.language` for older HA versions, then to `'en'`. Per HA dev docs and the `localize`/`locale` HomeAssistant interface.
  • Regional codes are stripped (e.g. `es-MX` → `es`).
  • Optional `language` config option for explicit override.
  • English is the fallback for any key missing in a translated locale (so contributors can add new languages incrementally).

YAML example

```yaml
type: custom:air-quality-card
co2_entity: sensor.air_quality_co2
language: es # or 'en' / 'fr' / 'de' / 'auto' (default)
```

Test plan

  • `node test.js` — 235 passed, 0 failed (29 new tests covering: language resolution precedence, `hass.locale.language` vs `hass.language` fallback, regional code stripping, unknown-language fallback, per-language status text, recommendation key→text mapping, icon backward-compat for English text, `_ts` interpolation in all 4 languages)
  • All previous tests pass unchanged — English fallback preserves the existing public API
  • Manual smoke test: set HA frontend language to Spanish, load card, confirm status badge shows "Excelente"/"Bueno"/etc.
  • Manual smoke test: `language: fr` config, confirm overrides HA language
  • Manual smoke test: editor labels and section titles render in the active language

Contributor credit

Spanish/French/German translations: @b0rv3g4r4 (PR #11). I'll @-mention them when merging so they're credited on the release.

Notes for maintainer

Spanish/French/German strings contributed by @b0rv3g4r4 on PR #11.
Translations are embedded as a const rather than fetched at runtime to
avoid first-render latency and HACS dist-directory restructuring.
@KadenThomp36 KadenThomp36 merged commit 0901a37 into main May 13, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature Request] Add support to localization

1 participant