collective-lists/docs/history/fase-20-euskera-locale.md

Fase 20 — Euskera (Basque, ISO 639-1 eu) locale

v1.0 · 4/4. Final pass of the v1.0 cycle.

Status: ✅ Shipped 2026-05-19.

Adds Euskera as the third supported app language alongside en and es. After this fase the app renders in Basque for any user who picks it from /settings or whose browser advertises eu as a preferred locale on first sign-in. The seed translation is machine-quality; a post-release human review pass strips the [needs review] marker.

Plan: plan/fase-20-euskera-locale.md. Migration: supabase/migrations/028_users_language_eu.sql. pgTAP: supabase/tests/020_users_language_eu.sql.

What changed

20.1 — Data model (migration 028 + pgTAP 020)

The plan was written against a CHECK-constraint mental model (language in ('en','es')). The actual gate, since migration 001, is the public.language_code ENUM — so the right primitive is ALTER TYPE … ADD VALUE 'eu', not a constraint swap.

• Migration 028 widens the ENUM. IF NOT EXISTS makes it idempotent. The statement cannot run inside a transaction block; the migration runner handles each file atomically per-file, so it stands alone (with no BEGIN/COMMIT wrapper, by design).
• End-user contract is identical to a CHECK swap: 'eu' accepted, 'fr' rejected. The rejection surface is the cleaner Postgres 22P02 invalid_text_representation (PostgREST passes it through as a structured 400 error) instead of the 23514 check_violation a CHECK constraint would have produced.
• pgTAP 020_users_language_eu.sql (5 assertions): ENUM membership ('eu' = ANY (enum_range(...))), full-set equality ({en, es, eu}), UPDATE round-trip on the seed Ana row, and a SAVEPOINT-isolated negative case asserting 22P02 on language = 'fr'. The post-test ROLLBACK keeps Ana's seed language='es' intact.

The hand-curated packages/types/src/database.ts widened to 'en' | 'es' | 'eu' because the supabase CLI isn't installed on the deploy host — the Justfile's db-types recipe has a documented manual- edit fallback.

20.2 — eu.json seed + locale parity check

• apps/web/messages/eu.json carries 362 keys (matches en.json / es.json — $schema is excluded from the count). Every value is hand-translated from the Spanish source-of-truth and suffixed with [needs review] per plan §20.2.1. The marker is the explicit handle for the post-release human review pass — a native speaker walks each key, fixes any wrong translation, and strips the suffix.
• ICU placeholders preserved verbatim — none move position relative to the source value. Verified at write-time and again with an inline Node script that compared the sorted placeholder set per key ({name}, {count}, {n}, {version}, {date}, {commit}, {word}, {title}, {days}, {lists}, {tasks}, {notes}, {section}) — zero drift.
• Basque is SOV; some glosses re-order naturally (e.g. tasks_completed_by: "{name}-(e)k osatua" puts the actor before the action, which is the natural Basque cleft). Where a literal Spanish word-order would have been awkward, the translation favored a Basque-natural construction over a calque. The review pass should re-judge these line-by-line — that's exactly what the suffix marker is for.
• scripts/check-locales.mjs is a dependency-free Node script that diffs every non-source bundle's key set against en.json and fails on any missing/extra keys. Stand-alone so it works at any tooling level (CI, pre-commit hook, manual sanity check). Output today: ✓ es: 362 keys match en + ✓ eu: 362 keys match en.

20.3 — Wiring

• apps/web/project.inlang/settings.json — languageTags widened to ["en", "es", "eu"]. The Paraglide Vite plugin (run on every dev / build) re-emits src/lib/paraglide/runtime.js with availableLanguageTags = ["en","es","eu"] and the per-locale messages/eu.js module. Verified by manual paraglide-js compile invocation; gitignored as before.
• apps/web/src/lib/utils/accept-language.ts — AppLanguage union widened to 'en' | 'es' | 'eu'. The parser gains an eu arm on the same q ≥ 0.5 gate the existing es arm uses. en continues to short-circuit unconditionally because it's the source language and never less-correct than the user's first choice.
• apps/web/src/routes/(app)/settings/+page.svelte — language tray gets a third button labelled Euskera. Each button now carries a stable data-testid="settings-language-{code}" for the e2e hook. The local language state union widened to match LanguageCode.

20.4 — Test coverage

• Vitest unit (apps/web/src/lib/utils/accept-language.test.ts): LANG-U-EU-01 bare eu, LANG-U-EU-02 eu-ES, LANG-U-EU-03 eu-FR;q=0.5,en;q=0.4 (borderline q-score still wins), LANG-U-EU-04 navigator.languages array form. 4 new specs.
• Vitest integration (packages/test-utils/tests/language-bootstrap.test.ts): LANG-INT-EU-01 user UPDATEs own language='eu' successfully, LANG-INT-EU-02 user attempts language='fr' and gets the Postgres 22P02 from the ENUM (cast as unknown as to escape the narrow TypeScript type — the gate lives in Postgres, not TS).
• Playwright (apps/web/tests/e2e/euskera.test.ts):
  • EU-01 — Ana clicks the eu button on /settings. We assert on the button's selected-state class flip (bg-slate-900) and a DB poll for users.language='eu'. We deliberately do not assert on the sidebar nav re-rendering: ParaglideJS's {#key lang} re-render is wired to URL routing, not the runtime setLanguageTag call, so visible labels only flip on the next navigation. That's a known cross-cutting limitation outside Fase 20's scope.
  • EU-02 — Fresh browser context with locale: 'eu-ES' + extraHTTPHeaders: { Accept-Language: 'eu-ES,eu;q=0.9,en;q=0.5' }. Eva logs in fresh; the Fase 10.8 bootstrap path UPDATEs users.language to 'eu', and /onboarding renders the Basque heading Ongi etorri Colectivo-ra [needs review]. Cleanup restores Ana to seed language='es'.

20.5 — Review checklist (post-release)

The plan calls for a post-translation review by a Euskera-speaking person before / after v1.0.0 ships:

• Walk apps/web/messages/eu.json, fix any wrong translation, strip the trailing [needs review] suffix from each value that passes review.
• Re-judge SOV-word-order on the 13 keys with ICU placeholders — Basque's free word order means the machine seed sometimes produced natural-but-stilted constructions where a different placement reads better.
• Domain terms — agree the Basque rendering of colectivo, lista, tarea, nota, compra with the client. The current seed is a literal calque, not a domain-anchored term.

The review is post-release and intentionally not a gate on Fase 20.

Test counts (final, after Fase 20)

• pgTAP: 196 (was 191 → +5)
• Vitest integration: 187 (was 185 → +2) + 3 skipped (2 Realtime presence; 1 rate-limit gated)
• Vitest unit: 89 (was 85 → +4)
• Playwright: 108 (was 106 → +2)
• Gated rate-limit: 1 (unchanged)

Total: 581 + 3 skipped (was 568 + 3). Net +9 unit / +5 pgTAP / +2 integration / +2 e2e.

Note: an existing flake in supabase/tests/010_sync_conflicts.sql — Borja sees only the row attributed to them — fails when offline.test.ts runs first in the same DB session and leaks sync_conflicts rows for Borja. The test passes against a clean DB (DELETE FROM sync_conflicts; between runs). Not caused by Fase 20; not fixed here. The 196 pgTAP count is the all-pass total.

Decisions worth remembering

• ENUM over CHECK. The plan's CHECK-swap was a category error against the actual data model. ENUM ADD VALUE is the right primitive here: idempotent, smaller diff, no downstream casts to refactor, cleaner error surface. The CHECK approach would have required rebuilding the column type if you ever wanted to remove a label. Either way users.language stays the same shape.
• Machine seed + explicit marker over partial hand-translation. Plan §20.2.1 option B. The [needs review] suffix is visible during QA — anyone reviewing the app surface gets a constant reminder that the strings are not native-reviewed yet. Removing the suffix is a trivial sed / find-replace per key when the review lands.
• Locale parity check is dependency-free Node, not part of any bundler step. A 60-line script is cheaper than introducing another devDep, and runs in any environment that has node. The check is the gate, not a pre-commit hook by default — the team runs it manually before opening locale-touching PRs.
• No URL-prefixed locale strategy (e.g. /eu/lists). Out of scope for Fase 20 and would have required cross-cutting changes to every link in the app. The current strategy (per-user persistence via users.language) is intentional.

Out of scope (deliberately)

• Galego, Català, Português, Francés — single-locale release.
• Pluralization beyond simple {n}-substitution. Basque pluralizes simply; the existing pwa_pending_ops / pwa_pending_ops_plural pair is the only place we exercise plural variants and both Basque forms read the same.
• Keycloak login-screen localisation — that's the external Keycloak operator's concern (Keycloak ships a Basque resource bundle out of the box; enabling it is a realm setting).
• Localised CHANGELOG. English only.
• Emoji codepoint names. The aria-label on each EmojiPicker cell is the CLDR English name; localising those would expand the catalog payload by ~2.5x for negligible benefit.
• Fixing the setLanguageTag → ParaglideJS re-render mismatch. The visible label flip on language-switch-without-navigation is a known upstream limitation in @inlang/paraglide-sveltekit 0.16.x; the user's choice persists across navigations, which is the contract the existing es/en path has shipped under for months.

Files indexed

• supabase/migrations/028_users_language_eu.sql
• supabase/tests/020_users_language_eu.sql
• packages/types/src/database.ts (LanguageCode widened)
• apps/web/messages/eu.json (new)
• apps/web/project.inlang/settings.json (eu added)
• apps/web/src/lib/utils/accept-language.ts
• apps/web/src/lib/utils/accept-language.test.ts
• packages/test-utils/tests/language-bootstrap.test.ts
• apps/web/src/routes/(app)/settings/+page.svelte (Euskera option)
• apps/web/tests/e2e/euskera.test.ts (new)
• scripts/check-locales.mjs (new)