i18n Cleanup Plan

Branch: feature/multi-language-support Created: 2026-02-28 Status: Planned

# Overview

Four-phase cleanup of the web-frontend translation system, executed in dependency order:

Do not execute phases in parallel. Phase 1 establishes canonical keys. Phase 2 finishes adding all keys. Phase 3 refactors tests to use stable selectors (which also makes Phase 4’s unused-key scanner more accurate, because test-referenced keys are now visible to it). Phase 4 then deletes what remains unused.

# Test Impact — Critical Context

Before touching any translation file or component, read this section.

The test suite uses real i18n with the actual EN locale files (not mocks). src/test/setup.ts imports src/i18n/config and calls i18n.changeLanguage('en'). This means:

• What tests see: The fully rendered English text output (e.g., "Cancel", "Save")
• Not what tests see: Translation keys or namespace paths

# Current test exposure

The dominant patterns are screen.getByText(), screen.getByRole(..., { name: }), getByPlaceholderText(), getByLabelText(), and Playwright’s toContainText(). All of these assert on the rendered string value, not on key names.

# Phase-by-phase blast radius

Phase 1 (deduplication) — LOW test risk. Moving a key from events:form.cancel to common:actions.cancel does NOT change the rendered text (both resolve to "Cancel" in EN). Tests that do getByText('Cancel') will continue to pass. The only tests at risk are the 6 instances of t_call_in_test — tests that call t() directly to construct their expected values; those must be updated to reference the new key path.

Phase 2 (hardcoded → t()) — MEDIUM test risk. Converting <button>Save Changes</button> to <button>{t('events:form.saveChanges')}</button> is safe if and only if the EN translation value is identical to the removed hardcoded string. If the value differs even in capitalisation or punctuation, getByText('Save Changes') will fail. Rule: the EN translation value for a new key must be a character-for-character copy of the string it replaces.

Phase 3 (test refactor) — ZERO production risk, MEDIUM test effort. No production code changes. Only test files and component data-testid attributes are touched. The unit test suite will go green faster because assertions no longer depend on specific EN strings. E2E tests stop using button:has-text('...') and text=/some label/i patterns.

Phase 4 (deleting unused keys) — NEAR-ZERO test risk. Deleting a key that is genuinely unused cannot affect tests — if the key were used in code, it would have been caught by the analysis. Doing Phase 3 first means any key referenced in tests is already visible to the scanner. Run the full test suite as a sanity check after deletion.

# Test fix workflow (apply in all phases)

When a test breaks after a translation change:

1. Determine root cause — is it a changed EN value, a removed key, or a renamed key?
2. Fix the component first if the component is wrong (wrong key, missing useTranslation namespace)
3. Then fix the test — update the expected string to match the new EN value, or switch the assertion to a more resilient selector:
   • Prefer getByRole('button', { name: /cancel/i }) over getByText('Cancel') — role-based selectors survive EN value tweaks
   • Prefer getByTestId or data-testid for elements where text is incidental
4. Never update a test to expect a translation key path (e.g., events:form.cancel) — that means the component has a broken useTranslation setup
5. Run the full unit test suite after each file batch: cd web-frontend && npm run test -- --run

# High-risk test files to watch (most text assertions)

These files are most likely to need attention in Phase 2, since they test components that appear in the hardcoded-text list:

# Phase 1 — Consolidate Duplicate Translations

Goal: Eliminate 169 cross-namespace duplicate values. All generic UI tokens (Cancel, Save, Status, Delete, …) must live exclusively in common and be referenced from other namespaces via t('common:actions.cancel').

# Background

The analysis found:

• 302 unique values appearing in 2+ keys
• 169 of those span multiple namespaces (prime consolidation candidates)
• 89 cross-namespace duplicates already have a canonical key in common — callers just need to be pointed there
• 80 cross-namespace duplicates are NOT yet in common — need a new common key added first

# Sub-task 1.1 — Redirect callers to existing common keys

For each entry below, delete the duplicate key from the other namespace’s JSON file and update every t() call in the source to use the common: key.

Canonical common key → duplicate keys to remove:

# Sub-task 1.2 — Add missing keys to common and consolidate

The following 80 values are duplicated across namespaces but have no canonical common key yet. Add each to common.json, then remove duplicates from other namespaces and update t() calls.

Top priority (highest duplication count):

Full list of 80 entries is in /tmp/duplicates_report.txt.

# Acceptance Criteria — Phase 1

• All 89 “already in common” duplicate keys removed from non-common All 89 "already in common" duplicate keys removed from non-`common` namespaces, callers updated
• All 80 “not yet in common” values added to common.json All 80 "not yet in common" values added to `common.json`, duplicates removed from other namespaces, callers updated
• All other locale files (de, es, fr, etc.) updated in sync — remove the same keys, add translations for the new common All other locale files (`de`, `es`, `fr`, etc.) updated in sync — remove the same keys, add translations for the new `common` keys
• The 6 t_call_in_test usages in unit tests updated to reference the new canonical common The 6 `t_call_in_test` usages in unit tests updated to reference the new canonical `common` key paths
• Full unit test suite passes: cd web-frontend && npm run test -- --run **Full unit test suite passes: `cd web-frontend && npm run test -- --run`** — 0 new failures vs baseline
• npm run type-check `npm run type-check` passes
• npm run lint `npm run lint` passes
• Playwright smoke suite passes (at least chromium Playwright smoke suite passes (at least `chromium` project)
• No runtime i18next: missing key No runtime `i18next: missing key` warnings in browser console

# Phase 2 — Translate Hardcoded UI Text

Goal: Replace all hardcoded English strings in production .tsx files with t() calls.

Excluded from this phase (intentionally kept in German for now):

• pages/public/PrivacyPage.tsx
• pages/public/SupportPage.tsx

Total scope (after exclusions): 78 files, 254 hardcoded hits.

# Priority order

Work through the groups below in order — higher-visibility / user-facing first.

# Group A — Public pages (41 hits, 4 files)

# Group B — Speaker portal (50 hits, 7 files)

# Group C — Organizer components (56 hits, ~20 files)

# Group D — Shared & user components (45 hits, ~20 files)

# Workflow per file

1. Open file, identify each hardcoded string
2. Check if a suitable key already exists in common (after Phase 1) or in the file’s own namespace
3. If yes → use existing key. If no → add new key to the appropriate namespace
4. Replace hardcoded string with t('namespace:key') (or bare t('key') if useTranslation already declares the namespace)
5. The EN translation value must be a character-for-character copy of the string being replaced — same casing, same punctuation, same whitespace. This is what keeps co-located tests passing without touching them.
6. Add the same key to all other locale files (de, es, fr, it, nl, fi, ja, rm) — use English value as placeholder if translation not yet available, prefix with [MISSING] to make it findable
7. Prefer common namespace for generic labels (buttons, statuses, form labels)
8. After each file (or small batch of files): run cd web-frontend && npm run test -- --run and fix any broken tests before continuing

# When a test breaks in Phase 2

Follow the test fix workflow from the Test Impact section above. The most common causes:

• EN value differs from hardcoded string → fix the EN translation value to match exactly
• Test was asserting on placeholder/aria-label that is now translated → update test assertion to match new EN value, or convert to getByRole
• Component now needs useTranslation but the test doesn’t provide i18n context → unlikely (setup.ts initialises real i18n globally), but if it happens, wrap the render in I18nextProvider

# Acceptance Criteria — Phase 2

• 0 hardcoded user-visible strings in the 78 scoped files (re-run the analysis script)
• All new keys added to all locale files; missing translations prefixed All new keys added to all locale files; missing translations prefixed `[MISSING]`
• Full unit test suite passes: cd web-frontend && npm run test -- --run **Full unit test suite passes: `cd web-frontend && npm run test -- --run`** — 0 new failures vs Phase 1 baseline
• High-risk test files explicitly verified **High-risk test files explicitly verified** (RegistrationWizard, InvitationResponsePage, ParticipantBatchImportModal, PartnerFilters, FilterSidebar, CompanyAutocomplete — see table in Test Impact section)
• npm run type-check `npm run type-check` passes
• npm run lint `npm run lint` passes
• Playwright smoke suite passes (chromium, speaker, partner Playwright smoke suite passes (`chromium`, `speaker`, `partner` projects)
• No i18next: missing key No `i18next: missing key` warnings in browser console for EN locale

# Phase 3 — Translation-Independent Tests

Goal: Make the entire test suite (unit + E2E) resilient to translation changes. Tests must never hard-code English text strings. After this phase, renaming a translation value or moving a key to a different namespace cannot cause a test failure.

This phase has two parallel workstreams that can be done by different people simultaneously:

• 3A: Add data-testid attributes to components (production code changes)
• 3B: Refactor test assertions to use role-based or data-testid selectors (test-only changes)

3B is blocked on 3A for elements that need new data-testid anchors. Elements that already have a clear ARIA role (button, heading, dialog, tab, etc.) can be refactored in 3B immediately.

# Background — current state

169 components already use data-testid — the pattern is established. The task is to extend it consistently and migrate assertions.

# Selector strategy (rule of thumb)

Apply these rules in order — use the first that applies:

Never use getByText for button labels, headings, or form labels — these are translations. Never use locator('button:has-text("...")') — replace with getByRole or getByTestId.

# data-testid naming convention

[feature]-[component]-[element]

Examples:
  data-testid="event-list-create-btn"
  data-testid="speaker-invitation-accept-btn"
  data-testid="participant-table-row"
  data-testid="partner-filter-status-select"
  data-testid="slot-assignment-confirm-dialog"
  data-testid="user-detail-edit-roles-btn"

Rules:

• Kebab-case only
• Prefix with the feature/page area
• Suffix with element type for interactive elements (-btn, -input, -select, -dialog, -tab, -panel)
• Do NOT use data-testid on every element — only on elements that tests need to find and that have no clear role/label

# Sub-task 3A — Add data-testid to components

Focus on the components where E2E tests currently use button:has-text(...) or text=/regex/i. Highest priority:

Also add data-testid to these high-usage unit test targets (most-referenced in 4,400 assertions):

• Dialog confirm/cancel button pairs
• Table action buttons (edit, delete, view)
• Tab navigation items
• Status badge elements
• Pagination controls

# Sub-task 3B — Refactor test assertions

# Unit tests (Vitest)

Replace in order of prevalence:

// ❌ Before — brittle text literal
screen.getByText('Cancel')
screen.getByRole('button', { name: 'Save Changes' })
screen.getByPlaceholderText('Enter email address')
screen.getByLabelText('Status')

// ✅ After — role-based (when role + name is distinctive)
screen.getByRole('button', { name: /cancel/i })
screen.getByRole('button', { name: /save/i })
screen.getByRole('textbox', { name: /email/i })
screen.getByRole('combobox', { name: /status/i })

// ✅ After — testid (when role alone is not distinctive)
screen.getByTestId('participant-import-cancel-btn')
screen.getByTestId('user-edit-roles-save-btn')

Note on name matching: use regex with case-insensitive flag (/cancel/i) instead of exact strings. This survives minor EN value tweaks (e.g., “Cancel” → “Cancel action”).

# E2E tests (Playwright)

// ❌ Before — brittle
page.locator('button:has-text("Accept Invitation")')
page.locator('text=/Invalid Link/i')
expect(page.locator('h1')).toContainText('Speaker Brainstorming')

// ✅ After — stable
page.getByTestId('invitation-accept-btn')
page.getByTestId('invitation-error-invalid')
page.getByRole('heading', { name: /speaker brainstorm/i })

Special cases noted in current E2E tests:

• text=/Archiviert|Archived/i — multi-language regex fallback: replace with getByTestId('event-status-archived')
• text=/error|fehler|ungültig/i — error state with German fallback: replace with getByTestId('form-error-message') or getByRole('alert')
• text=BATbern57 — asserting on event data (not UI chrome): keep as-is, this is correct
• locator('tbody tr') — structural: replace with getByTestId('user-table-row') or getByRole('row')

# High-priority E2E files (most brittle patterns)

# Acceptance Criteria — Phase 3

• Zero button:has-text('...') Zero `button:has-text('...')` patterns remaining in any E2E spec file
• Zero text=/translated string/i Zero `text=/translated string/i` locators remaining (except for data-content assertions like event titles)
• Zero locator('h1') / locator('h2') / locator('label') / locator('tbody tr') remaining — replaced with getByRole or Zero `locator('h1')` / `locator('h2')` / `locator('label')` / `locator('tbody tr')` remaining — replaced with `getByRole` or `getByTestId`
• Zero getByText('...') calls with EN UI labels in unit tests — replaced with getByRole(..., { name: /regex/i }) or Zero `getByText('...')` calls with EN UI labels in unit tests — replaced with `getByRole(..., { name: /regex/i })` or `getByTestId`
• All new data-testid attributes follow the [feature]-[component]-[element] All new `data-testid` attributes follow the `[feature]-[component]-[element]` convention
• Full unit test suite passes: cd web-frontend && npm run test -- --run **Full unit test suite passes: `cd web-frontend && npm run test -- --run`**
• Full Playwright suite passes: npx playwright test (all three projects: chromium, speaker, partner **Full Playwright suite passes: `npx playwright test`** (all three projects: `chromium`, `speaker`, `partner`)
• No data-testid No `data-testid` added to elements that already have a unique ARIA role — reviewable via PR

# Phase 4 — Smarter Unused Key Analysis

Goal: Reduce the 830 “potentially unused” keys to an actionable short list, without manual review of all 830.

The Phase 1 analysis was conservative — a key is flagged as “unused” if its bare string doesn’t appear in any t('...') call. But i18next allows dynamic key construction (e.g., t(`status.${state}`)) which the scanner cannot see. Phase 4 must account for this. Because Phase 3 has already migrated tests to use t() or getByTestId, the scanner now also sees keys referenced from tests — giving a more accurate picture of what is truly unused.

# Step 4.1 — Detect dynamic key patterns

Run a focused scan to find all dynamic t() calls in the source:

Pattern: t(`...${...}...`)  or  t(variable)  or  t(someKey + suffix)

For each dynamic call, extract:

• The static prefix (e.g., workflow. from t(`workflow.${state}`))
• The possible suffix values (look for the variable’s assignment or union type)

Build a list of all key prefixes that are referenced dynamically. Any translation key whose path starts with one of these prefixes must be kept even if no literal t('ns:key') call exists.

# Step 4.2 — Cross-reference with component prop drilling

Some keys are passed as props (label={t('ns:key')} resolved at a parent level). The scanner catches these fine if the key is a literal. But keys stored in config arrays or maps (e.g., a columns array with label: t('...')) may be missed if defined outside JSX. Scan for:

Pattern: label:\s*t\(  |  header:\s*t\(  |  title:\s*t\(  |  name:\s*t\(

# Step 4.3 — Generate tiered output

After steps 3.1 and 3.2, re-classify the 830 keys into three buckets:

Output: a markdown report docs/plans/i18n-unused-keys-report.md with all three buckets, total counts, and delete commands for the “Definitely unused” bucket.

# Step 4.4 — Delete confirmed unused keys

For each key in the Definitely unused bucket:

1. Remove the key from the EN locale JSON
2. Remove the same key from all other locale files
3. Run npm run type-check and Playwright smoke to confirm nothing broke

# Acceptance Criteria — Phase 4

• Automated script (scripts/i18n/analyze-unused.py Automated script (`scripts/i18n/analyze-unused.py`) committed to repo and runnable
• "Definitely unused" keys deleted from all locale files
• "Needs manual check" bucket is ≤ 50 keys (short enough for a focused review)
• Full unit test suite passes after deletion: cd web-frontend && npm run test -- --run **Full unit test suite passes after deletion: `cd web-frontend && npm run test -- --run`** — any failure after Phase 4 means a key was wrongly classified as unused; restore it and re-analyse
• npm run type-check `npm run type-check` passes
• npm run lint `npm run lint` passes
• Playwright smoke suite passes

# Implementation Notes

# Key naming conventions (going forward)

common:actions.*       — buttons and CTA labels (save, cancel, delete, edit, confirm, retry, close)
common:labels.*        — generic field labels (date, title, status, email, company)
common:filters.*       — filter panel labels and status values
common:filters.status.* — shared status values (all, active, inactive, pending, confirmed)
common:navigation.*    — nav items and tab labels
common:errors.*        — generic error messages
common:loading.*       — loading/saving states

# Running the hardcoded-text scanner

cd web-frontend
python3 scripts/i18n/scan-hardcoded.py  # (to be committed in Phase 2)

# Running the unused-key analyzer (Phase 4)

python3 scripts/i18n/analyze-unused.py  # (to be committed in Phase 4)

# Locale file sync rule

Whenever a key is added to EN, it must be added to all other locales in the same commit. Use [MISSING] prefix for untranslated values so they are findable by CI or grep:

grep -r '\[MISSING\]' web-frontend/public/locales/

# Reference Data