README

DB-Translatable

DB-Translatable est une solution robuste et performante pour gérer les traductions de vos modèles Eloquent dans des tables dédiées. Contrairement au stockage JSON, cette approche permet des recherches SQL natives, un typage strict et une intégrité référentielle totale.

Le package respecte strictement les conventions snake_case et lowercase pour une compatibilité parfaite avec les outils comme Prisma ou les standards de bases de données modernes.

🚀 Installation

Installer via Composer :

composer require bouleluciole/db-translatable

Publier la configuration :

php artisan vendor:publish --tag=db-translatable-config

Note : Le package utilise le Laravel Auto-Discovery. Le Service Provider est enregistré automatiquement via les métadonnées du composer.json.

⚙️ Configuration

Le fichier config/db-translatable.php centralise le comportement du package :

return [
    'tables' => [
        'suffix' => '_translations', // Nom de table : posts -> post_translations
        'locale_column' => 'locale', // Nom de la colonne de langue
        'foreign_key' => null, // Auto-calculé (ex: post_id) si null
    ],
    'locale' => [
        'current' => 'fr', // Locale courante par défaut
        'fallback' => 'en', // Langue de secours
        'use_fallback' => true, // Utiliser le fallback si trad manquante
        'strict' => false, // Si true, lance une exception si trad manquante
        'allowed' => ['fr','en'], // Locales autorisées
        'allow_unknown' => false, // Autorise des locales inconnues
        'prevent_writing_unknown_locale' => true,
        'missing_value' => null, // Valeur par défaut si traduction manquante
    ],
        'eloquent' => [
        'autoload' => true, // Eager-load automatique des traductions
        'dynamic_access' => true, // $model->title accède directement à la trad
        'relation' => 'translations', // Nom de la relation
    ],
        'cache' => [
        'enabled' => true, // Cache de requêtes activé
        'ttl' => 3600, // Durée de vie du cache (secondes)
    ]
];

📖 Utilisation Standard

1. Préparer le modèle parent

Ajoutez le trait HasTranslations et listez les attributs traduisibles :

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use DbTranslatable\Concerns\HasTranslations;

class Post extends Model
{
use HasTranslations;

    public array $translatable = ['title', 'content', 'slug'];

}

2. Générer l'infrastructure automatiquement

php artisan make:translation-migration Post
php artisan make:translation-model Post

3. Manipulation des données

Accès direct via locale courante

$post = Post::create(['slug' => 'mon-post']);
$post->title = 'Titre FR';
$post->save();

echo $post->title; // Retourne la valeur dans la locale courante

Forcer une locale temporairement

$post->withLocale('en', function($m) {
    $m->title = 'Hello';
});

Accès explicite via TranslationProxy

echo $post->translation('fr')->title; // Lecture
$post->translation('en')->title = 'Hello'; // Écriture

4. Suppression

$post->deleteTranslation('fr');            // Supprimer une langue
$post->deleteTranslationsExcept(['fr']); // Supprimer toutes sauf certaines
$post->delete(); // Supprime le modèle et ses traductions

5. Informations et utilitaires

$post->getTranslations('title');   // Retourne ['fr' => 'Titre FR', 'en' => 'My Title']
$post->getAvailableLocales(); // ['fr','en']
$post->hasLocale('en');           // true/false
$post->useLocale('en'); // Force temporairement la locale
$post->resetLocale(); // Réinitialise la locale forcée

🔍 Smart Scopes

// Rechercher par colonne traduite
Post::whereT('title', 'Bonjour')->get();

// Smart scope détectant tables principales et traductions
Post::whereSmart('title','LIKE','%Laravel%')
->whereSmart('status','published')
->get();

// Ordonner par colonne traduite
Post::orderByT('title','desc')->get();

⌨️ Commandes Artisan disponibles

Commande	Utilité
`make:translation-migration {model}`	Génère la migration SQL optimisée (BigInt/UUID/ULID).
`make:translation-model {model}`	Génère le modèle de traduction Eloquent.
`db-translatable:info`	Affiche l'état de santé et la config du package.

🛡️ Qualité et Conventions

Typage strict et intégrité référentielle.
Contrainte UNIQUE sur (foreign_key, locale).
Eager loading et cache pour éviter N+1.
Conventions : snake_case + lowercase.

🧪 Tests

Le package utilise Pest + Orchestra Testbench :

composer test

Licence MIT. Développé par Boule Luciole.

bouleluciole / db-translatable

Maintainers

Details