infiplot-web/docs/i18n-implementation.md

InfiPlot i18n Implementation

Summary

A complete i18n infrastructure has been implemented for InfiPlot, enabling support for 22 languages:

• English (en)
• Simplified Chinese (zh-CN) - Source language
• Traditional Chinese Taiwan (zh-TW)
• Traditional Chinese Hong Kong (zh-HK)
• Japanese (ja)
• Korean (ko)
• Spanish (es)
• French (fr)
• German (de)
• Portuguese Brazil (pt-BR)
• Portuguese (pt)
• Russian (ru)
• Italian (it)
• Vietnamese (vi)
• Thai (th)
• Indonesian (id)
• Turkish (tr)
• Polish (pl)
• Dutch (nl)
• Ukrainian (uk)
• Hindi (hi)
• Czech (cs)

What Was Implemented

1. Core i18n Infrastructure (lib/i18n/)

• config.ts: Locale configuration, locale names, storage key management
• types.ts: TypeScript types for translation system
• utils.ts: Helper functions for nested value access, string formatting
• client.tsx: React context provider and useI18n() hook for client components
• server.ts: Server-side translation utilities for Next.js App Router
• index.ts: Main export file

2. Translation Files (lib/i18n/locales/)

• zh-CN.ts: Complete source translations (Chinese)
• en.ts: Reference English translations
• Additional locale files will be generated by the translation script

3. Translation Script (scripts/translate-i18n.mjs)

A Node.js script that:

• Reads the source zh-CN translation file
• Uses LLM APIs (Gemini or OpenAI-compatible) to translate to all target languages
• Preserves structure and handles special cases:
  • Placeholder variables ({{email}}, {n}, etc.)
  • HTML tags (<em>, <a>, etc.)
  • Select/message format syntax
  • Proper nouns (InfiPlot, GitHub, Google, etc.)
• Generates TypeScript locale files
• Updates client.tsx and server.ts imports automatically

Usage:

# With Gemini
node scripts/translate-i18n.mjs --provider gemini --api-key YOUR_KEY

# With OpenAI-compatible API
TEXT_API_KEY=your_key TEXT_BASE_URL=https://api.openai.com/v1 node scripts/translate-i18n.mjs --provider openai

4. Components Updated with i18n

• ✅ CustomForm.tsx
• ✅ DialogueHistoryModal.tsx
• ✅ AuthModal.tsx
• ✅ PlayCanvas.tsx
• ✅ SettingsModal.tsx
• ✅ page.tsx (home page)
• ✅ layout.tsx (I18nProvider wrapper)
• ✅ LanguageSwitcher.tsx (new component)

Current Status

Completed

1. i18n Infrastructure - All core files in lib/i18n/
2. Translation Files - zh-CN.ts (source) and en.ts (reference) complete
3. Stub Files - Created for all 20 target languages (fallback to en)
4. Component Integration - All UI components now use t() function
5. Language Switcher - Added to page header with dropdown UI
6. TypeScript Types - Full type safety for translation system

Remaining Work

1. Generate Actual Translations

   • Run the translation script to translate stub files
   • Review and edit generated translations for quality
   • Test with native speakers if possible

2. Update Metadata (optional)

   • Make page titles and descriptions dynamic based on locale
   • Update lang attribute on html element dynamically

Optional Enhancements

1. Server-Side Rendering Support

   • Implement locale detection from Accept-Language header
   • Add middleware for locale routing (e.g., /en/play, /zh-CN/play)
   • Cache translations for better performance

2. Date/Number Formatting

   • Add locale-specific formatting for dates, numbers, currencies
   • Use Intl.DateTimeFormat and Intl.NumberFormat

3. RTL Support

   • Currently no RTL locales, but infrastructure is in place
   • Add layout mirroring if needed for future RTL languages

4. Pluralization

   • Enhance formatTranslation to support ICU message format
   • Handle singular/plural forms

Translation Best Practices

When adding new strings:

1. Keep strings neutral where possible
2. Avoid culturally-specific references
3. Provide context for translators in comments
4. Test with longer strings (German, Russian can be 2-3x longer)
5. Keep placeholders consistent ({{varName}} or {varName})

API Keys Required

To generate translations, set one of:

• GEMINI_API_KEY for Google Gemini (recommended for cost)
• TEXT_API_KEY for OpenAI-compatible API
• TEXT_BASE_URL for custom OpenAI-compatible endpoints

Files Modified

New Files Created

• lib/i18n/ (entire directory)
  • config.ts - Locale configuration
  • client.tsx - React context provider
  • server.ts - Server-side utilities
  • utils.ts - Helper functions
  • locales/zh-CN.ts - Source translations
  • locales/en.ts - English reference
  • locales/zh-TW.ts - Traditional Chinese stub
  • locales/zh-HK.ts - Hong Kong Chinese stub
  • locales/ja.ts - Japanese stub
  • locales/ko.ts - Korean stub
  • locales/es.ts - Spanish stub
  • locales/fr.ts - French stub
  • locales/de.ts - German stub
  • locales/pt-BR.ts - Portuguese Brazil stub
  • locales/pt.ts - Portuguese stub
  • locales/ru.ts - Russian stub
  • locales/it.ts - Italian stub
  • locales/vi.ts - Vietnamese stub
  • locales/th.ts - Thai stub
  • locales/id.ts - Indonesian stub
  • locales/tr.ts - Turkish stub
  • locales/pl.ts - Polish stub
  • locales/nl.ts - Dutch stub
  • locales/uk.ts - Ukrainian stub
  • locales/hi.ts - Hindi stub
  • locales/cs.ts - Czech stub
• components/LanguageSwitcher.tsx - Language selector component
• scripts/translate-i18n.mjs - Translation script
• docs/i18n-implementation.md - This documentation

Modified Files

• app/layout.tsx - Added I18nProvider wrapper
• app/page.tsx - Added i18n to all strings and LanguageSwitcher
• components/CustomForm.tsx - Added i18n
• components/DialogueHistoryModal.tsx - Added i18n
• components/AuthModal.tsx - Added i18n
• components/PlayCanvas.tsx - Added i18n
• components/SettingsModal.tsx - Added i18n

TypeScript

All type definitions are in place. Run pnpm typecheck to verify.