{t('common.welcome')}

# Language Toggle Implementation - Complete

## Overview
Implemented a complete i18n system with cookie-based language detection, Zustand state management, RTL support for Arabic, and TanStack Query integration.

## Files Created

### Core i18n System
- `src/lib/i18n/config.ts` - Language constants and configuration
- `src/lib/i18n/engine.ts` - Translation engine with t() function and Intl helpers
- `src/lib/i18n/cookie.ts` - Cookie utilities for client and server
- `src/lib/i18n/store.ts` - Zustand store for language state with callbacks
- `src/lib/i18n/language-sync.tsx` - Client component ensuring cookie/localStorage sync
- `src/lib/i18n/provider.tsx` - I18nProvider context with dictionary management
- `src/lib/i18n/server.ts` - Server-side translation helper

### Dictionaries
- `src/lib/i18n/dictionaries/dictionary.type.ts` - TypeScript interface for translations
- `src/lib/i18n/dictionaries/en.json` - English translations
- `src/lib/i18n/dictionaries/ar.json` - Arabic translations

### Hooks
- `src/hooks/useTranslation.ts` - Main hook for client components
- `src/hooks/useRTL.ts` - Hook for RTL/LTR direction management

### Components
- `src/components/RTLHandler.tsx` - Component applying RTL/LTR to HTML
- `src/components/LanguageSwitcher.tsx` - Dropdown menu for language selection with shadcn

### Constants
- `src/lib/constants/query-keys.ts` - TanStack Query key definitions
- `src/lib/constants/route-queries.ts` - Route to query mapping for invalidation

### Server Configuration
- `src/proxy.ts` - Language cookie detection and header injection

## Updated Files
- `src/app/layout.tsx` - Integrated I18nProvider, LanguageSync, RTLHandler, and Noto Sans Arabic font
- `src/app/page.tsx` - Added LanguageSwitcher and translation usage example
- `src/app/globals.css` - Added CSS variables for font families

## Key Features

### 1. Cookie-Based Language Detection
- `proxy.ts` validates and sets language cookie on every request
- Adds `x-language` header for server components
- Automatic fallback to default language (English)

### 2. Zustand Store
- Manages current language and RTL state
- Callback system for query invalidation on language change
- Persists to both cookie and localStorage

### 3. Language Sync
- Ensures cookie and localStorage are always in sync
- Handles repair cases (missing cookie, localStorage exists)
- No flash on subsequent visits

### 4. RTL Support
- Automatic `dir` and `lang` attributes on HTML element
- Font family switching: Inter (English) ↔ Noto Sans Arabic
- Logical CSS properties support via Tailwind

### 5. Server & Client Components
- Server components: Use `getServerTranslation()` helper
- Client components: Use `useTranslation()` hook
- Both support t(), plural(), formatNumber(), formatDate(), formatRelativeTime()

### 6. TanStack Query Integration
- Route-based query invalidation on language change
- Centralized query key definitions
- Route to query mapping for automatic invalidation

## Usage Examples

### Client Component
```tsx
'use client'

import { useTranslation } from '@/hooks/useTranslation'

export function MyComponent() {
  const { t, language, setLanguage } = useTranslation()
  
  return <h1>{t('common.welcome')}</h1>
}
```

### Server Component
```tsx
import { getServerTranslation } from '@/lib/i18n/server'

export default async function Page() {
  const { t } = await getServerTranslation()
  
  return <h1>{t('dashboard.title')}</h1>
}
```

### Language Switcher
```tsx
import { LanguageSwitcher } from '@/components/LanguageSwitcher'

export function Header() {
  return <LanguageSwitcher />
}
```

## Architecture Flow

1. User visits site
2. `proxy.ts` checks/validates language cookie
3. Root layout reads language from headers
4. Loads appropriate dictionary (en.json or ar.json)
5. Sets `<html lang="en/ar" dir="ltr/rtl">`
6. Wraps app in I18nProvider
7. LanguageSync mounts and syncs cookie/localStorage
8. RTLHandler applies RTL/LTR to HTML
9. User can toggle language via LanguageSwitcher
10. Zustand store updates, cookie/localStorage persist
11. Dictionary swaps client-side
12. Route queries invalidate automatically

## Next Steps

1. Add more translation keys as needed to dictionaries
2. Extend `routeQueryMap` as new routes are created
3. Use `useTranslation()` in all client components
4. Use `getServerTranslation()` in server components
5. Test language persistence across page reloads
6. Verify RTL layout works correctly for Arabic