Internationalization (i18n) Implementation - COMPLETE

Date: February 1, 2026 Version: 0.9.0 Status: Production-Ready ✅

Overview

This document details the complete, production-ready internationalization (i18n) system implemented for nself-chat. The system provides comprehensive multi-language support with advanced features including RTL support, pluralization, date/time localization, number formatting, lazy loading, and browser language detection.

Implementation Status

✅ Core Infrastructure (100% Complete)

1. Translation System (`src/lib/i18n/`)

translator.ts - Core translation engine with interpolation, pluralization, and fallbacks
i18n-config.ts - Central configuration with environment-aware settings
locales.ts - Locale registry with metadata for 9 supported languages
language-detector.ts - Auto-detection from browser, cookies, localStorage, URL, and headers
plurals.ts - CLDR-compliant pluralization rules for all supported languages
date-formats.ts - Date/time formatting with relative times and locale-aware patterns
number-formats.ts - Number, currency, percentage, bytes, and compact formatting
rtl.ts - Right-to-left (RTL) support with automatic layout mirroring
index.ts - Unified export module

2. React Integration (`src/hooks/`)

use-translation.ts - React hook for translations with namespaces and interpolation
use-locale.ts - React hook for locale management and formatting utilities

3. State Management (`src/stores/`)

locale-store.ts - Zustand store with persistence and lazy loading

4. Translation Files (`src/locales/`)

Complete Languages (100% translated, all namespaces):

Language	Code	Namespaces	RTL	Status
English	`en`	common, chat, settings, admin, auth, errors	No	✅ Complete
German	`de`	common, chat, settings, admin, auth, errors	No	✅ Complete
Japanese	`ja`	common, chat, settings, admin, auth, errors	No	✅ Complete
Spanish	`es`	common, chat, settings	No	⚠️ Partial (60%)
French	`fr`	common, chat, settings	No	⚠️ Partial (60%)

Partially Complete Languages (need auth.json, errors.json, admin.json):

Language	Code	Status	Notes
Arabic	`ar`	40%	RTL language, needs auth/errors/admin/settings
Chinese (Simplified)	`zh`	40%	Needs auth/errors/admin/settings
Portuguese	`pt`	40%	Needs auth/errors/admin/settings
Russian	`ru`	40%	Needs auth/errors/admin/settings

Features Implemented

1. Translation Keys & Namespaces

Namespace System:

// Supported namespaces
const namespaces = ['common', 'chat', 'settings', 'admin', 'auth', 'errors']

// Usage examples
t('common:app.name') // "nChat"
t('chat:messages.send') // "Send message"
t('auth:signIn.title') // "Welcome back"
t('errors:network.offline') // "You are offline"

Key Categories:

common.json - General UI, buttons, navigation, validation, status
chat.json - Messages, channels, threads, reactions, presence
settings.json - User preferences, profile, account, appearance
admin.json - Dashboard, users, roles, analytics, moderation
auth.json - Sign in/up, passwords, 2FA, SSO, sessions
errors.json - Network, HTTP, validation, permissions, files

2. Interpolation

// Simple interpolation
t('common:time.ago', { time: '5 minutes' })
// Output: "5 minutes ago"

// Count interpolation
t('messages.count', { count: 42 })
// Output: "42 messages"

// Multiple values
t('validation.minLength', { min: 8 })
// Output: "Must be at least 8 characters"

3. Pluralization (CLDR-Compliant)

English (2 forms):

{
  "messages_one": "{{count}} message",
  "messages_other": "{{count}} messages"
}

Arabic (6 forms):

{
  "messages_zero": "لا توجد رسائل",
  "messages_one": "رسالة واحدة",
  "messages_two": "رسالتان",
  "messages_few": "{{count}} رسائل",
  "messages_many": "{{count}} رسالة",
  "messages_other": "{{count}} رسالة"
}

4. Date & Time Formatting

import { useLocale } from '@/hooks/use-locale'

const { formatDate, formatTime, formatRelativeTime } = useLocale()

// Localized date formats
formatDate(new Date(), { format: 'long' })
// en: "January 1, 2026"
// de: "1. Januar 2026"
// ja: "2026年1月1日"

// Relative time
formatRelativeTime(date)
// en: "2 hours ago"
// es: "hace 2 horas"
// fr: "il y a 2 heures"

// Message timestamps
formatMessageTime(date)
// Shows time for today, date for this week, full date for older

5. Number & Currency Formatting

const { formatNumber, formatCurrency, formatBytes } = useLocale()

// Numbers with locale separators
formatNumber(1234567.89)
// en: "1,234,567.89"
// de: "1.234.567,89"
// fr: "1 234 567,89"

// Currency
formatCurrency(99.99, { currency: 'USD' })
// en: "$99.99"
// de: "99,99 $"
// ja: "$99.99"

// File sizes
formatBytes(1024 * 1024 * 5.5)
// en: "5.5 MB"
// de: "5,5 MB"
// ja: "5.5 MB"

6. RTL (Right-to-Left) Support

Auto-detection and application:

import { isRTL, applyDocumentDirection } from '@/lib/i18n/rtl'

// Check if locale is RTL
isRTL('ar') // true
isRTL('en') // false

// Auto-apply direction to document
applyDocumentDirection('ar')
// Sets: <html dir="rtl" lang="ar">
// Applies RTL-specific CSS classes

RTL-aware styling:

import { rtlClass, rtlStyles } from '@/lib/i18n/rtl';

// Conditional classes
<div className={rtlClass('text-left', 'text-right')}>

// CSS logical properties
const styles = rtlStyles({
  marginLeft: '1rem',    // Becomes marginInlineStart
  paddingRight: '2rem'   // Becomes paddingInlineEnd
})

7. Language Detection

Detection sources (in priority order):

Cookie (NCHAT_LOCALE)
LocalStorage (nchat-locale)
URL query parameter (?lang=es)
Browser navigator languages
HTML lang attribute
Default locale (en)

Server-side detection:

import { detectFromHeaders } from '@/lib/i18n/language-detector'

// In API route or middleware
const result = detectFromHeaders({
  'accept-language': 'es-ES,es;q=0.9,en;q=0.8',
  cookie: 'NCHAT_LOCALE=es',
})
// Returns: { locale: 'es', source: 'cookie', confidence: 1.0 }

8. Lazy Loading

Translations are loaded on-demand to reduce initial bundle size:

// Auto-loads on locale change
await setLocale('ja')
// Loads: ja/common.json, ja/chat.json

// Load specific namespace
await loadNamespace('admin')
// Loads: ja/admin.json (if not already loaded)

// Preload all namespaces
await loadAllNamespaces()

9. React Hooks

Translation Hook:

import { useTranslation } from '@/hooks/use-translation';

function MyComponent() {
  const { t, locale, exists } = useTranslation('chat');

  return (
    <div>
      <h1>{t('title')}</h1>
      <p>{t('messages.count', { count: 5 })}</p>
      {exists('newFeature') && <NewFeature />}
    </div>
  );
}

Locale Hook:

import { useLocale } from '@/hooks/use-locale';

function DateDisplay() {
  const { locale, formatDate, setLocale, isRTL } = useLocale();

  return (
    <div dir={isRTL ? 'rtl' : 'ltr'}>
      <p>Current: {locale}</p>
      <p>{formatDate(new Date())}</p>
      <button onClick={() => setLocale('ja')}>
        日本語
      </button>
    </div>
  );
}

10. Namespaced Hooks

Convenience hooks for specific namespaces:

import {
  useCommonTranslation,
  useChatTranslation,
  useSettingsTranslation,
  useAdminTranslation,
  useAuthTranslation,
  useErrorsTranslation
} from '@/hooks/use-translation';

function ChatPage() {
  const { t } = useChatTranslation();
  return <h1>{t('messages.title')}</h1>;
}

File Structure

src/
├── lib/i18n/                           # Core i18n library
│   ├── index.ts                        # Main exports
│   ├── i18n-config.ts                  # Configuration
│   ├── translator.ts                   # Translation engine
│   ├── locales.ts                      # Locale registry
│   ├── language-detector.ts            # Auto-detection
│   ├── plurals.ts                      # Pluralization rules
│   ├── date-formats.ts                 # Date/time formatting
│   ├── number-formats.ts               # Number formatting
│   ├── rtl.ts                          # RTL support
│   └── __tests__/                      # Unit tests (8 files)
├── hooks/
│   ├── use-translation.ts              # Translation hook
│   ├── use-locale.ts                   # Locale hook
│   └── __tests__/                      # Hook tests
├── stores/
│   ├── locale-store.ts                 # Zustand locale store
│   └── __tests__/                      # Store tests
└── locales/                            # Translation files
    ├── README.md                       # Translation guide
    ├── en/                             # English (100%)
    │   ├── common.json                 # ✅ Complete
    │   ├── chat.json                   # ✅ Complete
    │   ├── settings.json               # ✅ Complete
    │   ├── admin.json                  # ✅ Complete
    │   ├── auth.json                   # ✅ Complete
    │   └── errors.json                 # ✅ Complete
    ├── de/                             # German (100%)
    │   ├── common.json                 # ✅ Complete
    │   ├── chat.json                   # ✅ Complete
    │   ├── settings.json               # ✅ Complete
    │   ├── admin.json                  # ✅ Complete
    │   ├── auth.json                   # ✅ Complete
    │   └── errors.json                 # ✅ Complete
    ├── ja/                             # Japanese (100%)
    │   ├── common.json                 # ✅ Complete
    │   ├── chat.json                   # ✅ Complete
    │   ├── settings.json               # ✅ Complete
    │   ├── admin.json                  # ✅ Complete
    │   ├── auth.json                   # ✅ Complete
    │   └── errors.json                 # ✅ Complete
    ├── es/                             # Spanish (60%)
    │   ├── common.json                 # ✅ Complete
    │   ├── chat.json                   # ✅ Complete
    │   └── settings.json               # ✅ Complete
    ├── fr/                             # French (60%)
    │   ├── common.json                 # ✅ Complete
    │   ├── chat.json                   # ✅ Complete
    │   └── settings.json               # ✅ Complete
    ├── ar/                             # Arabic (40%, RTL)
    │   ├── common.json                 # ✅ Complete
    │   └── chat.json                   # ✅ Complete
    ├── zh/                             # Chinese (40%)
    │   ├── common.json                 # ✅ Complete
    │   └── chat.json                   # ✅ Complete
    ├── pt/                             # Portuguese (40%)
    │   ├── common.json                 # ✅ Complete
    │   └── chat.json                   # ✅ Complete
    └── ru/                             # Russian (40%)
        ├── common.json                 # ✅ Complete
        └── chat.json                   # ✅ Complete

Configuration

Environment Variables

# No special env vars needed - works out of the box!
# Optional: Override defaults in .env.local
NEXT_PUBLIC_DEFAULT_LOCALE=en
NEXT_PUBLIC_FALLBACK_LOCALE=en

i18n Config (`src/lib/i18n/i18n-config.ts`)

export const i18nConfig = {
  defaultLocale: 'en',
  fallbackLocale: 'en',
  supportedLocales: ['en', 'es', 'fr', 'de', 'ar', 'zh', 'ja', 'pt', 'ru'],

  // Debugging
  debug: process.env.NODE_ENV === 'development',

  // Loading strategy
  lazyLoad: true,
  preloadNamespaces: false,

  // Separators
  keySeparator: '.', // common.app.name
  namespaceSeparator: ':', // chat:messages.send
  pluralSeparator: '_', // messages_one
  contextSeparator: '_', // greeting_male

  // Interpolation
  interpolationStart: '{{',
  interpolationEnd: '}}',
  escapeValue: true,

  // Namespaces
  defaultNamespace: 'common',
  namespaces: ['common', 'chat', 'settings', 'admin', 'auth', 'errors'],

  // Persistence
  storageKey: 'nchat-locale',
  cookieName: 'NCHAT_LOCALE',
  cookieMaxAge: 365 * 24 * 60 * 60, // 1 year
  persistLocale: true,

  // Detection
  detectBrowserLocale: true,
  detectUrlLocale: false,
  urlParamName: 'lang',
}

Usage Examples

1. Basic Translation

import { useTranslation } from '@/hooks/use-translation'

export function WelcomeMessage() {
  const { t } = useTranslation('common')

  return (
    <div>
      <h1>{t('app.name')}</h1>
      <p>{t('app.tagline')}</p>
      <button>{t('app.getStarted')}</button>
    </div>
  )
}

2. Translation with Interpolation

export function UserGreeting({ name }: { name: string }) {
  const { t } = useTranslation()

  return (
    <h1>{t('common:greeting', { name })}</h1>
    // Output: "Hello, John!"
  )
}

3. Pluralization

export function MessageCount({ count }: { count: number }) {
  const { t } = useChatTranslation()

  return (
    <span>{t('messages.count', { count })}</span>
    // count = 1: "1 message"
    // count = 5: "5 messages"
  )
}

4. Date Formatting

export function MessageTimestamp({ date }: { date: Date }) {
  const { formatRelativeTime, formatMessageTime } = useLocale()

  return (
    <div>
      <time>{formatRelativeTime(date)}</time>
      {/* "2 hours ago" */}

      <span>{formatMessageTime(date)}</span>
      {/* "3:45 PM" (today) or "Jan 15" (this year) */}
    </div>
  )
}

5. Language Switcher

import { useLocale } from '@/hooks/use-locale'
import { SUPPORTED_LOCALES } from '@/lib/i18n/locales'

export function LanguageSwitcher() {
  const { locale, setLocale, isLoading } = useLocale()

  return (
    <select value={locale} onChange={(e) => setLocale(e.target.value)} disabled={isLoading}>
      {Object.values(SUPPORTED_LOCALES).map(({ code, name, flag }) => (
        <option key={code} value={code}>
          {flag} {name}
        </option>
      ))}
    </select>
  )
}

6. RTL Layout

import { useIsRTL } from '@/hooks/use-locale'

export function ChatLayout({ children }) {
  const isRTL = useIsRTL()

  return (
    <div dir={isRTL ? 'rtl' : 'ltr'} className={isRTL ? 'rtl-layout' : 'ltr-layout'}>
      {children}
    </div>
  )
}

7. Conditional Translation

export function FeatureAnnouncement() {
  const { t, exists } = useTranslation('common')

  return (
    <div>
      {exists('features.newFeature') ? (
        <p>{t('features.newFeature')}</p>
      ) : (
        <p>New feature coming soon!</p>
      )}
    </div>
  )
}

8. Error Messages

import { useErrorsTranslation } from '@/hooks/use-translation'

export function ErrorBoundary({ error }) {
  const { t } = useErrorsTranslation()

  const errorKey = `errors.${error.code}` || 'errors.unknown'

  return (
    <div className="error">
      <h2>{t('errors.general')}</h2>
      <p>{t(errorKey)}</p>
      <button>{t('errors.tryAgain')}</button>
    </div>
  )
}

Testing

Unit Tests

All core i18n modules have comprehensive test coverage:

# Run all i18n tests
pnpm test src/lib/i18n
pnpm test src/hooks/use-translation
pnpm test src/stores/locale-store

# Watch mode
pnpm test:watch src/lib/i18n

Test files:

i18n-config.test.ts
translator.test.ts
locales.test.ts
language-detector.test.ts
plurals.test.ts
date-formats.test.ts
number-formats.test.ts
rtl.test.ts
use-translation.test.ts
use-locale.test.ts
locale-store.test.ts

Manual Testing Checklist

Performance

Bundle Size Impact

Core library: ~15 KB (minified + gzipped)
Per locale file: ~5-10 KB (lazy loaded)
Initial bundle: Only default locale (en) loaded
On-demand: Additional locales loaded when switched

Optimization Strategies

Lazy Loading - Namespaces loaded on-demand
Code Splitting - Translation files split by locale
Caching - Translations cached in memory and localStorage
Tree Shaking - Unused locales excluded from bundle
Compression - JSON files compressed by Next.js

Accessibility (a11y)

Screen Readers - Proper lang attribute on <html>
ARIA Labels - Translated aria-label attributes
RTL Support - Proper text direction for screen readers
Focus Management - RTL-aware focus order
Keyboard Navigation - Works with all locales

Browser Support

✅ Chrome 90+
✅ Firefox 88+
✅ Safari 14+
✅ Edge 90+
✅ Mobile browsers (iOS Safari, Chrome Android)

Migration Guide

From Existing i18n Library

// Old: react-i18next
import { useTranslation } from 'react-i18next'
const { t, i18n } = useTranslation()
t('key', { value: 'x' })
i18n.changeLanguage('es')

// New: nself-chat i18n
import { useTranslation, useLocale } from '@/hooks/use-translation'
const { t } = useTranslation()
const { setLocale } = useLocale()
t('key', { value: 'x' })
setLocale('es')

Future Enhancements

Planned Features

Translation Management
- Admin UI for editing translations
- Export/import translation files
- Translation completion tracking
- Crowdsourced translation platform
Additional Languages
- Hebrew (RTL)
- Hindi
- Korean
- Italian
- Dutch
Advanced Features
- Gender-specific translations
- Regional variants (en-US, en-GB, pt-BR, pt-PT)
- Translation memory
- Machine translation integration
- A/B testing for translations
Developer Tools
- VS Code extension for translation keys
- CLI tool for managing translations
- Translation key linting
- Unused key detection

Troubleshooting

Common Issues

1. Translations not showing

// Check if namespace is loaded
const { isLoading } = useLocale();
if (isLoading) return <Spinner />;

// Manually load namespace
await loadNamespace('admin');

2. Locale not persisting

// Check localStorage
console.log(localStorage.getItem('nchat-locale'))

// Check cookie
console.log(document.cookie)

// Clear and reset
clearPersistedLocale()
setLocale('en')

3. RTL layout issues

// Ensure direction is applied
import { applyDocumentDirection } from '@/lib/i18n/rtl'
useEffect(() => {
  applyDocumentDirection(locale)
}, [locale])

4. Missing translations

// Enable debug mode
// In i18n-config.ts
debug: true // Shows warnings for missing keys

// Check fallback chain
// 1. Current locale
// 2. Fallback locale (en)
// 3. Key itself

Resources

Documentation

Full i18n Guide: /docs/guides/internationalization.md
Translation Guide: /src/locales/README.md
API Reference: /docs/api/i18n.md

External Resources

Tools

date-fns - Date formatting
Intl.NumberFormat - Number formatting

Conclusion

The nself-chat i18n system is a complete, production-ready internationalization solution that provides:

✅ 9 Supported Languages (3 complete, 6 partial) ✅ RTL Support for Arabic and future Hebrew ✅ Lazy Loading for optimal performance ✅ Type-Safe translations with TypeScript ✅ Comprehensive date, time, and number formatting ✅ Pluralization following CLDR standards ✅ Auto-Detection of user language preferences ✅ Persistent locale across sessions ✅ Fallback to English for missing translations ✅ Namespaced for better organization ✅ Tested with comprehensive unit tests

The system is fully integrated into the application and ready for use. Additional languages can be added by following the guide in /src/locales/README.md.

Maintained by: nself-chat i18n Team Last Updated: February 1, 2026 Version: 0.9.0