feat(frontend): Internationalization (i18n) with react-i18next

[jonasyr]

🎯 Issue Type

• ✨ Feature - New functionality
• 🔧 Enhancement - Improvement of existing functionality

📋 Description

Problem/Need

GitRay currently only supports German text hardcoded in components. To reach international users and improve accessibility, we need multi-language support for 7-10 languages with automatic detection and user preference persistence.

Expected Behavior

• Support for 7-10 languages (starting with DE + EN)
• Language selector in Settings drawer
• Automatic browser language detection
• User language preference persists across sessions
• All UI text properly translated (no hardcoded strings)
• Pluralization support (e.g., "1 commit" vs "5 commits")
• Language-specific date/number formatting
• TypeScript type safety for translation keys

Current Behavior

• All text hardcoded in German/English mix
• No language switching capability
• No internationalization framework

🔄 Steps to Reproduce

This is a feature implementation. To test completion:

1. Clone branch feature/i18n-implementation
2. Run npm install and npm run dev
3. Open Settings drawer → verify language selector visible
4. Switch between languages → verify all text updates
5. Reload page → verify language preference persists
6. Test browser language detection (change browser language)
7. Test pluralization with different counts
8. Verify date formatting changes per language
9. Check for any untranslated strings (hardcoded text)

🎨 Mockups/Screenshots

Language selector in Settings drawer:

Settings
├── Theme: [Light | Dark | System]
└── Language: [🇩🇪 Deutsch | 🇬🇧 English | 🇪🇸 Español | ...]

Translation file structure:

{
  "header.menu": "Menü",
  "landing.hero.title": "Analysiere dein Repository",
  "dashboard.heatmap.commits": "{{count}} Commit",
  "dashboard.heatmap.commits_plural": "{{count}} Commits"
}

🧪 Acceptance Criteria

• react-i18next installed and configured
• Translation file structure created (de, en, es, fr, it, pt, pl, nl, ja)
• Language selector added to Settings drawer
• All components updated to use t() function (no hardcoded strings)
• Automatic browser language detection working
• Language preference persists in localStorage
• Pluralization working correctly
• Date/number formatting respects selected language
• TypeScript types for translation keys working
• German + English translations complete and reviewed
• Additional 5-8 languages added (at least structure)
• No translation keys visible in UI (all resolved)
• Tests updated for i18n (component rendering in multiple languages)
• Bundle size increase < 50KB
• Documentation updated with translation workflow
• Code reviewed and approved

🛠 Technical Details

Affected Files/Components

New Files:

src/i18n/
├── config.ts           # i18next configuration
└── types.ts            # TypeScript type definitions

public/locales/
├── de/
│   ├── common.json     # Header, Footer, Settings, Toasts
│   ├── landing.json    # Landing page specific
│   └── dashboard.json  # Dashboard specific
├── en/
│   ├── common.json
│   ├── landing.json
│   └── dashboard.json
└── [es, fr, it, pt, pl, nl, ja]/

Updated Components (add useTranslation hook):

• Header.tsx - Menu, news, signOut buttons
• Footer.tsx - Links
• SettingsDrawer.tsx - Add language selector, translate theme labels
• LandingPage.tsx - Hero, buttons, placeholders
• DashboardPage.tsx - Tab labels
• ActivityHeatmap.tsx - Filter labels, commit counts
• CommitList.tsx - Column headers
• InfoModal.tsx - Modal content
• NewsDrawer.tsx - News titles
• App.tsx - Toast messages

Updated Files:

• main.tsx - Import i18n config before App

Dependencies

New packages:

npm install i18next react-i18next i18next-browser-languagedetector
# Optional for better performance:
npm install i18next-http-backend

Depends on:

• #[ui-migration-issue-number] - MUST be completed and merged first
• All UI components must exist before adding translations

Blocks:

• Nothing

Breaking Changes

• No, backward compatible change
• New feature, doesn't affect existing functionality

🏷 Categorization

Scope

• scope:frontend - Frontend/UI changes

Priority

• prio:high - Important feature

Effort

• effort:medium - 2-8 hours (2 days estimated)

🌍 Environment

Development:

• OS: Cross-platform (Windows, macOS, Linux)
• Browser: Chrome 120+, Firefox 121+, Safari 17+
• Node Version: 18+ required
• Repo Branch: feature/i18n-implementation (create from main AFTER UI migration merged)

🔗 Related Issues/PRs

• Blocked by: #[ui-migration-issue-number] - UI Migration (MUST be merged first)
• Relates to: Accessibility improvements

📝 Additional Notes

Target Languages & Rollout

Phase 1: MVP (Week 1)

• 🇩🇪 German (Deutsch) - Professional translation
• 🇬🇧 English - Professional translation

Phase 2: European Expansion (Week 2-3)

• 🇪🇸 Spanish (Español)
• 🇫🇷 French (Français)
• 🇮🇹 Italian (Italiano)
• 🇵🇹 Portuguese (Português)

Phase 3: Global (Week 4+)

• 🇵🇱 Polish (Polski)
• 🇳🇱 Dutch (Nederlands)
• 🇯🇵 Japanese (日本語)
• 🇨🇳 Chinese (中文) - Optional

Implementation Timeline (2 days)

Day 1 (Morning): Setup, install dependencies, create folder structure, i18n config, TypeScript types
Day 1 (Afternoon): Create English + German translation files, update first components (Header, Footer, Landing)
Day 2 (Morning): Update remaining components (Dashboard, Heatmap, Lists), add language selector
Day 2 (Afternoon): Add remaining language structures, testing, documentation

Week 2+: Professional translation review, community translations for additional languages

Translation Strategy (Cost-Effective Hybrid Approach)

Recommended: Hybrid Approach

• Core languages (DE, EN): Professional translation (€600-1,200)
• Additional languages: DeepL API + native speaker review
• Total cost: €800-1,500
• Quality: Good to very high
• Scalable: Yes ✅

Alternatives:

• DIY: ~40 hours developer time, variable quality
• Full Professional: €2,100-€4,200 (7 languages), highest quality

Content Volume

• ~90 translation keys per language
• ~500 words per language
• Total for 7 languages: ~3,500 words

Documentation

Complete i18n implementation guide available:

• docs/migration-plan/I18N_IMPLEMENTATION.md - Full guide (30 pages)
• Translation file templates
• Component update examples
• Maintenance workflow
• Adding new languages process

Key Technical Decisions

Why react-i18next?

• Industry standard (11k+ stars)
• Small bundle size (12KB vs 45KB for react-intl)
• Perfect TypeScript support
• Built-in lazy loading
• Excellent Vite support

Namespace Organization:

• common.json - Used everywhere (header, footer, toasts)
• landing.json - Landing page specific
• dashboard.json - Dashboard specific
• Benefit: Code splitting, better performance

Key Naming Convention:

{
  "section.component.element": "Text",
  "header.menu": "Menü",
  "landing.hero.title": "Analysiere dein Repository"
}

Performance Impact

• Initial bundle increase: ~30KB (with lazy loading)
• Language files load on demand
• Minimal impact on app performance
• All languages cached in localStorage

Maintenance Workflow

1. Add new text to English files first (source of truth)
2. Copy structure to other language files
3. Translate or mark as TODO
4. Test in all languages
5. Quarterly audit for completeness

Testing Strategy

• Component tests with multiple languages
• Language switching tests
• Pluralization tests
• Date formatting tests
• Translation key existence tests
• No hardcoded strings validation

✅ Checklist for Reviewer

• Issue is clearly and understandably formulated
• Acceptance criteria are measurable
• Labels and priority are set
• Technical feasibility is given
• UI Migration is completed and merged (hard requirement)
• Dependencies listed and installable
• Timeline is realistic (2 days confirmed)
• Translation strategy decided (DIY/Professional/Hybrid)
• Budget approved for translations (if using professional)
• Documentation linked and accessible