Internationalization (i18n)

The application uses i18next and react-i18next for internationalization, following industry-standard frontend translation management.

Overview

Translations are stored as JSON files in the codebase, providing:

• Zero latency (instant loading)
• Type safety with TypeScript
• Git-based workflow (translations versioned with code)
• Offline development support
• Reliable, no network dependencies

Project Structure

apps/web/src/
├── i18n/
│   ├── config.ts          # i18next configuration
│   └── types.ts           # TypeScript type definitions
└── locales/
    ├── en/                # English (default)
    ├── de/                # German
    ├── es/                # Spanish
    ├── fr/                # French
    ├── pt/                # Portuguese
    ├── zh-CN/             # Simplified Chinese
    └── pseudo/            # Pseudo locale (debug)
        # Each directory contains:
        ├── common.json    # Shared translations (buttons, errors, admin, discord, theme)
        ├── guild.json     # Guild-specific translations
        ├── character.json # Character-specific translations
        ├── roster.json    # Roster-specific translations
        ├── auth.json      # Login and account settings
        ├── posts.json     # Guild posts (TOC)
        └── events.json    # Events (types, roster, signup, manage, confirmations)

Supported Languages

Code	Language	Native Name
en	English	English
de	German	Deutsch
es	Spanish	Español
fr	French	Français
pt	Portuguese	Português
zh-CN	Simplified Chinese	中文 (简体)
pseudo	Debug	🔤 Pseudo

Configuration

Main Setup (apps/web/src/i18n/config.ts)

import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';
import LanguageDetector from 'i18next-browser-languagedetector';

i18n
  .use(LanguageDetector) // Auto-detect from browser
  .use(initReactI18next) // React integration
  .init({
    resources,
    defaultNS: 'common',
    fallbackLng: 'en',
    detection: {
      order: ['localStorage', 'navigator'],
      caches: ['localStorage'],
    },
  });

TypeScript Types (apps/web/src/i18n/types.ts)

Provides type-safe translation keys with autocomplete in your IDE.

Basic Usage

Simple Translations

import { useTranslation } from 'react-i18next';

function MyComponent() {
  const { t } = useTranslation();

  return (
    <div>
      <h1>{t('app.name')}</h1>
      <button>{t('actions.save')}</button>
      <button>{t('actions.cancel')}</button>
    </div>
  );
}

Namespaced Translations

// Use guild namespace
const { t } = useTranslation('guild');

return (
  <div>
    <h2>{t('title')}</h2>
    <p>{t('messages.created')}</p>
  </div>
);

Multiple Namespaces

const { t } = useTranslation(['common', 'guild']);

return (
  <div>
    <button>{t('common:actions.save')}</button>
    <p>{t('guild:messages.created')}</p>
  </div>
);

Advanced Features

Interpolation (Dynamic Values)

// Translation JSON
{
  "guild": {
    "createdBy": "Created by {{name}}",
    "memberCount": "{{count}} members"
  }
}

// Component
const { t } = useTranslation('guild');
<p>{t('createdBy', { name: 'John' })}</p>
<p>{t('memberCount', { count: 42 })}</p>

Pluralization

i18next automatically handles plurals:

{
  "member_one": "{{count}} member",
  "member_other": "{{count}} members"
}

const { t } = useTranslation('guild');
<p>{t('member', { count: 1 })}</p>  // "1 member"
<p>{t('member', { count: 5 })}</p>  // "5 members"

Change Language

const { i18n } = useTranslation();

const changeLanguage = (lng: string) => {
  i18n.changeLanguage(lng);
};

<button onClick={() => changeLanguage('en')}>English</button>
<button onClick={() => changeLanguage('es')}>Español</button>

Translation File Structure

Common (locales/en/common.json)

Shared translations used across the entire app:

• Actions (save, cancel, delete, etc.)
• Validation messages
• Error messages
• Status labels

Domain-Specific Files

Each major feature has its own namespace:

• guild.json - Guild management
• character.json - Character management
• roster.json - Roster operations
• auth.json - Login, callback, account settings
• posts.json - Guild posts (create, edit, delete, history)
• events.json - Events (types, statuses, manage actions, roster, voice attendance, confirmations)

Benefits:

• Smaller file sizes (only load what you need)
• Better organization
• Easier to maintain
• Multiple people can work on different namespaces

Backend API and translation keys

When the API returns errors, it can include a messageKey (and optional messageParams) so the frontend can show a translated message. See API Translation Keys for the convention and how to consume messageKey in toasts and error UIs.

Integration with Toast Notifications

import { useTranslation } from 'react-i18next';
import { useToastMutations } from '@/hooks/useToastMutations';

function CreateGuild() {
  const { t } = useTranslation('guild');
  const { toastPromise } = useToastMutations();

  const handleCreate = async (data) => {
    await toastPromise(createGuild(data).unwrap(), {
      loading: t('messages.creating'),
      success: t('messages.created'),
      error: t('messages.createError'),
    });
  };
}

Adding a New Language

1. Create Translation Files

mkdir -p apps/web/src/locales/ja
cp apps/web/src/locales/en/*.json apps/web/src/locales/ja/

2. Translate JSON Files

Edit each .json file in locales/ja/ with Japanese translations.

3. Update i18n Config

// apps/web/src/i18n/config.ts
import commonJA from '../locales/ja/common.json';
import guildJA from '../locales/ja/guild.json';
// ... other imports (one per namespace)

export const resources = {
  en: {
    /* ... */
  },
  // existing languages ...
  ja: {
    common: commonJA,
    guild: guildJA,
    character: characterJA,
    roster: rosterJA,
    auth: authJA,
    posts: postsJA,
    events: eventsJA,
  },
} as const;

4. Add to LanguageSelector

// apps/web/src/components/LanguageSelector.tsx
const LANGUAGES = [
  // ... existing entries
  { code: 'ja', label: '日本語' },
] as const;

Best Practices

DO ✅

• Extract all user-facing strings - Even English text should use t()
• Use meaningful keys - guild.messages.created not msg1
• Group related keys - Use nested objects for organization
• Use interpolation - t('welcome', { name }) instead of string concatenation
• Namespace by feature - Separate guild, character, roster
• Add context - Use namespaces like guild:actions.delete for clarity

DON'T ❌

• Hard-code strings - Even in English, use translation keys
• Concatenate strings - Use interpolation instead
• Duplicate keys - Share common translations via common namespace
• Use generic keys - button1 is meaningless, use actions.save
• Mix languages - Keep one language per file
• Nest too deeply - 2-3 levels max for readability

Type Safety

TypeScript provides autocomplete and validation:

const { t } = useTranslation('guild');

t('messages.created'); // ✅ Valid key - autocomplete works
t('messages.invalid'); // ❌ TypeScript error - key doesn't exist

Language Detection

The app auto-detects user language:

1. localStorage - Previously selected language
2. Browser navigator - Browser language setting
3. Fallback - English (en)

Users can manually change language, which is saved to localStorage.

Performance

• Zero network requests - All translations bundled with app
• Code splitting - Only load namespaces you use
• Instant language switching - No loading states needed
• Caching - Selected language persists across sessions

Migration Strategy

From Hard-Coded Strings

// Before
<button>Create Guild</button>
<p>Guild created successfully!</p>

// After
<button>{t('guild:create')}</button>
<p>{t('guild:messages.created')}</p>

Extract Incrementally

1. Start with high-traffic pages (dashboard, guild list)
2. Extract as you touch files (no need for big-bang migration)
3. Search for hard-coded strings: grep -r "Guild created" src/

Translation Management Services (Future)

When you scale to 3+ languages and need non-developers to translate:

Recommended Services:

• Lokalise - Developer-friendly, GitHub integration
• Crowdin - Community translations, good for open source
• Phrase - Enterprise-grade with automation

Workflow:

1. Developer adds key: t('guild.newFeature')
2. Service detects missing translations
3. Translators fill in via web UI
4. Service creates PR with updated JSON files
5. Merge and deploy

Troubleshooting

Translation Not Showing

1. Check key exists in JSON file
2. Verify namespace is loaded in component
3. Check i18n initialization in main.tsx
4. Look for typos in translation key

TypeScript Errors

1. Restart TypeScript server in IDE
2. Ensure i18n/types.ts is properly configured
3. Verify translation files are imported in i18n/config.ts

Language Not Changing

1. Check i18n.changeLanguage() is called correctly
2. Verify language code matches resources (en, es, etc.)
3. Check browser console for i18n errors
4. Clear localStorage if old language is stuck

Examples

See apps/web/src/examples/I18nExamples.tsx for complete usage examples.

Related

• i18next Documentation
• react-i18next Documentation
• Toast Notifications Guide