FAQ - Système de Traduction

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

Questions générales

Q : Comment activer/désactiver les traductions ?

R : Utilisez la variable TRANSLATIONS_ENABLED dans .env :

TRANSLATIONS_ENABLED=true  # Activer
TRANSLATIONS_ENABLED=false # Désactiver

Vous pouvez aussi activer/désactiver chaque composant indépendamment (interface, BDD, routing, Filament).

Q : Puis-je activer les traductions pour seulement certains modèles ?

R : Oui, utilisez les variables TRANSLATIONS_MODEL_* :

TRANSLATIONS_MODEL_POST=true
TRANSLATIONS_MODEL_PRODUCT=true
TRANSLATIONS_MODEL_PAGE=false

Q : Que se passe-t-il si je désactive les traductions après avoir migré les données ?

R : Les données restent en JSON dans la BDD, mais le code les traite comme des colonnes classiques. Le trait ConditionallyTranslatable gère automatiquement la conversion.

Q : Comment tester si les traductions fonctionnent ?

R :

php artisan config:clear
php artisan cache:clear

app()->setLocale('fr');
__('Welcome'); // Devrait retourner la traduction française

translations_enabled(); // true/false
current_locale(); // 'fr', 'es', etc.
available_locales(); // ['fr', 'es']

Traductions JSON (Interface)

Q : Où sont stockées les traductions JSON ?

R : Dans le dossier lang/ à la racine du projet :

• lang/fr.json - Traductions françaises
• lang/es.json - Traductions espagnoles
• lang/en.json - Traductions anglaises (si ajouté)

---

Q : Comment utiliser les traductions JSON dans les vues ?

R : Utilisez la fonction __() :

{{ __('Welcome') }}
{{ __('Hello :name', ['name' => $user->name]) }}

---

Q : Puis-je organiser les traductions JSON par namespace ?

R : Oui, utilisez des clés en notation pointée :

{
    "blog.title": "Blog",
    "blog.posts": "Articles",
    "shop.products": "Produits"
}

Utilisation :

{{ __('blog.title') }}
{{ __('shop.products') }}

---

Traductions BDD (Modèles)

Q : Comment rendre un modèle traduisible ?

R :

• Ajouter le trait ConditionallyTranslatable
• Implémenter getTranslatableFields()
• Convertir les colonnes en JSON via migration
• Activer le modèle dans .env

Voir le Guide pour rendre un modèle traduisible.

---

Q : Comment migrer les données existantes vers le format JSON ?

R : Utilisez la commande :

php artisan translate:migrate-data --model=Post

Ou migrez manuellement (voir le guide).

---

Q : Le fallback fonctionne-t-il automatiquement ?

R : Oui, le système utilise automatiquement un fallback :

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

---

Q : Comment récupérer une traduction spécifique ?

R :

// Méthode directe
$title = $post->getTranslation('title', 'fr');
// Helper
$title = trans_model($post, 'title', 'fr');
// Selon la locale courante
app()->setLocale('fr');
$title = $post->title; // Ou trans_model($post, 'title')

---

Routing et URLs

Q : Comment générer des URLs localisées ?

R : Utilisez le helper localized_route() :

localized_route('blog.index'); // '/fr/blog' ou '/es/blog'
localized_route('blog.show', ['slug' => $slug]);

---

Q : Les routes Filament sont-elles localisées ?

R : Non, les routes Filament (commençant par filament.) ne sont jamais localisées, même si le routing est activé.

---

Q : Que se passe-t-il si le routing est désactivé ?

R : localized_route() utilise route() normalement, sans préfixe de locale.

---

Q : Comment traduire les slugs dans les URLs ?

R : Le système traduit automatiquement les slugs lors du changement de langue via SlugTranslationService. Les Queries (GetPostByTranslatedSlugQuery, etc.) résolvent les modèles par leur slug traduit.

---

Filament

Q : Comment ajouter le sélecteur de langue dans Filament ?

R : Ajoutez LocaleAction dans getHeaderActions() :

use App\Filament\Support\LocaleAction;
protected function getHeaderActions(): array
{
    return array_merge(
        LocaleAction::make() ?? [],
        parent::getHeaderActions()
    );
}

---

Q : Comment créer des champs traduisibles dans Filament ?

R : Utilisez TranslatableField :

use App\Filament\Support\TranslatableField;
...TranslatableField::makeTextInput('title', 'Titre',
    fn ($field) => $field->required()
),

---

Q : Les champs Filament ne s'affichent pas, que faire ?

R :

• Vérifier TRANSLATIONS_FILAMENT_ENABLED=true
• Vérifier que LocaleAction::make() est ajouté
• Vérifier que $locale est initialisé dans mount()
• Vérifier que le modèle est activé : TRANSLATIONS_MODEL_{MODEL}=true

---

Cache

Q : Comment vider le cache des traductions ?

R : Utilisez la commande :

php artisan translate:clear-cache

Options :

Vider seulement le cache JSON
php artisan translate:clear-cache --json
Vider seulement le cache BDD
php artisan translate:clear-cache --db
Vider pour une locale spécifique
php artisan translate:clear-cache --locale=fr

---

Q : Le cache est-il invalidé automatiquement ?

R : Oui, le cache est automatiquement invalidé lors des modifications des modèles traduisibles (création, mise à jour, suppression).

---

Q : Comment désactiver le cache ?

R : Dans .env :

TRANSLATIONS_CACHE_ENABLED=false

---

Modules

Q : Comment ajouter des traductions dans un module ?

R :

• Créer app/Specifics/{Module}/lang/{locale}.json
• Créer app/Specifics/{Module}/Providers/{Module}ServiceProvider.php
• Enregistrer le Service Provider dans bootstrap/providers.php

Voir le Guide Pattern Modules.

---

Helpers

Q : Quels helpers sont disponibles ?

R : Voir le Guide des Helpers pour la liste complète.

Principaux helpers :

• current_locale() - Locale courante
• available_locales() - Locales disponibles
• locale_name($locale) - Nom de la locale
• locale_flag($locale) - Drapeau emoji
• localized_route($name, ...) - Route localisée
• trans_model($model, $field, ...) - Traduction de modèle
• translations_enabled() - Vérifier l'activation
• translation_component_enabled($component) - Vérifier un composant

---

Dépannage

Q : Les traductions ne sont pas sauvegardées

R :

• Vérifier TRANSLATIONS_ENABLED=true
• Vérifier TRANSLATIONS_DATABASE_ENABLED=true
• Vérifier TRANSLATIONS_MODEL_{MODEL}=true
• Vérifier que les colonnes sont de type JSON
• Vérifier que getTranslatableFields() retourne les bons champs

---

Q : RouteNotFoundException lors du changement de langue

R :

• Vérifier que vous utilisez localized_route() et non route()
• Vérifier que la route existe avec le préfixe de locale
• Vérifier TRANSLATIONS_ROUTING_ENABLED=true

---

Q : 404 sur les pages avec slugs traduits

R :

• Vérifier que les Queries sont correctement configurées
• Vérifier que les slugs sont bien stockés en JSON
• Vérifier que le trait ConditionallyTranslatable est utilisé

---

Q : TypeError avec htmlspecialchars() quand TRANSLATIONS_ENABLED=false

R :

• Vérifier que le trait ConditionallyTranslatable est utilisé
• Le trait ajuste automatiquement les casts selon l'activation

---

Q : Les traductions ne se chargent pas dans les modules

R :

• Vérifier que le Service Provider est enregistré dans bootstrap/providers.php
• Vérifier que translation_component_enabled('interface') retourne true
• Vérifier que les fichiers JSON existent dans app/Specifics/{Module}/lang/
• Vider le cache : php artisan translate:clear-cache

---

Performance

Q : Le cache améliore-t-il les performances ?

R : Oui, le cache peut améliorer significativement les performances, surtout pour les traductions BDD. Voir le Guide du Cache.

---

Q : Comment mesurer l'impact du cache ?

R : Des tests de performance sont disponibles dans tests/Feature/TranslationCachePerformanceTest.php.

---

Support

Q : Où trouver plus d'aide ?

R :

• 📖 Documentation complète
• 📖 Guide de Configuration
• 📖 Guide de Démarrage Rapide
• 📖 Guide des Helpers

Dernière mise à jour : 25 janvier 2026