# Story 1.3: Système i18n frontend + API bilingue

Status: review

## Story

As a visiteur,
I want voir le site dans ma langue (FR ou EN),
so that je comprends le contenu.

## Acceptance Criteria

1. **Given** le module `@nuxtjs/i18n` configuré avec stratégie `prefix_except_default` **When** le visiteur accède à `/` ou `/en` **Then** le contenu statique UI est affiché dans la langue correspondante via fichiers JSON (`i18n/fr.json`, `i18n/en.json`)
2. **And** les URLs FR sont par défaut (`/`, `/projets`, `/competences`, `/contact`)
3. **And** les URLs EN sont préfixées (`/en`, `/en/projects`, `/en/skills`, `/en/contact`)
4. **And** `useI18n()`, `$t()`, `localePath()`, `switchLocalePath()` fonctionnent en SSR
5. **And** les tags `hreflang` sont générés automatiquement dans le `<head>`
6. **And** l'attribut `lang` du `<html>` est dynamique (fr/en)
7. **And** le middleware Laravel extrait `Accept-Language` et joint la table `translations` pour le contenu dynamique
8. **And** les API Resources Laravel renvoient le contenu traduit selon la langue demandée
9. **And** le fallback est FR si langue non supportée

## Tasks / Subtasks

- [x] **Task 1: Configuration @nuxtjs/i18n** (AC: #1, #2, #3, #4)
  - [x] Vérifier que `@nuxtjs/i18n` est installé (Story 1.1)
  - [x] Créer la structure `frontend/i18n/` pour les fichiers de traduction
  - [x] Configurer `nuxt.config.ts` avec i18n complet :
    - locales: ['fr', 'en']
    - defaultLocale: 'fr'
    - strategy: 'prefix_except_default'
    - detectBrowserLanguage: false (on utilise l'URL)
  - [x] Activer `vueI18n` pour le composant `<i18n-t>`

- [x] **Task 2: Fichiers de traduction JSON** (AC: #1)
  - [x] Créer `frontend/i18n/fr.json` avec structure de base
  - [x] Créer `frontend/i18n/en.json` avec structure de base
  - [x] Inclure les traductions pour :
    - Navigation (Accueil, Projets, Compétences, Témoignages, Parcours, Contact)
    - Boutons communs (Continuer, Retour, Découvrir, Fermer)
    - Messages d'erreur (404, erreur générique)
    - Landing page (accroche, CTA Aventure, CTA Express)
    - Footer et metadata

- [x] **Task 3: Routes localisées Nuxt** (AC: #2, #3)
  - [x] Configurer `i18n.pages` dans nuxt.config.ts pour les routes custom :
    ```
    pages: {
      'projets/[slug]': { en: '/projects/[slug]' },
      'competences': { en: '/skills' },
      'temoignages': { en: '/testimonials' },
      'parcours': { en: '/journey' },
      'contact': { en: '/contact' }
    }
    ```
  - [x] Vérifier que les routes FR fonctionnent sans préfixe
  - [x] Vérifier que les routes EN fonctionnent avec préfixe `/en`

- [x] **Task 4: Helpers i18n et composables** (AC: #4)
  - [x] Créer un composable `frontend/app/composables/useLocale.ts` pour centraliser la logique i18n
  - [x] Exposer : `currentLocale`, `switchLocale()`, `localizedPath()`
  - [x] Tester `useI18n()` dans un composant
  - [x] Tester `$t('key')` dans un template
  - [x] Tester `localePath('/projets')` pour les liens
  - [x] Tester `switchLocalePath('en')` pour le switcher de langue

- [x] **Task 5: SEO et balises hreflang** (AC: #5, #6)
  - [x] Configurer `i18n.head` dans nuxt.config.ts pour les balises SEO
  - [x] Vérifier que `<html lang="fr">` ou `<html lang="en">` est dynamique
  - [x] Vérifier les balises `<link rel="alternate" hreflang="fr" href="..." />`
  - [x] Vérifier les balises `<link rel="alternate" hreflang="en" href="..." />`
  - [x] Vérifier `<link rel="alternate" hreflang="x-default" href="..." />`

- [x] **Task 6: Composant LanguageSwitcher** (AC: #4)
  - [x] Créer `frontend/app/components/ui/LanguageSwitcher.vue`
  - [x] Afficher les langues disponibles (FR / EN)
  - [x] Utiliser `switchLocalePath()` pour la navigation
  - [x] Highlight de la langue active
  - [x] Accessible au clavier (boutons ou liens)
  - [x] Style cohérent avec le design system (sky-accent pour actif)

- [x] **Task 7: Middleware Laravel SetLocale** (AC: #7, #9)
  - [x] Créer `api/app/Http/Middleware/SetLocale.php`
  - [x] Extraire la langue depuis le header `Accept-Language`
  - [x] Parser le header (ex: `fr-FR,fr;q=0.9,en;q=0.8` → `fr`)
  - [x] Valider que la langue est supportée (fr, en)
  - [x] Fallback vers `fr` si langue non supportée
  - [x] Stocker la langue dans `app()->setLocale($lang)`
  - [x] Passer la langue via `$request->attributes->set('lang', $lang)`
  - [x] Enregistrer le middleware dans `bootstrap/app.php` pour les routes API

- [x] **Task 8: Trait HasTranslations pour les Models** (AC: #8)
  - [x] Créer `api/app/Traits/HasTranslations.php`
  - [x] Méthode `getTranslated($keyField, $lang = null)` qui :
    - Récupère la clé depuis le champ (ex: `$this->title_key`)
    - Joint la table `translations` pour obtenir la valeur
    - Utilise la langue du request ou le fallback
  - [x] Appliquer le trait aux models : Project, Skill
  - [x] Tester : `$project->getTranslated('title_key', 'fr')`

- [x] **Task 9: API Resources avec traductions** (AC: #8)
  - [x] Créer `api/app/Http/Resources/ProjectResource.php`
  - [x] Transformer les champs `*_key` en valeurs traduites :
    ```php
    'title' => $this->getTranslated('title_key'),
    'description' => $this->getTranslated('description_key'),
    ```
  - [x] Créer `api/app/Http/Resources/SkillResource.php` de même
  - [x] Inclure `meta.lang` dans les réponses pour debug/vérification

- [x] **Task 10: Endpoints API avec traductions** (AC: #7, #8)
  - [x] Créer `api/app/Http/Controllers/Api/ProjectController.php`
  - [x] Endpoint `GET /api/projects` retournant la liste traduite
  - [x] Endpoint `GET /api/projects/{slug}` retournant le détail traduit
  - [x] Créer `api/app/Http/Controllers/Api/SkillController.php`
  - [x] Endpoint `GET /api/skills` retournant la liste traduite par catégorie
  - [x] Enregistrer les routes dans `routes/api.php`

- [x] **Task 11: Intégration frontend-backend** (AC: tous)
  - [x] Créer composable `frontend/app/composables/useApi.ts` qui :
    - Utilise `$fetch` ou `useFetch` de Nuxt
    - Ajoute automatiquement le header `X-API-Key`
    - Ajoute automatiquement le header `Accept-Language` selon la locale courante
  - [x] Tester un appel API depuis une page Nuxt
  - [x] Vérifier que le contenu retourné est dans la bonne langue

- [x] **Task 12: Validation finale** (AC: tous)
  - [x] Accéder à `/` → contenu FR
  - [x] Accéder à `/en` → contenu EN
  - [x] Cliquer sur le switcher FR → EN → URL change vers `/en`
  - [x] API call avec `Accept-Language: en` → réponse en anglais
  - [x] API call avec `Accept-Language: de` → fallback FR
  - [x] Vérifier les balises hreflang dans le code source HTML
  - [x] Vérifier `<html lang="...">` dynamique

## Dev Notes

### Architecture i18n Hybride

```
┌────────────────────────────────────────────────────────────────────────────┐
│                           FRONTEND (Nuxt 4)                                │
├────────────────────────────────────────────────────────────────────────────┤
│  Contenu statique UI → Fichiers JSON (i18n/fr.json, i18n/en.json)         │
│  - Labels, boutons, navigation, messages d'erreur                          │
│  - Déployé avec le frontend                                                │
│  - Accès via $t('key') ou useI18n()                                        │
└────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    │ API calls avec Accept-Language header
                                    ▼
┌────────────────────────────────────────────────────────────────────────────┐
│                           BACKEND (Laravel 12)                             │
├────────────────────────────────────────────────────────────────────────────┤
│  Contenu dynamique → Table translations (MariaDB)                          │
│  - Titres, descriptions projets/skills                                     │
│  - Textes narrateur, dialogues PNJ                                         │
│  - Géré via API/BDD                                                        │
│  - Accès via HasTranslations trait + API Resources                         │
└────────────────────────────────────────────────────────────────────────────┘
```

### Configuration nuxt.config.ts complète pour i18n

```typescript
// frontend/nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    '@nuxtjs/i18n',
    // ... autres modules
  ],

  i18n: {
    locales: [
      { code: 'fr', iso: 'fr-FR', file: 'fr.json', name: 'Français' },
      { code: 'en', iso: 'en-US', file: 'en.json', name: 'English' },
    ],
    defaultLocale: 'fr',
    strategy: 'prefix_except_default',
    lazy: true,
    langDir: 'i18n/',
    detectBrowserLanguage: false, // On utilise l'URL uniquement

    // Routes personnalisées
    pages: {
      'projets/index': { en: '/projects' },
      'projets/[slug]': { en: '/projects/[slug]' },
      'competences': { en: '/skills' },
      'temoignages': { en: '/testimonials' },
      'parcours': { en: '/journey' },
      'contact': { en: '/contact' },
      'resume': { en: '/resume' },
    },

    // SEO
    baseUrl: process.env.NUXT_PUBLIC_SITE_URL || 'https://skycel.fr',
  },
})
```

### Structure des fichiers de traduction

```json
// frontend/i18n/fr.json
{
  "nav": {
    "home": "Accueil",
    "projects": "Projets",
    "skills": "Compétences",
    "testimonials": "Témoignages",
    "journey": "Parcours",
    "contact": "Contact"
  },
  "common": {
    "continue": "Continuer",
    "back": "Retour",
    "discover": "Découvrir",
    "close": "Fermer",
    "loading": "Chargement..."
  },
  "landing": {
    "title": "Bienvenue dans mon univers",
    "subtitle": "Développeur Full-Stack",
    "cta_adventure": "Partir à l'aventure",
    "cta_express": "Mode express"
  },
  "error": {
    "404": "Page non trouvée",
    "generic": "Une erreur est survenue"
  },
  "meta": {
    "title": "Skycel - Portfolio de Célian",
    "description": "Découvrez mon portfolio interactif et gamifié"
  }
}
```

### Middleware Laravel SetLocale

```php
<?php
// api/app/Http/Middleware/SetLocale.php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;

class SetLocale
{
    protected array $supportedLocales = ['fr', 'en'];
    protected string $fallbackLocale = 'fr';

    public function handle(Request $request, Closure $next): Response
    {
        $locale = $this->parseAcceptLanguage($request->header('Accept-Language'));

        app()->setLocale($locale);
        $request->attributes->set('locale', $locale);

        return $next($request);
    }

    protected function parseAcceptLanguage(?string $header): string
    {
        if (!$header) {
            return $this->fallbackLocale;
        }

        // Parse "fr-FR,fr;q=0.9,en;q=0.8" → ['fr', 'en']
        $locales = [];
        foreach (explode(',', $header) as $part) {
            $part = trim($part);
            if (preg_match('/^([a-z]{2})(?:-[A-Z]{2})?(?:;q=([0-9.]+))?$/i', $part, $matches)) {
                $lang = strtolower($matches[1]);
                $quality = isset($matches[2]) ? (float)$matches[2] : 1.0;
                $locales[$lang] = $quality;
            }
        }

        arsort($locales);

        foreach (array_keys($locales) as $lang) {
            if (in_array($lang, $this->supportedLocales)) {
                return $lang;
            }
        }

        return $this->fallbackLocale;
    }
}
```

### Trait HasTranslations

```php
<?php
// api/app/Traits/HasTranslations.php

namespace App\Traits;

use App\Models\Translation;

trait HasTranslations
{
    public function getTranslated(string $keyField, ?string $lang = null): ?string
    {
        $lang = $lang ?? request()->attributes->get('locale', 'fr');
        $key = $this->{$keyField};

        if (!$key) {
            return null;
        }

        return Translation::getTranslation($key, $lang);
    }
}
```

### API Resource avec traductions

```php
<?php
// api/app/Http/Resources/ProjectResource.php

namespace App\Http\Resources;

use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\JsonResource;

class ProjectResource extends JsonResource
{
    public function toArray(Request $request): array
    {
        return [
            'id' => $this->id,
            'slug' => $this->slug,
            'title' => $this->getTranslated('title_key'),
            'description' => $this->getTranslated('description_key'),
            'short_description' => $this->getTranslated('short_description_key'),
            'image' => $this->image,
            'url' => $this->url,
            'github_url' => $this->github_url,
            'date_completed' => $this->date_completed?->format('Y-m-d'),
            'is_featured' => $this->is_featured,
            'skills' => SkillResource::collection($this->whenLoaded('skills')),
        ];
    }
}
```

### Composable useApi

```typescript
// frontend/app/composables/useApi.ts
export const useApi = () => {
  const config = useRuntimeConfig()
  const { locale } = useI18n()

  const apiFetch = async <T>(endpoint: string, options: any = {}) => {
    return await $fetch<T>(`${config.public.apiUrl}${endpoint}`, {
      ...options,
      headers: {
        'X-API-Key': config.public.apiKey,
        'Accept-Language': locale.value,
        'Content-Type': 'application/json',
        ...options.headers,
      },
    })
  }

  return { apiFetch }
}
```

### Dépendances avec Stories précédentes

**Cette story DÉPEND de :**
- Story 1.1 : Module @nuxtjs/i18n installé
- Story 1.2 : Table `translations` créée, Models Project et Skill avec relations

**Cette story PRÉPARE pour :**
- Story 1.4 : Layouts utiliseront $t() pour les labels
- Story 1.5 : Landing page avec contenu bilingue
- Story 2.x : Tous les contenus projets/skills seront traduits

### Project Structure Notes

**Fichiers à créer dans `frontend/` :**
```
frontend/
├── i18n/
│   ├── fr.json                    # CRÉER
│   └── en.json                    # CRÉER
├── app/
│   ├── components/
│   │   └── ui/
│   │       └── LanguageSwitcher.vue  # CRÉER
│   └── composables/
│       ├── useLocale.ts           # CRÉER
│       └── useApi.ts              # CRÉER
└── nuxt.config.ts                 # MODIFIER (i18n config)
```

**Fichiers à créer dans `api/` :**
```
api/
├── app/
│   ├── Http/
│   │   ├── Controllers/
│   │   │   └── Api/
│   │   │       ├── ProjectController.php   # CRÉER
│   │   │       └── SkillController.php     # CRÉER
│   │   ├── Middleware/
│   │   │   └── SetLocale.php               # CRÉER
│   │   └── Resources/
│   │       ├── ProjectResource.php         # CRÉER
│   │       └── SkillResource.php           # CRÉER
│   └── Traits/
│       └── HasTranslations.php             # CRÉER
├── bootstrap/
│   └── app.php                             # MODIFIER (middleware)
└── routes/
    └── api.php                             # MODIFIER (routes)
```

### References

- [Source: docs/planning-artifacts/architecture.md#Data-Architecture]
- [Source: docs/planning-artifacts/architecture.md#Stratégie-i18n]
- [Source: docs/planning-artifacts/architecture.md#API-Communication-Patterns]
- [Source: docs/planning-artifacts/epics.md#Story-1.3]
- [Source: docs/prd-gamification.md#NFR7]

### Technical Requirements

| Requirement | Value | Source |
|-------------|-------|--------|
| i18n module | @nuxtjs/i18n 8.x | Architecture |
| Strategy | prefix_except_default | Architecture |
| Default locale | fr | PRD |
| Supported locales | fr, en | PRD |
| SSR | Required | NFR5, NFR7 |
| SEO hreflang | Required | NFR5 |

### Previous Story Intelligence (Story 1.2)

**Files created in Story 1.2:**
- Table `translations` avec clés i18n
- Models Project, Skill avec colonnes `*_key`
- Seeders avec données FR et EN

**Pattern established:**
- Convention de nommage des clés : `{table}.{slug}.{field}`
- Ex: `project.skycel.title`, `skill.vuejs.name`

## Dev Agent Record

### Agent Model Used

Claude Opus 4.5 (claude-opus-4-5-20251101)

### Debug Log References

- hreflang tags non générés au début — résolu en ajoutant `useLocaleHead()` dans `app.vue` avec `addSeoAttributes: true`
- `langDir` configuré en `'../i18n/'` (relatif à `app/`) car Nuxt 4 utilise `app/` comme srcDir

### Completion Notes List

- Frontend: i18n configuré avec lazy loading, fichiers JSON FR/EN, routes localisées, `useLocaleHead()` pour SEO
- Frontend: Composable `useLocale` encapsule la logique i18n, composable `useApi` ajoute automatiquement les headers
- Frontend: LanguageSwitcher accessible au clavier avec highlight de la langue active
- Backend: Middleware SetLocale parse `Accept-Language` avec support qualité (q=), fallback FR
- Backend: Trait HasTranslations appliqué à Project et Skill
- Backend: API Resources transforment les `*_key` en valeurs traduites, meta.lang inclus
- Backend: Controllers avec endpoints GET /api/projects, GET /api/projects/{slug}, GET /api/skills
- Validé: `/` → FR, `/en` → EN, hreflang tags, `<html lang="fr-FR">` / `<html lang="en-US">`
- Validé: API avec Accept-Language: fr → FR, en → EN, de → fallback FR

### Change Log
| Date | Change | Author |
|------|--------|--------|
| 2026-02-03 | Story créée avec contexte complet | SM Agent |
| 2026-02-05 | Tasks 1-12 implémentées et validées | Dev Agent (Claude Opus 4.5) |

### File List

- `frontend/i18n/fr.json` — CRÉÉ
- `frontend/i18n/en.json` — CRÉÉ
- `frontend/nuxt.config.ts` — MODIFIÉ (config i18n complète)
- `frontend/app/app.vue` — MODIFIÉ (useLocaleHead pour SEO)
- `frontend/app/pages/index.vue` — MODIFIÉ (utilise $t())
- `frontend/app/composables/useLocale.ts` — CRÉÉ
- `frontend/app/composables/useApi.ts` — CRÉÉ
- `frontend/app/components/ui/LanguageSwitcher.vue` — CRÉÉ
- `api/app/Http/Middleware/SetLocale.php` — CRÉÉ
- `api/app/Traits/HasTranslations.php` — CRÉÉ
- `api/app/Http/Resources/ProjectResource.php` — CRÉÉ
- `api/app/Http/Resources/SkillResource.php` — CRÉÉ
- `api/app/Http/Controllers/Api/ProjectController.php` — CRÉÉ
- `api/app/Http/Controllers/Api/SkillController.php` — CRÉÉ
- `api/bootstrap/app.php` — MODIFIÉ (ajout middleware SetLocale)
- `api/routes/api.php` — MODIFIÉ (ajout routes projects/skills)
- `api/app/Models/Project.php` — MODIFIÉ (ajout HasTranslations trait)
- `api/app/Models/Skill.php` — MODIFIÉ (ajout HasTranslations trait)

