Guide : Ajouter une Nouvelle Langue

Version : 1.0 Date : 2026-01-25 Story : Epic 5, Story 5.4

Vue d'ensemble

Ce guide explique comment ajouter une nouvelle langue (locale) au système de traduction. Par exemple, ajouter l'anglais (en) en plus du français (fr) et de l'espagnol (es).

1. Configuration

Étape 1 : Ajouter la locale dans la configuration

Fichier : config/translations.php

'available_locales' => ['fr', 'es', 'en'], // Ajouter 'en'
'default_locale' => 'fr',

Ou via .env :

TRANSLATIONS_AVAILABLE_LOCALES=fr,es,en
TRANSLATIONS_DEFAULT_LOCALE=fr

Étape 2 : Configurer Spatie Translatable

Fichier : config/translatable.php

'locales' => [
    'fr',
    'es',
    'en', // Ajouter 'en'
],
'default_locale' => 'fr',
'fallback_locale' => 'fr',

2. Fichiers de traduction JSON

Créer le fichier de traduction

Fichier : lang/en.json

{
    "Welcome": "Welcome",
    "Hello": "Hello",
    "Login": "Login",
    "Register": "Register"
}

Ajouter la locale dans TranslationHelper

Fichier : app/Support/TranslationHelper.php

public static function localeName(string $locale): string
{
    return match ($locale) {
        'fr' => 'Français',
        'es' => 'Español',
        'en' => 'English', // Ajouter
        default => $locale,
    };
}

Ajouter le drapeau dans helpers.php

Fichier : bootstrap/helpers.php

function locale_flag(string $locale): string
{
    return match ($locale) {
        'fr' => '🇫🇷',
        'es' => '🇪🇸',
        'en' => '🇬🇧', // Ajouter
        default => '🌐',
    };
}

3. Migrer les données existantes

Si vous avez déjà des données traduites, vous devez ajouter la traduction anglaise :

$posts = Post::all();
foreach ($posts as $post) {
    // Récupérer la traduction française comme base
    $titleFr = $post->getTranslation('title', 'fr');
    
    // Créer une traduction anglaise (ou laisser vide pour traduction manuelle)
    $post->setTranslation('title', 'en', ''); // À traduire manuellement
    $post->save();
}

4. Traductions dans les modules

Si vous utilisez des traductions dans les modules, ajoutez le fichier JSON :

Fichier : app/Specifics/Blog/lang/en.json

{
    "blog.title": "Blog",
    "blog.posts": "Posts",
    "blog.create_post": "Create a post",
    "blog.edit_post": "Edit the post"
}

5. Vérification

Tester les traductions JSON

app()->setLocale('en');
__('Welcome'); // "Welcome"

Tester les traductions BDD

$post = Post::first();
app()->setLocale('en');
trans_model($post, 'title'); // Titre en anglais ou fallback

Tester les routes

localized_route('home', [], 'en'); // '/en' ou '/en/home'

6. Checklist

• [ ] Locale ajoutée dans config/translations.php
• [ ] Locale ajoutée dans config/translatable.php
• [ ] Fichier lang/{locale}.json créé
• [ ] localeName() mis à jour dans TranslationHelper
• [ ] locale_flag() mis à jour dans helpers.php
• [ ] Fichiers de traduction des modules créés (si applicable)
• [ ] Données existantes migrées (si applicable)
• [ ] Tests effectués

---

7. Exemple complet : Ajouter l'anglais

1. Configuration

.env
TRANSLATIONS_AVAILABLE_LOCALES=fr,es,en
TRANSLATIONS_DEFAULT_LOCALE=fr

2. Fichiers JSON

// lang/en.json
{
    "Welcome": "Welcome",
    "Hello": "Hello"
}

3. Code

// app/Support/TranslationHelper.php
public static function localeName(string $locale): string
{
    return match ($locale) {
        'fr' => 'Français',
        'es' => 'Español',
        'en' => 'English',
        default => $locale,
    };
}

// bootstrap/helpers.php
function locale_flag(string $locale): string
{
    return match ($locale) {
        'fr' => '🇫🇷',
        'es' => '🇪🇸',
        'en' => '🇬🇧',
        default => '🌐',
    };
}

4. Test

app()->setLocale('en');
__('Welcome'); // "Welcome"
available_locales(); // ['fr', 'es', 'en']
locale_name('en'); // "English"
locale_flag('en'); // "🇬🇧"

---

8. Notes importantes

• Fallback : Si une traduction n'existe pas pour la nouvelle locale, le système utilisera automatiquement la locale par défaut (fallback).
• Migration : Les données existantes ne sont pas automatiquement traduites. Vous devez les traduire manuellement ou utiliser un service de traduction.
• Cache : N'oubliez pas de vider le cache après avoir ajouté une nouvelle langue : php artisan translate:clear-cache

Prochaines étapes : Consultez le Guide de Configuration pour plus de détails.