From 8c1dfe5460de682148ef6f7723c38207708f657b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andrew=20Beveridge=20=E2=98=84=EF=B8=8F?= Date: Fri, 3 Apr 2026 21:50:53 -0400 Subject: [PATCH] =?UTF-8?q?feat(i18n):=20Phase=203=20frontend=20=E2=80=94?= =?UTF-8?q?=20next-intl=20infrastructure=20+=201062=20strings=20(en/es/de)?= =?UTF-8?q?=20(#656)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit @coderabbitai ignore ## Summary - Phase 3 of the i18n multilingual initiative — makes the karaoke-gen frontend fully multilingual (English, Spanish, German) - Installs `next-intl` with `[locale]` path-based routing, LanguageSwitcher, and `Accept-Language` API header - Extracts **1,062 strings** from ~70 components into `messages/en.json` across 31 namespaces - Wires `useTranslations()` into all user-facing components (landing, dashboard, auth, job flow, lyrics review, instrumental review, audio editor, etc.) - Admin pages (`/admin/*`) stay outside locale routing — intentionally excluded from i18n scope - Static export generates `/en/`, `/es/`, `/de/` directories (45 total pages) for Cloudflare Pages - `es.json`/`de.json` are English placeholders — translation via Gemini pipeline pending - Translation pipeline (`scripts/translate.py`) and glossary (55 karaoke-specific terms) included ## Key architecture decisions - Root layout keeps ThemeProvider/TenantProvider (needed by admin pages outside `[locale]`) - Only NextIntlClientProvider added to `[locale]/layout.tsx` - `job-status.ts` labels converted to translation keys; consumers translate via `useTranslations('jobStatus')` - Jest mock loads actual `en.json` so existing tests validate i18n wiring without assertion changes ## Test plan - [x] All 707 frontend tests pass (39 suites) - [x] Static build generates all 45 pages across 3 locales - [x] Admin pages render at `/admin/` without locale prefix - [x] CodeRabbit review: 4 issues fixed, 7 pre-existing noted - [ ] Post-deploy: verify `/en/` landing page renders correctly - [ ] Post-deploy: verify LanguageSwitcher redirects to `/es/` and `/de/` - [ ] Post-deploy: verify `/admin/` still works without locale context 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.6 (1M context) --- .next/trace | 1 + .next/trace-build | 1 + docs/LESSONS-LEARNED.md | 16 + docs/README.md | 1 + docs/archive/2026-04-03-i18n-phase3-plan.md | 215 +++ frontend/__tests__/job-status.test.ts | 72 +- .../[locale]/app/jobs/[[...slug]]/client.tsx | 446 ++++++ .../[locale]/app/jobs/[[...slug]]/page.tsx | 16 + frontend/app/[locale]/app/page.tsx | 512 +++++++ frontend/app/[locale]/auth/verify/page.tsx | 274 ++++ frontend/app/[locale]/layout.tsx | 38 + frontend/app/[locale]/order/success/page.tsx | 84 ++ frontend/app/[locale]/page.tsx | 863 ++++++++++++ .../app/[locale]/payment/success/page.tsx | 90 ++ frontend/app/page.tsx | 898 +----------- frontend/components/LanguageSwitcher.tsx | 36 + frontend/components/TenantLandingPage.tsx | 14 +- frontend/components/WarmingUpLoader.tsx | 8 +- .../components/__tests__/AuthStatus.test.tsx | 2 +- .../__tests__/PushNotificationPrompt.test.tsx | 8 +- frontend/components/app-header.tsx | 31 +- .../audio-editor/AudioEditRestoreDialog.tsx | 23 +- .../components/audio-editor/AudioEditor.tsx | 69 +- .../__tests__/AudioEditor.test.tsx | 10 +- .../audio-search/AudioSearchDialog.tsx | 34 +- frontend/components/auth/AuthDialog.tsx | 49 +- frontend/components/auth/AuthStatus.tsx | 23 +- .../components/credits/BuyCreditsDialog.tsx | 21 +- .../components/feedback/FeedbackDialog.tsx | 44 +- .../instrumental-review/CustomUpload.tsx | 4 +- .../InstrumentalGuidancePanel.tsx | 47 +- .../InstrumentalSelector.tsx | 60 +- .../InstrumentalSelectorEmbedded.tsx | 21 +- .../instrumental-review/MuteRegionEditor.tsx | 21 +- .../instrumental-review/SelectionOptions.tsx | 30 +- .../instrumental-review/StemComparison.tsx | 14 +- frontend/components/job/ColorOverrides.tsx | 29 +- .../components/job/CommunityVersionBanner.tsx | 12 +- frontend/components/job/EditTrackModal.tsx | 20 +- frontend/components/job/GuidedJobFlow.tsx | 59 +- frontend/components/job/ImageUploadField.tsx | 12 +- frontend/components/job/JobActions.tsx | 24 +- frontend/components/job/JobCard.tsx | 26 +- frontend/components/job/JobSubmission.tsx | 89 +- frontend/components/job/OutputLinks.tsx | 94 +- frontend/components/job/TenantJobFlow.tsx | 42 +- frontend/components/job/ThemeSelector.tsx | 20 +- frontend/components/job/TitleCardPreview.tsx | 8 +- .../components/job/steps/CustomizeStep.tsx | 53 +- .../components/job/steps/SongInfoStep.tsx | 33 +- .../components/job/steps/VisibilityStep.tsx | 69 +- .../AgenticCorrectionMetrics.tsx | 16 +- .../lyrics-review/CorrectionDetailCard.tsx | 22 +- .../lyrics-review/CorrectionMetrics.tsx | 26 +- .../lyrics-review/EditActionBar.tsx | 12 +- .../lyrics-review/EditFeedbackBar.tsx | 51 +- .../components/lyrics-review/EditWordList.tsx | 29 +- .../components/lyrics-review/GapNavigator.tsx | 8 +- .../lyrics-review/GuidancePanel.tsx | 54 +- frontend/components/lyrics-review/Header.tsx | 42 +- .../lyrics-review/LyricsAnalyzer.tsx | 2 + .../components/lyrics-review/ModeSelector.tsx | 16 +- .../lyrics-review/PreviewVideoSection.tsx | 8 +- .../lyrics-review/ReferenceEmptyState.tsx | 9 +- .../lyrics-review/ReferenceView.tsx | 6 +- .../lyrics-review/SessionRestoreDialog.tsx | 33 +- .../lyrics-review/TranscriptionView.tsx | 14 +- .../lyrics-review/modals/AIFeedbackModal.tsx | 37 +- .../lyrics-review/modals/AddLyricsModal.tsx | 8 +- .../modals/CorrectionAnnotationModal.tsx | 116 +- .../lyrics-review/modals/EditModal.tsx | 19 +- .../lyrics-review/modals/FindReplaceModal.tsx | 28 +- .../modals/ModeSelectionModal.tsx | 27 +- .../lyrics-review/modals/PasteLyricsTab.tsx | 14 +- .../modals/ReplaceAllLyricsModal.tsx | 40 +- .../modals/ReviewChangesModal.tsx | 22 +- .../lyrics-review/modals/SearchLyricsTab.tsx | 32 +- .../modals/SegmentDetailsModal.tsx | 4 +- .../modals/TimingOffsetModal.tsx | 16 +- .../synchronizer/LyricsSynchronizer.tsx | 42 +- .../synchronizer/SyncControls.tsx | 26 +- .../synchronizer/UpcomingWordsBar.tsx | 4 +- .../components/push-notification-prompt.tsx | 33 +- frontend/components/push-settings.tsx | 39 +- frontend/components/status-badge.tsx | 14 +- frontend/components/system-status-modal.tsx | 35 +- frontend/i18n/request.ts | 15 + frontend/i18n/routing.ts | 10 + frontend/jest.config.js | 4 + frontend/jest.setup.js | 35 + frontend/lib/api.ts | 10 +- frontend/lib/job-status.ts | 81 +- frontend/messages/de.json | 1226 +++++++++++++++++ frontend/messages/en.json | 1226 +++++++++++++++++ frontend/messages/es.json | 1226 +++++++++++++++++ frontend/next.config.mjs | 5 +- frontend/package-lock.json | 735 +++++++++- frontend/package.json | 1 + frontend/scripts/glossary.json | 63 + frontend/scripts/translate.py | 274 ++++ pyproject.toml | 2 +- 101 files changed, 8550 insertions(+), 1953 deletions(-) create mode 100644 .next/trace create mode 100644 .next/trace-build create mode 100644 docs/archive/2026-04-03-i18n-phase3-plan.md create mode 100644 frontend/app/[locale]/app/jobs/[[...slug]]/client.tsx create mode 100644 frontend/app/[locale]/app/jobs/[[...slug]]/page.tsx create mode 100644 frontend/app/[locale]/app/page.tsx create mode 100644 frontend/app/[locale]/auth/verify/page.tsx create mode 100644 frontend/app/[locale]/layout.tsx create mode 100644 frontend/app/[locale]/order/success/page.tsx create mode 100644 frontend/app/[locale]/page.tsx create mode 100644 frontend/app/[locale]/payment/success/page.tsx create mode 100644 frontend/components/LanguageSwitcher.tsx create mode 100644 frontend/i18n/request.ts create mode 100644 frontend/i18n/routing.ts create mode 100644 frontend/messages/de.json create mode 100644 frontend/messages/en.json create mode 100644 frontend/messages/es.json create mode 100644 frontend/scripts/glossary.json create mode 100644 frontend/scripts/translate.py diff --git a/.next/trace b/.next/trace new file mode 100644 index 00000000..4c674995 --- /dev/null +++ b/.next/trace @@ -0,0 +1 @@ +[{"name":"generate-buildid","duration":272,"timestamp":244518298649,"id":4,"parentId":1,"tags":{},"startTime":1775262331361,"traceId":"b3ef0d179e8acedf"},{"name":"load-custom-routes","duration":314,"timestamp":244518299029,"id":5,"parentId":1,"tags":{},"startTime":1775262331361,"traceId":"b3ef0d179e8acedf"},{"name":"create-dist-dir","duration":333,"timestamp":244518299363,"id":6,"parentId":1,"tags":{},"startTime":1775262331362,"traceId":"b3ef0d179e8acedf"},{"name":"clean","duration":358,"timestamp":244518300558,"id":7,"parentId":1,"tags":{},"startTime":1775262331363,"traceId":"b3ef0d179e8acedf"},{"name":"next-build","duration":1670851,"timestamp":244516630180,"id":1,"tags":{"buildMode":"default","version":"16.2.2","bundler":"turbopack","failed":true},"startTime":1775262329693,"traceId":"b3ef0d179e8acedf"}] diff --git a/.next/trace-build b/.next/trace-build new file mode 100644 index 00000000..a50695b1 --- /dev/null +++ b/.next/trace-build @@ -0,0 +1 @@ +[{"name":"next-build","duration":1670851,"timestamp":244516630180,"id":1,"tags":{"buildMode":"default","version":"16.2.2","bundler":"turbopack","failed":true},"startTime":1775262329693,"traceId":"b3ef0d179e8acedf"}] diff --git a/docs/LESSONS-LEARNED.md b/docs/LESSONS-LEARNED.md index 07c19aab..00040538 100644 --- a/docs/LESSONS-LEARNED.md +++ b/docs/LESSONS-LEARNED.md @@ -1070,3 +1070,19 @@ For this bug, the missing test was: "does `transcribe_lyrics()` return `lyrics_d **Fix:** (1) Root cause: Don't write `corrections_updated.json` unless the payload actually contains a `"corrections"` key. (2) Defensive: Both GCE and Cloud Run workers validate the downloaded JSON has the expected structure before processing, falling back to base result if not. **Key insight:** When a file's existence is used as a boolean signal ("corrections were updated"), never write it with empty/invalid content. The existence check and content processing must agree on what constitutes a valid file. Apply defense in depth: fix the writer AND validate in readers. + +### i18n: Keep Providers in Root Layout When Admin Pages Exist (Apr 2026) + +**Problem:** The Phase 1/2 i18n pattern (public-website, karaoke-decide) stripped the root `app/layout.tsx` bare and moved all providers into `app/[locale]/layout.tsx`. This doesn't work for karaoke-gen because admin pages at `app/admin/` sit outside the `[locale]` route segment and need ThemeProvider/TenantProvider. + +**Fix:** Keep shared providers (ThemeProvider, TenantProvider, ImpersonationBannerWrapper, ServiceWorkerRegistration, GoogleAnalytics) in root layout. Only add NextIntlClientProvider to `[locale]/layout.tsx`. Admin pages inherit root providers without locale context. + +**Key insight:** When adding `[locale]` routing to a project with routes that should NOT be locale-prefixed (admin, API, etc.), don't blindly follow the "strip root layout" pattern. Keep shared providers in root so all route segments can access them. + +### i18n: Mock next-intl in Jest by Loading en.json (Apr 2026) + +**Problem:** Adding `useTranslations` to components caused 27 test suites to fail — Jest can't handle ESM exports from `next-intl`, and even after fixing that, tests that assert on English text (e.g., `screen.getByText("Review Lyrics")`) fail because the mock returns translation keys instead of English strings. + +**Fix:** Mock `next-intl` in `jest.setup.js` with a function that loads the actual `messages/en.json` and resolves dotted key paths to real English strings. Tests see the same text users see, no test assertions need updating. The mock supports interpolation (`{count}`, ICU plurals). + +**Key insight:** For i18n refactors, make the test mock return real translations, not keys. This lets existing tests validate that the i18n wiring produces correct output without changing every assertion. The mock is ~20 lines and eliminates hundreds of test updates. diff --git a/docs/README.md b/docs/README.md index e2d81d81..9005f139 100644 --- a/docs/README.md +++ b/docs/README.md @@ -36,6 +36,7 @@ | **Community version detection** | Working (via karaokenerds.com) | | **Review session backup/restore** | Working (auto-save + restore UI) | | **Review reminder & auto-expiry** | Working (24h reminder, 48h cancel + refund) | +| **i18n / Multilingual (frontend)** | Working (next-intl, en/es/de, 1062 strings, [locale] routing) | ## Known Issues diff --git a/docs/archive/2026-04-03-i18n-phase3-plan.md b/docs/archive/2026-04-03-i18n-phase3-plan.md new file mode 100644 index 00000000..63a27082 --- /dev/null +++ b/docs/archive/2026-04-03-i18n-phase3-plan.md @@ -0,0 +1,215 @@ +# Plan: Karaoke-Gen i18n Multilingual (Phase 3) + +**Created:** 2026-04-03 +**Branch:** `feat/sess-20260403-1115-i18n-multilingual` +**Worktree:** `/Users/andrew/Projects/nomadkaraoke/karaoke-gen-i18n-multilingual` +**Status:** Draft + +## Context + +This is Phase 3 of the i18n multilingual initiative. Phases 1+2 shipped successfully for public-website (205 strings) and karaoke-decide (811 frontend + 47 backend strings). The patterns are proven — we're replicating them in karaoke-gen, the most complex project (many frontend surfaces + multi-layered backend). + +## Scope Decisions + +| Decision | Choice | Rationale | +|----------|--------|-----------| +| Admin pages (`/admin/*`) | **Exclude** from i18n | Internal-only, ~30% more strings for zero user impact. Can add later. | +| Tenant default locale | **Out of scope** | Orthogonal to user locale; user's localStorage/browser detection suffices | +| Hash routing compatibility | **No conflict** | Hash (`#/jobId/review`) is client-side only, preserved across locale changes | +| Providers in root layout | **Keep in root** | Unlike Phase 1/2, karaoke-gen has admin pages outside `[locale]` that need ThemeProvider/TenantProvider. Only NextIntlClientProvider moves to `[locale]/layout.tsx`. | + +## Architecture: Frontend Key Difference from Phase 1/2 + +karaoke-gen has admin pages at `app/admin/` that must NOT be under `[locale]` routing. So: + +- **Root `app/layout.tsx`**: Keeps ``, ``, ThemeProvider, TenantProvider, ImpersonationBannerWrapper, ServiceWorkerRegistration, GoogleAnalytics. Remove hardcoded `lang="en"`. +- **`app/[locale]/layout.tsx`**: Adds NextIntlClientProvider + inline `