Locale Key Checks

Overview

The locale key parity check ensures every translation key present in the reference locale (en) also exists in all other tier-1 locales (en, pt). It runs automatically in CI on every push or PR that touches locale files.

---

Locale file conventions

Locale files live in apps/dashboard/src/locales/ and follow a two-pattern naming convention that mirrors the i18next namespace loading strategy:

File	Namespace	Locale
en.json	common	en
pt.json	common	pt
people.en.json	people	en
people.pt.json	people	pt

To add a new namespace foo for locale en, create foo.en.json. The check script discovers all *.json files automatically.

---

Running locally

# From repo root — exits 0 if all tier-1 locales are complete
node scripts/check-locale-keys.mjs

# Verbose: also prints extra keys present in non-reference locales
node scripts/check-locale-keys.mjs --verbose

# Via the root package.json shortcut
pnpm locale:check

Example passing output

Locale key parity check
  Locales dir : .../apps/dashboard/src/locales
  Reference   : en
  Tier-1      : en, pt
  Namespaces  : common, people

  [common]  34 keys in reference (en)
    ✓ pt — complete (34 keys)

  [people]  33 keys in reference (en)
    ✓ pt — complete (33 keys)

OK    All tier-1 locales are complete (67 keys checked).

Example failing output

  [common]  34 keys in reference (en)
    ✗ pt — 2 missing key(s):
        - common.admin
        - common.switch_workspace

FAIL  2 missing key(s) detected across tier-1 locales.

---

CI workflow

The check runs as a GitHub Actions job (locale-key-parity) defined in .github/workflows/locale-check.yml. It is triggered on:

• push or pull_request — whenever files under apps/dashboard/src/locales/** or the script itself change.
• workflow_dispatch — manual trigger from the GitHub Actions tab.

The job requires no pnpm install because the script has no external dependencies (pure Node.js built-ins only).

---

Adding a new translation key

1. Add the key to the reference locale file (en.json or {namespace}.en.json).
2. Add the key with a translated value to every other tier-1 locale file.
3. Run pnpm locale:check locally to confirm parity before pushing.

Missing a step will cause CI to fail with a message listing the exact key path and locale.

---

Adding a new tier-1 locale

1. Create the locale JSON files for every namespace:
   • apps/dashboard/src/locales/{locale}.json
   • apps/dashboard/src/locales/{namespace}.{locale}.json for each namespace
2. Add the locale code to SUPPORTED_LOCALES in apps/dashboard/src/lib/locale.ts.
3. Add the locale code to the TIER1_LOCALES array in scripts/check-locale-keys.mjs.
4. Register the locale metadata via registerLocale() in locale.ts.

---

Tier-1 vs non-tier-1 locales

Currently, all supported locales are tier-1:

Locale	Code	Tier
English	en	1 — reference
Portuguese	pt	1 — strict

Tier-1 locales must be 100% complete. If a future locale is added with only partial coverage, lower it to a non-tier-1 tier by not including it in TIER1_LOCALES — the script will skip the missing-key check for that locale.