# Translation System Guide

## Overview
Your application now supports **site-wide multilingual translation** in:
- **English** (en)
- **French** (fr)
- **Arabic** (ar) with RTL support

## Features Implemented

### ✅ Country Label Translation
- GADM GID_0 codes mapped to 250+ countries in 3 languages
- Dynamic Cesium map labels update in real-time

### ✅ UI Translation System
- Translation service with common UI keys
- Translation pipe for Angular templates
- Observable-based language switching

### ✅ RTL (Right-to-Left) Support
- Automatic text direction switching for Arabic
- HTML `dir` and `lang` attributes updated dynamically

---

## How to Use Translations

### 1. In TypeScript Components

```typescript
import { CountryTranslationService } from './Services/country-translation.service';

export class MyComponent {
  constructor(private translationService: CountryTranslationService) {}

  // Get translated text
  getTranslation() {
    const text = this.translationService.translate('nav.home');
    // Returns: 'Home' (en), 'Accueil' (fr), or 'الرئيسية' (ar)
  }

  // Get country name
  getCountryName() {
    const name = this.translationService.getCountryName('USA');
    // Returns: 'United States' (en), 'États-Unis' (fr), or 'الولايات المتحدة' (ar)
  }

  // Change language
  switchToFrench() {
    this.translationService.setLanguage('fr');
    // All subscribed components update automatically
  }

  // Check if RTL
  isRightToLeft() {
    return this.translationService.isRTL(); // true for Arabic
  }
}
```

### 2. In HTML Templates

```html
<!-- Use the translate pipe -->
<h1>{{ 'nav.home' | translate }}</h1>
<button>{{ 'action.save' | translate }}</button>
<p>{{ 'message.loading' | translate }}</p>

<!-- Conditional rendering based on language -->
<div *ngIf="translationService.isRTL()" class="rtl-layout">
  <!-- RTL-specific layout -->
</div>
```

### 3. Language Switcher Buttons

Already implemented in [cesium-map.component.html](cesium-map/cesium-map.component.html):

```html
<div class="language-controls">
  <button [class.active]="currentLanguage === 'en'" 
          (click)="changeLanguage('en')">English</button>
  <button [class.active]="currentLanguage === 'fr'" 
          (click)="changeLanguage('fr')">Français</button>
  <button [class.active]="currentLanguage === 'ar'" 
          (click)="changeLanguage('ar')">العربية</button>
</div>
```

---

## Available Translation Keys

### Navigation
- `nav.home` - Home / Accueil / الرئيسية
- `nav.map` - Map / Carte / الخريطة
- `nav.locations` - Locations / Emplacements / المواقع
- `nav.settings` - Settings / Paramètres / الإعدادات

### Map Controls
- `map.zoom_in` - Zoom In / Zoomer / تكبير
- `map.zoom_out` - Zoom Out / Dézoomer / تصغير
- `map.home` - Home View / Vue initiale / العرض الرئيسي
- `map.labels` - Country Labels / Étiquettes de pays / تسميات الدول

### Actions
- `action.create` - Create / Créer / إنشاء
- `action.edit` - Edit / Modifier / تعديل
- `action.delete` - Delete / Supprimer / حذف
- `action.save` - Save / Enregistrer / حفظ
- `action.cancel` - Cancel / Annuler / إلغاء
- `action.back` - Back / Retour / رجوع

### Messages
- `message.loading` - Loading... / Chargement... / جاري التحميل...
- `message.no_data` - No data available / Aucune donnée disponible / لا توجد بيانات
- `message.error` - An error occurred / Une erreur s'est produite / حدث خطأ
- `message.success` - Success / Succès / نجح

### Location Types
- `location.zone` - Zone / Zone / منطقة
- `location.point` - Point / Point / نقطة
- `location.all` - All / Tous / الكل
- `location.name` - Name / Nom / الاسم
- `location.description` - Description / Description / الوصف

---

## Adding New Translations

### 1. Add to Translation Service

Edit [country-translation.service.ts](Services/country-translation.service.ts):

```typescript
private uiTranslations: { [key: string]: CountryTranslation } = {
  // ... existing translations
  
  // Add your new key
  'my.custom.key': { 
    en: 'My Custom Text', 
    fr: 'Mon Texte Personnalisé', 
    ar: 'النص المخصص الخاص بي' 
  }
};
```

### 2. Use in Template

```html
<p>{{ 'my.custom.key' | translate }}</p>
```

---

## RTL Support

### Automatic Features
✅ HTML `dir="rtl"` attribute set when Arabic is selected  
✅ HTML `lang="ar"` attribute for proper rendering  
✅ Text direction changes automatically

### CSS for RTL

Create RTL-specific styles:

```css
/* Applies when dir="rtl" is set on HTML element */
[dir="rtl"] .your-component {
  text-align: right;
  direction: rtl;
}

[dir="rtl"] .button-icon {
  margin-left: 0;
  margin-right: 8px;
}
```

### Conditional Classes

```html
<div [class.rtl-mode]="translationService.isRTL()">
  Content adapts to RTL
</div>
```

---

## Arabic Text Display Issue

**Q: Why does Arabic text appear reversed in my code editor?**

**A:** Arabic is a **Right-to-Left (RTL)** language. In code editors with LTR (Left-to-Right) settings, Arabic text may appear reversed, but it's actually stored correctly. When rendered in a browser with proper RTL support (via `dir="rtl"`), it displays correctly.

Example:
```typescript
// In code editor (may look reversed):
'TUN': { ar: 'تونس' }  // Appears: سنوت

// In browser (renders correctly):
'TUN': { ar: 'تونس' }  // Displays: تونس (Tunisia)
```

---

## Implementation Checklist

✅ **Translation Service** - CountryTranslationService with UI & country translations  
✅ **Translation Pipe** - `{{ 'key' | translate }}` for templates  
✅ **RTL Support** - Automatic direction switching for Arabic  
✅ **Language Buttons** - UI controls in cesium-map component  
✅ **App-wide Integration** - AppComponent subscribes to language changes  
✅ **Country Labels** - 250+ countries in 3 languages  
✅ **Dynamic Updates** - Real-time label updates without page reload  

---

## Testing

1. **Change Language**: Click language buttons in the map
2. **Check Country Labels**: Labels on map should update instantly
3. **Test RTL**: Switch to Arabic - layout should flip to right-to-left
4. **Inspector**: Check `<html dir="rtl" lang="ar">` in browser DevTools

---

## Future Enhancements

Consider adding:
- More languages (Spanish, German, etc.)
- Persistent language preference (localStorage)
- Browser language detection
- Date/time formatting per locale
- Number formatting per locale
- Full component translation (buttons, menus, etc.)

---

## Files Modified

1. ✅ `Services/country-translation.service.ts` - Added UI translations + RTL methods
2. ✅ `Services/translation.pipe.ts` - NEW: Angular pipe for templates
3. ✅ `app.module.ts` - Added TranslatePipe to declarations
4. ✅ `app.component.ts` - Added RTL handling and language subscription
5. ✅ `cesium-map/cesium-map.component.ts` - Language integration
6. ✅ `cesium-map/cesium-map.component.html` - Language selector buttons
7. ✅ `cesium-map/cesium-map.component.css` - Language button styles

---

## Support

For issues with:
- **Translation keys**: Add them to `uiTranslations` in the service
- **RTL layout**: Use `[dir="rtl"]` CSS selectors
- **Arabic display**: Ensure proper Unicode encoding (UTF-8)
- **Country names**: Check GADM GID_0 codes in `countryTranslations`

---

**Your app now has complete multilingual support! 🌍**