Guide : Helpers et utilitaires pour les traductions

Guide : Helpers et utilitaires pour les traductions

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

Vue d'ensemble

Ce guide présente tous les helpers et utilitaires disponibles pour faciliter l'utilisation du système de traduction dans l'application. Ces helpers sont disponibles à la fois comme méthodes statiques de la classe TranslationHelper et comme fonctions globales.

1. Helpers de base

currentLocale() / current_locale()

Obtient la locale courante de l'application.

Classe : 

use App\Support\TranslationHelper;
$locale = TranslationHelper::currentLocale(); // 'fr'

Helper global : 

$locale = current_locale(); // 'fr'

Exemple d'utilisation : 

if (current_locale() === 'fr') {
    // Code spécifique au français
}

availableLocales() / available_locales()

Obtient toutes les locales disponibles dans l'application.

Classe : 

use App\Support\TranslationHelper;
$locales = TranslationHelper::availableLocales(); // ['fr', 'es']

Helper global : 

$locales = available_locales(); // ['fr', 'es']

Exemple d'utilisation : 

@foreach (available_locales() as $locale)
    <a href="{{ route('switch.locale', $locale) }}">{{ locale_name($locale) }}</a>
@endforeach

localeName(string $locale) / locale_name(string $locale)

Obtient le nom d'une locale dans sa langue native.

Classe : 

use App\Support\TranslationHelper;
$name = TranslationHelper::localeName('fr'); // 'Français'
$name = TranslationHelper::localeName('es'); // 'Español'

Helper global : 

$name = locale_name('fr'); // 'Français'
$name = locale_name('es'); // 'Español'

Exemple d'utilisation : 

<select name="locale">
    @foreach (available_locales() as $locale)
        <option value="{{ $locale }}">{{ locale_name($locale) }}</option>
    @endforeach
</select>

locale_flag(string $locale)

Obtient l'emoji du drapeau pour une locale donnée.

Helper global : 

$flag = locale_flag('fr'); // '🇫🇷'
$flag = locale_flag('es'); // '🇪🇸'
$flag = locale_flag('en'); // '🇬🇧'
$flag = locale_flag('unknown'); // '🌐'

Exemple d'utilisation : 

@foreach (available_locales() as $locale)
    <a href="{{ route('switch.locale', $locale) }}">
        {{ locale_flag($locale) }} {{ locale_name($locale) }}
    </a>
@endforeach

2. Helpers de routes localisées

localizedRoute(string $name, array|object $parameters = [], ?string $locale = null) / localized_route(string $name, array|object $parameters = [], ?string $locale = null)

Génère une URL localisée pour une route donnée. Si le routing est activé, ajoute automatiquement le préfixe de locale au nom de la route.

Classe : 

use App\Support\TranslationHelper;
$url = TranslationHelper::localizedRoute('home'); // '/fr' ou '/es/home' selon la locale
$url = TranslationHelper::localizedRoute('posts.show', ['post' => $post]);
$url = TranslationHelper::localizedRoute('posts.show', $post, 'es'); // Spécifier une locale

Helper global : 

$url = localized_route('home');
$url = localized_route('posts.show', ['post' => $post]);
$url = localized_route('posts.show', $post, 'es');

Exemple d'utilisation : 

<a href="{{ localized_route('posts.show', $post) }}">
    {{ trans_model($post, 'title') }}
</a>

Comportement :

  • Les routes Filament (commençant par filament.) ne sont jamais localisées
  • Si le routing est désactivé, utilise route() normalement
  • Si la route n'existe pas avec le préfixe de locale, essaie sans préfixe (fallback)

    • 3. Helpers de traduction de modèles

    transModel($model, string $field, ?string $locale = null) / trans_model($model, string $field, ?string $locale = null)

    Traduit un champ d'un modèle pour la locale courante ou spécifiée. Utilise un système de fallback automatique.

    Classe : 

    use App\Support\TranslationHelper;
    $title = TranslationHelper::transModel($post, 'title'); // Traduction pour la locale courante
$title = TranslationHelper::transModel($post, 'title', 'es'); // Traduction espagnole

    Helper global : 

    $title = trans_model($post, 'title');
$title = trans_model($post, 'title', 'es');

    Exemple d'utilisation : 

    <h1>{{ trans_model($post, 'title') }}</h1>
<p>{{ trans_model($post, 'content') }}</p>

    Système de fallback :

  • Essaie d'abord avec la locale demandée
  • Si vide, essaie avec la locale par défaut
  • Si toujours vide, essaie avec toutes les locales disponibles
  • Retourne null si aucune traduction n'est trouvée

    • Exemple : 

    $post = Post::create([
    'title' => [
        'fr' => 'Titre français',
        // Pas de traduction espagnole
    ],
]);
    app()->setLocale('es');
$title = trans_model($post, 'title'); // Retourne 'Titre français' (fallback)

    4. Helpers de vérification

    enabled() / translations_enabled()

    Vérifie si les traductions sont activées globalement.

    Classe : 

    use App\Support\TranslationHelper;
    if (TranslationHelper::enabled()) {
    // Traductions activées
}

    Helper global : 

    if (translations_enabled()) {
    // Traductions activées
}

    componentEnabled(string $component) / translation_component_enabled(string $component)

    Vérifie si un composant de traduction spécifique est activé.

    Composants disponibles :

  • 'interface' : Traductions JSON (interface)
  • 'database' : Traductions BDD (modèles)
  • 'routing' : Routes localisées
  • 'filament' : Support Filament

    • Classe : 

    use App\Support\TranslationHelper;
    if (TranslationHelper::componentEnabled('database')) {
    // Traductions BDD activées
}

    Helper global : 

    if (translation_component_enabled('database')) {
    // Traductions BDD activées
}

    Exemple d'utilisation : 

    @if (translation_component_enabled('routing'))
    <a href="{{ localized_route('home') }}">Accueil</a>
@else
    <a href="{{ route('home') }}">Accueil</a>
@endif

    modelEnabled(string $model) / translation_model_enabled(string $model)

    Vérifie si la traduction est activée pour un modèle spécifique.

    Classe : 

    use App\Support\TranslationHelper;
    if (TranslationHelper::modelEnabled('post')) {
    // Traductions activées pour le modèle Post
}

    Helper global : 

    if (translation_model_enabled('post')) {
    // Traductions activées pour le modèle Post
}

    Exemple d'utilisation : 

    if (translation_model_enabled('post')) {
    $title = trans_model($post, 'title');
} else {
    $title = $post->title;
}

    5. Helpers de routes (avancés)

    route_is_localized(string|array $patterns)

    Vérifie si la route courante correspond à un pattern de route localisée.

    Helper global : 

    if (route_is_localized('home')) {
    // Route home (localisée ou non)
}
    if (route_is_localized(['home', 'about'])) {
    // Route home ou about
}

    Exemple d'utilisation : 

    @if (route_is_localized('posts.*'))
    <nav>
        <a href="{{ localized_route('posts.index') }}">Articles</a>
    </nav>
@endif

    localized_routes(callable $callback)

    Enveloppe des routes dans un groupe localisé si le routing est activé.

    Helper global : 

    localized_routes(function () {
    Route::get('/posts', [PostController::class, 'index'])->name('posts.index');
    Route::get('/posts/{post}', [PostController::class, 'show'])->name('posts.show');
});

    Comportement :

  • Si le routing est activé : enregistre les routes pour chaque locale
  • Si le routing est désactivé : enregistre les routes normalement

    • 6. Exemples d'utilisation complets

    Exemple 1 : Sélecteur de langue

    <div class="language-selector">
    @foreach (available_locales() as $locale)
        <a 
            href="{{ localized_route('switch.locale', $locale) }}"
            class="{{ current_locale() === $locale ? 'active' : '' }}"
        >
            {{ locale_flag($locale) }} {{ locale_name($locale) }}
        </a>
    @endforeach
</div>

    Exemple 2 : Affichage d'un article avec traductions

    <article>
    <h1>{{ trans_model($post, 'title') }}</h1>
    <div class="meta">
        <span>{{ $post->created_at->format('d/m/Y') }}</span>
        <span>{{ trans_model($post, 'category.name') }}</span>
    </div>
    <div class="content">
        {{ trans_model($post, 'content') }}
    </div>
    <nav>
        <a href="{{ localized_route('posts.index') }}">Retour aux articles</a>
    </nav>
</article>

    Exemple 3 : Navigation conditionnelle

    <nav>
    @if (translation_component_enabled('routing'))
        <a href="{{ localized_route('home') }}">Accueil</a>
        <a href="{{ localized_route('posts.index') }}">Articles</a>
        <a href="{{ localized_route('about') }}">À propos</a>
    @else
        <a href="{{ route('home') }}">Accueil</a>
        <a href="{{ route('posts.index') }}">Articles</a>
        <a href="{{ route('about') }}">À propos</a>
    @endif
</nav>

    Exemple 4 : Utilisation dans un contrôleur

    <?php
    namespace App\Http\Controllers;
    use App\Models\Post;
    class PostController extends Controller
{
    public function index()
    {
        $posts = Post::all();
        
        return view('posts.index', [
            'posts' => $posts,
            'currentLocale' => current_locale(),
            'availableLocales' => available_locales(),
        ]);
    }
        public function show(Post $post)
    {
        // Utiliser trans_model pour obtenir les traductions
        $title = trans_model($post, 'title');
        $content = trans_model($post, 'content');
        
        return view('posts.show', [
            'post' => $post,
            'title' => $title,
            'content' => $content,
        ]);
    }
}

    7. Tableau récapitulatif

    | Helper | Classe | Fonction globale | Description | |--------|--------|------------------|-------------| | currentLocale() | ✅ | current_locale() | Obtient la locale courante | | availableLocales() | ✅ | available_locales() | Obtient les locales disponibles | | localeName($locale) | ✅ | locale_name($locale) | Obtient le nom d'une locale | | locale_flag($locale) | ❌ | ✅ | Obtient l'emoji du drapeau | | localizedRoute($name, ...) | ✅ | localized_route($name, ...) | Génère une URL localisée | | transModel($model, $field, ...) | ✅ | trans_model($model, $field, ...) | Traduit un champ de modèle | | enabled() | ✅ | translations_enabled() | Vérifie si les traductions sont activées | | componentEnabled($component) | ✅ | translation_component_enabled($component) | Vérifie si un composant est activé | | modelEnabled($model) | ✅ | translation_model_enabled($model) | Vérifie si un modèle est traduisible | | route_is_localized($patterns) | ❌ | ✅ | Vérifie si une route est localisée | | localized_routes($callback) | ❌ | ✅ | Enveloppe des routes dans un groupe localisé |

    8. Bonnes pratiques

    1. Utiliser les helpers globaux dans les vues Blade

    {{-- ✅ Bon --}}
<h1>{{ trans_model($post, 'title') }}</h1>
<a href="{{ localized_route('posts.index') }}">Articles</a>
    {{-- ❌ Moins pratique --}}
<h1>{{ \App\Support\TranslationHelper::transModel($post, 'title') }}</h1>

    2. Utiliser la classe dans le code PHP

    // ✅ Bon pour la réutilisabilité et les tests
use App\Support\TranslationHelper;
    $locale = TranslationHelper::currentLocale();

    3. Vérifier l'activation avant d'utiliser

    // ✅ Bon
if (translation_component_enabled('database')) {
    $title = trans_model($post, 'title');
} else {
    $title = $post->title;
}

    4. Utiliser le fallback automatique

    // ✅ Bon - le fallback est automatique
$title = trans_model($post, 'title');
    // ❌ Inutile - le fallback est déjà géré
$title = trans_model($post, 'title') ?? trans_model($post, 'title', 'fr');

    9. FAQ

    Q : Quelle est la différence entre TranslationHelper::method() et helper_function() ?

    R : Aucune différence fonctionnelle. Les helpers globaux appellent simplement les méthodes de la classe TranslationHelper. Utilisez les helpers globaux dans les vues Blade pour plus de lisibilité, et la classe dans le code PHP pour plus de flexibilité.

    Q : Les helpers fonctionnent-ils si les traductions sont désactivées ?

    R : Oui, la plupart des helpers fonctionnent même si les traductions sont désactivées. Par exemple :

  • current_locale() retourne toujours la locale de l'application
  • available_locales() retourne la locale par défaut
  • localized_route() utilise route() normalement si le routing est désactivé

    • Q : Comment tester les helpers ?

    R : Des tests complets sont disponibles dans tests/Feature/Support/TranslationHelperTest.php. Vous pouvez les exécuter avec :

    php artisan test tests/Feature/Support/TranslationHelperTest.php

    Q : Puis-je créer mes propres helpers ?

    R : Oui, vous pouvez ajouter vos propres helpers dans bootstrap/helpers.php ou créer une nouvelle classe helper. Assurez-vous de suivre les conventions existantes.

    10. Support et ressources

  • Classe principale : app/Support/TranslationHelper.php
  • Helpers globaux : bootstrap/helpers.php
  • Tests : tests/Feature/Support/TranslationHelperTest.php
  • PRD : docs/prd/epic-5-optimizations-and-extensions.md

Dernière mise à jour : 25 janvier 2026

← Retour à la documentation

Prendre rendez-vous