Guide du Système de Cache des Traductions

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

Vue d'ensemble

Le système de cache des traductions améliore les performances de l'application en mettant en cache les traductions JSON (interface) et les traductions BDD (modèles traduisibles). Le cache est automatiquement invalidé lors des modifications des modèles traduisibles.

1. Configuration

Activation du cache

Le cache est activé par défaut. Vous pouvez le configurer dans config/translations.php ou via les variables d'environnement :

Fichier : .env

Activer/désactiver le cache
TRANSLATIONS_CACHE_ENABLED=true
Durée de vie du cache en secondes (défaut: 86400 = 24 heures)
TRANSLATIONS_CACHE_TTL=86400
Store de cache à utiliser (optionnel, utilise le store par défaut si null)
TRANSLATIONS_CACHE_STORE=null

Fichier : config/translations.php

'cache' => [
    'enabled' => env('TRANSLATIONS_CACHE_ENABLED', true),
    'ttl' => env('TRANSLATIONS_CACHE_TTL', 86400),
    'store' => env('TRANSLATIONS_CACHE_STORE', null),
],

2. Fonctionnement

Cache des traductions JSON (interface)

Les fichiers JSON de traduction (lang/*.json) sont automatiquement mis en cache lors de leur première lecture. Le cache est utilisé pour toutes les lectures suivantes jusqu'à expiration ou invalidation.

Clé de cache : translations.json.{locale} Exemple : translations.json.fr, translations.json.es

Cache des traductions BDD (modèles)

Les traductions des modèles utilisant le trait ConditionallyTranslatable sont automatiquement mises en cache lors de l'appel à getTranslation(). Le cache est utilisé pour toutes les lectures suivantes jusqu'à expiration ou invalidation.

Clé de cache : translations.db.{ModelName}.{modelId}.{field}.{locale} Exemple : translations.db.Post.123.title.fr

Invalidation automatique

Le cache est automatiquement invalidé lors des événements suivants sur les modèles traduisibles :

Création : Le cache est invalidé (bien que le modèle n'ait pas encore d'ID, donc pas de cache à invalider)
Mise à jour : Le cache du modèle est invalidé
Suppression : Le cache du modèle est invalidé
Restauration : Le cache du modèle est invalidé

L'invalidation est gérée par l'observer TranslatableModelObserver qui est automatiquement enregistré pour tous les modèles traduisibles.

3. Utilisation

Utilisation automatique

Le cache fonctionne automatiquement. Aucune modification de code n'est nécessaire. Les traductions sont mises en cache et récupérées depuis le cache de manière transparente.

Exemple :

use App\Models\Page;
$page = Page::find(1);
// Première lecture : mise en cache
$titleFr = $page->getTranslation('title', 'fr');// Deuxième lecture : depuis le cache
$titleFr = $page->getTranslation('title', 'fr'); // Plus rapide !

Service de cache

Si vous avez besoin d'accéder directement au service de cache :

use App\Services\TranslationCacheService;
$cacheService = app(TranslationCacheService::class);
// Récupérer les traductions JSON
$jsonTranslations = $cacheService->getJsonTranslations('fr');
// Invalider le cache JSON pour une locale
$cacheService->invalidateJsonCache('fr');
// Invalider le cache JSON pour toutes les locales
$cacheService->invalidateJsonCache();
// Invalider le cache BDD pour un modèle
$cacheService->invalidateModelCache(Page::class, $pageId);// Vider tout le cache
$cacheService->clearAll();

4. Commande Artisan

Vider le cache

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

Options disponibles

--json : Vide uniquement le cache des traductions JSON
--db : Vide uniquement le cache des traductions BDD
--locale=LOCALE : Vide le cache pour une locale spécifique

5. Drivers de cache supportés

Le système de cache fonctionne avec tous les drivers de cache Laravel :

Array : Cache en mémoire (perdu à la fin de la requête)
Database : Cache dans une table de base de données
File : Cache dans des fichiers
Redis : Cache Redis (recommandé pour la production)
Memcached : Cache Memcached

Note : Pour les drivers qui supportent les tags (Redis, Memcached), l'invalidation est plus précise. Pour les autres drivers (database, file), l'invalidation peut vider tout le cache.

6. Cas d'usage

Cas 1 : Cache activé (par défaut)

TRANSLATIONS_CACHE_ENABLED=true

Comportement :

Les traductions JSON sont mises en cache
Les traductions BDD sont mises en cache
Le cache est invalidé automatiquement lors des modifications
Amélioration significative des performances

Cas 2 : Cache désactivé

TRANSLATIONS_CACHE_ENABLED=false

Comportement :

Aucun cache n'est utilisé
Les traductions sont toujours récupérées depuis la source (fichiers ou BDD)
Utile pour le développement ou le débogage

Cas 3 : TTL personnalisé

TRANSLATIONS_CACHE_TTL=3600  # 1 heure

Comportement :

Le cache expire après 1 heure au lieu de 24 heures
Utile pour les environnements où les traductions changent fréquemment

7. Performance

Amélioration attendue

Le cache améliore significativement les performances, surtout pour :

Traductions JSON : Réduction du temps de chargement de 50-90% après le premier chargement
Traductions BDD : Réduction du temps de requête de 70-95% après la première lecture

Tests de performance

Des tests de performance sont disponibles dans tests/Feature/TranslationCachePerformanceTest.php. Pour les exécuter :

Exécuter les tests de performance (marqués avec ->skip() par défaut)
php artisan test --filter="TranslationCachePerformanceTest"

8. Dépannage

Le cache ne se met pas à jour après modification

Problème : Les modifications d'un modèle ne sont pas reflétées dans le cache.

Solution :

Vérifier que le cache est activé : TRANSLATIONS_CACHE_ENABLED=true
Vérifier que l'observer est enregistré dans AppServiceProvider
Vider manuellement le cache : php artisan translate:clear-cache

Le cache est trop volumineux

Problème : Le cache prend trop de place.

Solution :

Réduire le TTL : TRANSLATIONS_CACHE_TTL=3600
Utiliser un driver de cache avec expiration automatique (Redis, Memcached)
Vider régulièrement le cache : php artisan translate:clear-cache

Le cache ne fonctionne pas avec certains drivers

Problème : L'invalidation ne fonctionne pas correctement avec certains drivers.

Solution :

Les drivers database et file ne supportent pas l'invalidation par pattern. Dans ce cas, tout le cache est vidé lors de l'invalidation.
Pour une invalidation plus précise, utilisez Redis ou Memcached qui supportent les tags.

9. Architecture technique

Composants

TranslationCacheService (app/Services/TranslationCacheService.php)

TranslatableModelObserver (app/Observers/TranslatableModelObserver.php)

created

updated

deleted

restored

forceDeleted

ConditionallyTranslatable (app/Specifics/Shares/Models/Concerns/ConditionallyTranslatable.php)

getTranslation()

Cache::remember()

TranslateClearCacheCommand (app/Console/Commands/TranslateClearCacheCommand.php)

Flux de données

┌─────────────────┐
│  getTranslation │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Cache activé ?  │───Non───► Lecture directe depuis BDD
└────────┬────────┘
         │ Oui
         ▼
┌─────────────────┐
│ Clé en cache ?  │───Oui───► Retour depuis cache
└────────┬────────┘
         │ Non
         ▼
┌─────────────────┐
│ Lecture BDD     │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Mise en cache   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Retour valeur   │
└─────────────────┘

10. Exemples de code

Exemple 1 : Utilisation basique

use App\Models\Page;
$page = Page::find(1);// Le cache est utilisé automatiquement
$titleFr = $page->getTranslation('title', 'fr');
$titleEs = $page->getTranslation('title', 'es');

Exemple 2 : Invalidation manuelle

use App\Services\TranslationCacheService;
$cacheService = app(TranslationCacheService::class);
// Invalider le cache pour une page spécifique
$cacheService->invalidateModelCache(Page::class, 1);// Invalider le cache JSON pour le français
$cacheService->invalidateJsonCache('fr');

Exemple 3 : Vider le cache via commande

Dans un script de déploiement
php artisan translate:clear-cache
Ou via code
Artisan::call('translate:clear-cache');

11. FAQ

Q : Le cache est-il activé par défaut ?

R : Oui, le cache est activé par défaut. Vous pouvez le désactiver avec TRANSLATIONS_CACHE_ENABLED=false.

Q : Comment vider le cache manuellement ?

R : Utilisez la commande php artisan translate:clear-cache ou appelez Cache::flush() (vide tout le cache Laravel).

Q : Le cache est-il invalidé automatiquement ?

R : Oui, le cache est automatiquement invalidé lors de la création, mise à jour, suppression ou restauration d'un modèle traduisible.

Q : Puis-je désactiver le cache pour certains modèles ?

R : Non, le cache est global. Si vous devez désactiver le cache, désactivez-le pour toute l'application via TRANSLATIONS_CACHE_ENABLED=false.

Q : Le cache fonctionne-t-il avec tous les drivers de cache Laravel ?

R : Oui, mais l'invalidation est plus précise avec Redis et Memcached qui supportent les tags. Avec les autres drivers, l'invalidation peut vider tout le cache.

Q : Comment mesurer l'amélioration de performance ?

R : Utilisez les tests de performance dans tests/Feature/TranslationCachePerformanceTest.php ou mesurez manuellement avec microtime(true).

12. Tests

Des tests complets sont disponibles dans :

Tests fonctionnels : tests/Feature/TranslationCacheTest.php (19 tests)
Tests de performance : tests/Feature/TranslationCachePerformanceTest.php (3 tests)

Pour exécuter les tests :

Tous les tests de cache
php artisan test --filter="TranslationCache"
Tests fonctionnels uniquement
php artisan test tests/Feature/TranslationCacheTest.php
Tests de performance (marqués avec ->skip() par défaut)
php artisan test tests/Feature/TranslationCachePerformanceTest.php

13. Support et ressources

Service : app/Services/TranslationCacheService.php
Observer : app/Observers/TranslatableModelObserver.php
Commande : app/Console/Commands/TranslateClearCacheCommand.php
Configuration : config/translations.php
PRD : docs/prd/epic-5-optimizations-and-extensions.md

Dernière mise à jour : 25 janvier 2026

Guide du Système de Cache des Traductions

Guide du Système de Cache des Traductions

Vue d'ensemble

1. Configuration

Activation du cache

Activer/désactiver le cache

Durée de vie du cache en secondes (défaut: 86400 = 24 heures)

Store de cache à utiliser (optionnel, utilise le store par défaut si null)

2. Fonctionnement

Cache des traductions JSON (interface)

Cache des traductions BDD (modèles)

Invalidation automatique

3. Utilisation

Utilisation automatique

Service de cache

4. Commande Artisan

Vider le cache

Vider tout le cache des traductions

Vider uniquement le cache JSON

Vider uniquement le cache BDD

Vider le cache pour une locale spécifique

Options disponibles

5. Drivers de cache supportés

6. Cas d'usage

Cas 1 : Cache activé (par défaut)

Cas 2 : Cache désactivé

Cas 3 : TTL personnalisé

7. Performance

Amélioration attendue

Tests de performance

Exécuter les tests de performance (marqués avec ->skip() par défaut)

8. Dépannage

Le cache ne se met pas à jour après modification

Le cache est trop volumineux

Le cache ne fonctionne pas avec certains drivers

9. Architecture technique

Composants

Flux de données

10. Exemples de code

Exemple 1 : Utilisation basique

Exemple 2 : Invalidation manuelle

Exemple 3 : Vider le cache via commande

Dans un script de déploiement

Ou via code

11. FAQ

Q : Le cache est-il activé par défaut ?

Q : Comment vider le cache manuellement ?

Q : Le cache est-il invalidé automatiquement ?

Q : Puis-je désactiver le cache pour certains modèles ?

Q : Le cache fonctionne-t-il avec tous les drivers de cache Laravel ?

Q : Comment mesurer l'amélioration de performance ?

12. Tests

Tous les tests de cache

Tests fonctionnels uniquement

Tests de performance (marqués avec ->skip() par défaut)

13. Support et ressources

Prendre rendez-vous