@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) <noreply@anthropic.com>
12 KiB
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<html>,<body>, ThemeProvider, TenantProvider, ImpersonationBannerWrapper, ServiceWorkerRegistration, GoogleAnalytics. Remove hardcodedlang="en". app/[locale]/layout.tsx: Adds NextIntlClientProvider + inline<script>to setdocument.documentElement.lang. UsesgenerateStaticParamsfor locale pre-rendering.app/admin/layout.tsx: Unchanged — inherits root providers, no locale context needed.
PR Breakdown (4 PRs)
PR 1: Frontend Infrastructure + Page Migration (~250 strings)
Goal: Set up next-intl, [locale] routing, move all user-facing pages under locale prefix.
Create:
frontend/i18n/routing.ts— locale config,createNavigationfrontend/i18n/request.ts— message loading for next-intlfrontend/messages/en.json— all user-facing strings (namespaced:common,landing,dashboard,auth,payment,jobFlow,lyricsReview,instrumentalReview,audioEditor,audioSearch,credits,feedback,push,status)frontend/app/[locale]/layout.tsx— NextIntlClientProvider,generateStaticParams, lang scriptfrontend/app/[locale]/page.tsx— landing page (moved fromapp/page.tsx)frontend/app/[locale]/app/page.tsx— dashboardfrontend/app/[locale]/app/jobs/[[...slug]]/page.tsx— job routerfrontend/app/[locale]/app/jobs/[[...slug]]/client.tsx— job client componentfrontend/app/[locale]/auth/verify/page.tsx— magic link verifyfrontend/app/[locale]/payment/success/page.tsx— payment successfrontend/app/[locale]/order/success/page.tsx— order successfrontend/components/LanguageSwitcher.tsx— dropdown in headerfrontend/scripts/translate.py— copy from karaoke-decidefrontend/scripts/glossary.json— extended with karaoke-gen terms
Modify:
frontend/app/layout.tsx— removelang="en"from<html>, keep all providersfrontend/app/page.tsx— replace with client-side locale redirect (localStorage > navigator.language > 'en')frontend/next.config.mjs— wrap withcreateNextIntlPluginfromnext-intl/pluginfrontend/package.json— addnext-intlfrontend/lib/api.ts— addAccept-Languageheader viagetLocaleFromPath()frontend/components/app-header.tsx— add LanguageSwitcher
String extraction in this PR: Extract ALL user-facing strings from ALL components (landing, dashboard, job flow, lyrics review, instrumental review, audio editor, audio search, credits, feedback, push, auth, status, common). Write the complete en.json upfront so PR 2 is just wiring useTranslations() into components.
Why extract all strings in PR 1? The en.json file defines the complete translation surface. Having it complete lets us run translate.py once to generate es.json/de.json, and subsequent PRs just add useTranslations() calls without needing to re-translate.
PR 2: Component i18n Wiring (~50 components)
Goal: Wire useTranslations() into all user-facing components.
Components to convert (by area):
Job creation (~14 files):
components/job/GuidedJobFlow.tsx,TenantJobFlow.tsxcomponents/job/steps/SongInfoStep.tsx,AudioSourceStep.tsx,CustomizeStep.tsx,VisibilityStep.tsxcomponents/job/JobCard.tsx,JobActions.tsx,OutputLinks.tsx,JobSubmission.tsxcomponents/job/ThemeSelector.tsx,TitleCardPreview.tsx,EditTrackModal.tsx,CommunityVersionBanner.tsx
Lyrics review (~20 files):
components/lyrics-review/Header.tsx,LyricsAnalyzer.tsx,GuidancePanel.tsx,TranscriptionView.tsxcomponents/lyrics-review/EditActionBar.tsx,EditFeedbackBar.tsx,EditWordList.tsxcomponents/lyrics-review/ModeSelector.tsx,ReferenceView.tsx,ReferenceEmptyState.tsxcomponents/lyrics-review/SessionRestoreDialog.tsx,PreviewVideoSection.tsx,GapNavigator.tsxcomponents/lyrics-review/modals/*.tsx(8 files)components/lyrics-review/synchronizer/*.tsx(4 files)
Instrumental review (~7 files):
components/instrumental-review/InstrumentalSelector.tsx,InstrumentalSelectorEmbedded.tsxcomponents/instrumental-review/InstrumentalGuidancePanel.tsx,SelectionOptions.tsxcomponents/instrumental-review/StemComparison.tsx,CustomUpload.tsx,MuteRegionEditor.tsx
Other (~10 files):
components/audio-editor/AudioEditor.tsx,AudioEditRestoreDialog.tsxcomponents/audio-search/AudioSearchDialog.tsxcomponents/credits/BuyCreditsDialog.tsxcomponents/feedback/FeedbackDialog.tsxcomponents/auth/AuthDialog.tsx,AuthStatus.tsxcomponents/push-notification-prompt.tsx,push-settings.tsxcomponents/TenantLandingPage.tsx,WarmingUpLoader.tsx,status-badge.tsx
Pattern: Each component gets const t = useTranslations('namespace') and replaces hardcoded strings with t('key').
PR 3: Backend i18n Infrastructure + Route Localization (~150-200 strings)
Goal: Add backend/i18n.py, translation files, convert all route files.
Create:
backend/i18n.py—t(locale, key, **kwargs),get_locale_from_request(request),get_locale_prefix(locale)(copy from karaoke-decide)backend/translations/en.json— all backend stringsbackend/translations/es.json,de.json— via translate.py
Modify:
backend/models/user.py— addlocale: Optional[str] = Noneto User modelbackend/services/user_service.py— persist locale on create/update- All user-facing route files (10 files):
auth.py,jobs.py,review.py,audio_search.py,users.py,push.py,file_upload.py,catalog.py,themes.py,tenant.py backend/main.py— localizeInsufficientCreditsErrorhandler
Pattern:
from backend.i18n import t, get_locale_from_request
locale = get_locale_from_request(request)
raise HTTPException(status_code=404, detail=t(locale, "jobs.notFound"))
PR 4: Email + Push Notification Localization (~50-80 strings)
Goal: Localize all 5 email types and 3 push notification types.
Modify:
backend/services/email_service.py— pass locale to all email methods, uset()for subjects/headings/buttonsbackend/services/template_service.py— locale-aware GCS template paths (templates/{locale}/...)backend/services/job_notification_service.py— fetch user locale, pass to email service; localize URL prefixesbackend/services/push_notification_service.py— locale-aware notification titles/bodies
Add to translations: emails.* and push.* namespaces in backend translation files.
Implementation Order
PR 1 (Frontend Infra) ──→ PR 2 (Component Wiring)
│
└──→ PR 3 (Backend Infra) ──→ PR 4 (Emails + Push)
PRs 2 and 3 can be developed in parallel after PR 1 lands.
Key Technical Details
Accept-Language Header (frontend → backend)
// frontend/lib/api.ts
function getLocaleFromPath(): string {
if (typeof window === 'undefined') return 'en';
const match = window.location.pathname.match(/^\/(en|es|de)\//);
return match ? match[1] : 'en';
}
Added to getAuthHeaders() so every API call includes locale.
User Locale Persistence
- Frontend:
localStorage.setItem('locale', newLocale)on language switch - Backend:
User.localefield in Firestore (gen_userscollection), set on magic link verify fromAccept-Language, updated on explicit language change - Emails/push: Read
User.localefrom Firestore, fallback to'en'
Static Export with Locale Routing
generateStaticParams on [locale]/layout.tsx returns [{locale:'en'},{locale:'es'},{locale:'de'}]. Combined with output: 'export' and trailingSlash: true, Next.js generates /en/, /es/, /de/ directories — compatible with Cloudflare Pages.
Backend-Generated URLs
All backend URLs that point to frontend must include locale prefix:
f"{frontend_url}/{get_locale_prefix(user_locale)}/app/jobs#{job_id}/review"
Testing Strategy
Unit Tests
- Backend: Test
i18n.py—t()function with valid/invalid keys, interpolation, fallback to English, unsupported locale handling - Backend: Test locale extraction from
Accept-Languageheader - Frontend: Jest tests for
getLocaleFromPath()helper
Integration Tests
- Backend: Verify routes return localized error messages when
Accept-Language: esis sent - Backend: Verify emails are sent with correct locale strings
E2E Tests (Playwright)
- Production E2E: Navigate to
/es/and/de/, verify page renders in correct language - Production E2E: Switch language via LanguageSwitcher, verify localStorage persistence and page reload
- Production E2E: Verify root
/redirects to correct locale based on browser language
Manual Verification
Convert to automated E2E tests per TESTING.md guidelines:
- Verify static export generates all 3 locale directories
- Verify admin pages still work at
/admin/(no locale prefix) - Verify tenant subdomains work with locale routing
Estimated String Counts
| Area | Strings | PR |
|---|---|---|
| Frontend: landing, dashboard, auth, payment | ~100 | 1 |
| Frontend: common (buttons, errors, loading) | ~50 | 1 |
| Frontend: job flow | ~80 | 1 (extracted), 2 (wired) |
| Frontend: lyrics review | ~120 | 1 (extracted), 2 (wired) |
| Frontend: instrumental review | ~40 | 1 (extracted), 2 (wired) |
| Frontend: other components | ~60 | 1 (extracted), 2 (wired) |
| Frontend total | ~450-550 | |
| Backend: route messages | ~150-200 | 3 |
| Backend: emails + push | ~50-80 | 4 |
| Backend total | ~200-280 | |
| Grand total | ~650-830 |
Open Questions
- Should we store locale preference in a cookie too (for pre-auth pages where we don't have a user document)?
- The landing page (
app/page.tsx) currently has a lot of marketing content — confirm it should be fully translated vs. just the chrome - Any karaoke-gen-specific glossary terms beyond what's in karaoke-decide's glossary? (e.g., "stem separation", "instrumental track", "lyrics review")
Rollback Plan
Each PR is independently revertable:
- PR 1: Revert moves pages back to non-locale paths. Admin pages unaffected.
- PR 3: Revert removes
i18n.pyand translation files. Routes return English strings. - Cloudflare Pages: Previous deployment is one click to restore.