Internationalization (i18n) & Localization Guide

The Home Assistant WhatsApp Integration & WhatsApp Addon Web UI feature 100% dynamic i18n support for English (EN), German (DE), and any additional community-contributed language.

Architecture Overview

All language dictionaries are stored as flat, top-level .json files directly inside the respective translation folder. There are no subdirectories — every language file behaves 100% uniformly and identically to en.json and de.json.

├── custom_components/whatsapp/
│   ├── strings.json             # Base keys template for Home Assistant
│   └── translations/
│       ├── en.json              # English translation
│       ├── de.json              # German translation
│       ├── fr.json              # French translation (drop-in)
│       └── es.json              # Spanish translation (drop-in)
│
└── whatsapp/app/src/locales/
    ├── loader.js                # Dynamic file-based locale loader (no hardcoded language lists)
    ├── en.json                  # English dictionary
    ├── de.json                  # German dictionary
    ├── fr.json                  # French dictionary (drop-in)
    └── es.json                  # Spanish dictionary (drop-in)

Automatic Browser Language Detection & Manual Override

The Web UI automatically detects the user’s preferred language on initial visit:

Browser Auto-Detection: Reads navigator.language (e.g. de-DE -> de or en-US -> en).
Default Fallback: If an unsupported language or no language is detected, the system automatically defaults to en (English).
Manual Selection: Users can switch the UI language anytime using the language selector (🌐 DE / EN) in the top navigation header.
Persistence: Manual preferences are stored in localStorage (ha-whatsapp-lang) and override browser auto-detection.

1. Adding a New Language to the Web UI & Addon

Adding a new language to the Addon Web UI requires zero code modifications.

Create a new .json file inside whatsapp/app/src/locales/<lang_code>.json (e.g., es.json or fr.json).

Include language metadata in the meta section:

{
  "meta": {
    "code": "es",
    "name": "Español",
    "flag": "🇪🇸"
  },
  "nav": { ... },
  "common": { ... }
}

The server-side loader.js will automatically discover the new language file on startup and expose it via /api/i18n/languages.

2. Adding a New Language to the Home Assistant Integration

Create a new file in custom_components/whatsapp/translations/<lang_code>.json.
Mirror all key structures from custom_components/whatsapp/strings.json.

3. Automated Translation Verification

Run the automated test suite to verify key parity across all language files:

npm test

The test runner automatically validates:

Key parity across all locale files in src/locales/
Interpolation placeholder matching ({count}, {name}, etc.)
Parity between Home Assistant strings.json and translations/de.json