Guide de Configuration - Système de Traduction

Version : 1.1 Date : 2026-01-25

Vue d'ensemble

Le système de traduction peut être activé ou désactivé à plusieurs niveaux pour offrir une flexibilité maximale selon les besoins du projet.

> Note : Pour la documentation du système de cache des traductions, consultez Guide du Système de Cache des Traductions.

1. Configuration globale

Activer/Désactiver tout le système

Fichier : .env

Activer toutes les traductions
TRANSLATIONS_ENABLED=true
Désactiver toutes les traductions (comportement monolithique)
TRANSLATIONS_ENABLED=false

Comportement si désactivé :

• Pas de préfixes de langue dans les URLs
• Pas de sélecteur de langue
• Modèles utilisent les colonnes classiques (pas JSON)
• Filament n'affiche pas le sélecteur de langue
• Interface utilise la locale par défaut uniquement

---

2. Configuration par composant

Activer/Désactiver chaque composant indépendamment

Fichier : .env

Activer globalement
TRANSLATIONS_ENABLED=true
Interface utilisateur (fichiers JSON)
TRANSLATIONS_INTERFACE_ENABLED=true
Base de données (Spatie Translatable)
TRANSLATIONS_DATABASE_ENABLED=true
Routing (URLs localisées)
TRANSLATIONS_ROUTING_ENABLED=true
Filament (plugin admin)
TRANSLATIONS_FILAMENT_ENABLED=true

Exemples d'utilisation :

Cas 1 : Traduction de l'interface uniquement

TRANSLATIONS_ENABLED=true
TRANSLATIONS_INTERFACE_ENABLED=true
TRANSLATIONS_DATABASE_ENABLED=false
TRANSLATIONS_ROUTING_ENABLED=false
TRANSLATIONS_FILAMENT_ENABLED=false

→ Seuls les textes de l'interface sont traduits (boutons, labels, etc.)

Cas 2 : Traduction BDD sans routing

TRANSLATIONS_ENABLED=true
TRANSLATIONS_INTERFACE_ENABLED=true
TRANSLATIONS_DATABASE_ENABLED=true
TRANSLATIONS_ROUTING_ENABLED=false
TRANSLATIONS_FILAMENT_ENABLED=true

→ Contenu traduisible en BDD, mais URLs non localisées (toujours /blog au lieu de /fr/blog)

Cas 3 : Routing sans traduction BDD

TRANSLATIONS_ENABLED=true
TRANSLATIONS_INTERFACE_ENABLED=true
TRANSLATIONS_DATABASE_ENABLED=false
TRANSLATIONS_ROUTING_ENABLED=true
TRANSLATIONS_FILAMENT_ENABLED=false

→ URLs localisées mais contenu en une seule langue

---

3. Configuration par modèle

Activer/Désactiver la traduction pour chaque modèle

Fichier : .env

Activer la traduction pour chaque modèle
TRANSLATIONS_MODEL_POST=true
TRANSLATIONS_MODEL_PRODUCT=true
TRANSLATIONS_MODEL_PAGE=true
TRANSLATIONS_MODEL_CATEGORY=true
TRANSLATIONS_MODEL_TAG=true
TRANSLATIONS_MODEL_FEEDBACK=true

Exemple : Traduire seulement les Posts et Products

TRANSLATIONS_ENABLED=true
TRANSLATIONS_DATABASE_ENABLED=true
TRANSLATIONS_MODEL_POST=true
TRANSLATIONS_MODEL_PRODUCT=true
TRANSLATIONS_MODEL_PAGE=false
TRANSLATIONS_MODEL_CATEGORY=false
TRANSLATIONS_MODEL_TAG=false
TRANSLATIONS_MODEL_FEEDBACK=false

---

4. Utilisation dans le code

Helpers disponibles

use App\Support\TranslationHelper;
// Vérifier si les traductions sont activées globalement
if (translations_enabled()) {
    // Utiliser le système de traduction
}
// Vérifier un composant spécifique
if (translation_component_enabled('database')) {
    // Utiliser Spatie Translatable
}
if (translation_component_enabled('routing')) {
    // Utiliser les routes localisées
}
// Vérifier un modèle spécifique
if (translation_model_enabled('post')) {
    // Post est traduisible
}

Dans les modèles

Avant (sans système d'activation) :

use Spatie\Translatable\HasTranslations;
class Post extends Model
{
    use HasTranslations;
    
    public $translatable = ['title', 'excerpt', 'content'];
}

Après (avec système d'activation) :

use App\Traits\ConditionallyTranslatable;
class Post extends Model
{
    use ConditionallyTranslatable;
    
    protected function getTranslatableFields(): array
    {
        return ['title', 'excerpt', 'content'];
    }
}

Le trait ConditionallyTranslatable :

• Utilise HasTranslations si TRANSLATIONS_MODEL_POST=true
• Utilise les colonnes classiques si désactivé
• Fournit les mêmes méthodes dans les deux cas (transparent pour le code)

Dans les routes

use Illuminate\Support\Facades\Route;
use App\Support\TranslationHelper;
// Routes conditionnelles
if (translation_component_enabled('routing')) {
    Route::group([
        'prefix' => LaravelLocalization::setLocale(),
        'middleware' => ['localize', 'localizationRedirect']
    ], function() {
        Route::get('/blog', [BlogController::class, 'index']);
    });
} else {
    Route::get('/blog', [BlogController::class, 'index']);
}

Dans Filament

Le plugin Filament s'enregistre automatiquement seulement si TRANSLATIONS_FILAMENT_ENABLED=true.

---

5. Scénarios d'utilisation

Scénario 1 : Site monolithique (une seule langue)

TRANSLATIONS_ENABLED=false

Avantages :

• Simplicité
• Pas de surcharge
• Performance optimale

Utilisation : Sites avec une seule langue, pas de besoin multilingue

---

Scénario 2 : Multilingue complet

TRANSLATIONS_ENABLED=true
TRANSLATIONS_INTERFACE_ENABLED=true
TRANSLATIONS_DATABASE_ENABLED=true
TRANSLATIONS_ROUTING_ENABLED=true
TRANSLATIONS_FILAMENT_ENABLED=true
Tous les modèles activés
TRANSLATIONS_MODEL_POST=true
TRANSLATIONS_MODEL_PRODUCT=true
TRANSLATIONS_MODEL_PAGE=true
TRANSLATIONS_MODEL_CATEGORY=true
TRANSLATIONS_MODEL_TAG=true
TRANSLATIONS_MODEL_FEEDBACK=true

Avantages :

• Support complet multilingue
• SEO optimisé
• Expérience utilisateur complète

Utilisation : Sites internationaux, e-commerce multilingue

---

Scénario 3 : Migration progressive

Phase 1 : Activer seulement l'interface

TRANSLATIONS_ENABLED=true
TRANSLATIONS_INTERFACE_ENABLED=true
TRANSLATIONS_DATABASE_ENABLED=false
TRANSLATIONS_ROUTING_ENABLED=false
TRANSLATIONS_FILAMENT_ENABLED=false

Phase 2 : Ajouter la traduction BDD

TRANSLATIONS_DATABASE_ENABLED=true
TRANSLATIONS_FILAMENT_ENABLED=true
TRANSLATIONS_MODEL_POST=true  # Commencer par un modèle

Phase 3 : Ajouter le routing

TRANSLATIONS_ROUTING_ENABLED=true

Avantages :

• Migration sans risque
• Tests progressifs
• Rollback facile

---

Scénario 4 : Traduction partielle

TRANSLATIONS_ENABLED=true
TRANSLATIONS_INTERFACE_ENABLED=true
TRANSLATIONS_DATABASE_ENABLED=true
TRANSLATIONS_ROUTING_ENABLED=false
TRANSLATIONS_FILAMENT_ENABLED=true
Seulement certains modèles
TRANSLATIONS_MODEL_POST=true
TRANSLATIONS_MODEL_PRODUCT=true
TRANSLATIONS_MODEL_PAGE=false
TRANSLATIONS_MODEL_CATEGORY=false
TRANSLATIONS_MODEL_TAG=false
TRANSLATIONS_MODEL_FEEDBACK=false

Avantages :

• Flexibilité maximale
• Traduire seulement ce qui est nécessaire

Utilisation : Sites avec contenu mixte (certains articles traduits, d'autres non)

---

6. Migration depuis monolithique vers multilingue

Étape 1 : Préparation

• Backup complet de la base de données
• Vérifier que tous les packages sont installés
• Configurer .env avec TRANSLATIONS_ENABLED=false (pour l'instant)

Étape 2 : Activation progressive

• Activer l'interface :

   TRANSLATIONS_ENABLED=true
   TRANSLATIONS_INTERFACE_ENABLED=true
   

→ Tester que l'interface fonctionne
• Activer un modèle :

   TRANSLATIONS_DATABASE_ENABLED=true
   TRANSLATIONS_FILAMENT_ENABLED=true
   TRANSLATIONS_MODEL_POST=true
   

→ Migrer les données du modèle Post → Tester dans Filament
• Activer les autres modèles un par un
• Activer le routing :

   TRANSLATIONS_ROUTING_ENABLED=true
   

→ Tester les URLs localisées

Étape 3 : Validation

• Tous les tests passent
• Aucune régression fonctionnelle
• Performance acceptable

---

7. Rollback (désactivation)

Désactiver complètement

TRANSLATIONS_ENABLED=false

Actions nécessaires :

• php artisan config:clear
• php artisan cache:clear
• Redémarrer l'application

Résultat : Application en mode monolithique, toutes les traductions ignorées

Désactiver un composant

TRANSLATIONS_ROUTING_ENABLED=false

→ Les URLs ne sont plus localisées, mais le reste fonctionne

---

8. Vérification de la configuration

Commande Artisan

php artisan translations:status

Affiche :

• État global (activé/désactivé)
• État de chaque composant
• État de chaque modèle
• Locales disponibles
• Recommandations

Exemple de sortie

Système de Traduction - État
Global : ✅ Activé
Composants :
  Interface : ✅ Activé
  Base de données : ✅ Activé
  Routing : ✅ Activé
  Filament : ✅ Activé
Modèles :
  Post : ✅ Activé
  Product : ✅ Activé
  Page : ⚠️  Désactivé (mais DATABASE_ENABLED=true)
  Category : ✅ Activé
  Tag : ✅ Activé
  Feedback : ⚠️  Désactivé
Locales disponibles : fr, en
Locale par défaut : fr

---

9. Bonnes pratiques

1. Toujours vérifier la configuration avant d'utiliser

// ❌ Mauvais
$post->getTranslation('title', 'fr');
// ✅ Bon
if (translation_model_enabled('post')) {
    $post->getTranslation('title', 'fr');
} else {
    $post->title;
}

2. Utiliser les helpers centralisés

// ❌ Mauvais
if (config('translations.enabled') && config('translations.components.database')) {
    // ...
}
// ✅ Bon
if (translation_component_enabled('database')) {
    // ...
}

3. Tester avec différentes configurations

• Tests avec TRANSLATIONS_ENABLED=true
• Tests avec TRANSLATIONS_ENABLED=false
• Tests avec composants partiellement activés

4. Documenter les dépendances

Si une fonctionnalité nécessite les traductions, le documenter clairement.

---

10. FAQ

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

R : Oui, utilisez TRANSLATIONS_MODEL_* pour chaque modèle.

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 : Puis-je avoir des URLs localisées sans traduction BDD ?

R : Oui, activez seulement TRANSLATIONS_ROUTING_ENABLED=true et TRANSLATIONS_DATABASE_ENABLED=false.

Q : Comment tester si les traductions fonctionnent ?

R : Utilisez php artisan translations:status pour voir l'état de la configuration.

Q : Puis-je activer les traductions en production sans risque ?

R : Oui, si vous suivez la migration progressive. Commencez par l'interface, puis la BDD, puis le routing.

---

11. Exemples de fichiers .env

Configuration minimale (monolithique)

APP_LOCALE=fr
APP_FALLBACK_LOCALE=fr
TRANSLATIONS_ENABLED=false

Configuration multilingue complète

APP_LOCALE=fr
APP_FALLBACK_LOCALE=en
TRANSLATIONS_ENABLED=true
TRANSLATIONS_INTERFACE_ENABLED=true
TRANSLATIONS_DATABASE_ENABLED=true
TRANSLATIONS_ROUTING_ENABLED=true
TRANSLATIONS_FILAMENT_ENABLED=true
TRANSLATIONS_MODEL_POST=true
TRANSLATIONS_MODEL_PRODUCT=true
TRANSLATIONS_MODEL_PAGE=true
TRANSLATIONS_MODEL_CATEGORY=true
TRANSLATIONS_MODEL_TAG=true
TRANSLATIONS_MODEL_FEEDBACK=true

Configuration partielle (exemple)

APP_LOCALE=fr
APP_FALLBACK_LOCALE=en
TRANSLATIONS_ENABLED=true
TRANSLATIONS_INTERFACE_ENABLED=true
TRANSLATIONS_DATABASE_ENABLED=true
TRANSLATIONS_ROUTING_ENABLED=false
TRANSLATIONS_FILAMENT_ENABLED=true
TRANSLATIONS_MODEL_POST=true
TRANSLATIONS_MODEL_PRODUCT=true
TRANSLATIONS_MODEL_PAGE=false
TRANSLATIONS_MODEL_CATEGORY=false
TRANSLATIONS_MODEL_TAG=false
TRANSLATIONS_MODEL_FEEDBACK=false

---

12. Support

Pour toute question ou problème avec la configuration, consultez :

• PRD : docs/prd/prd-multilingual-system.md
• Épic 1, Story 1.6 : docs/prd/epic-1-translation-foundations.md