Skip to main content

Laravel i18n : guide complet de l'internationalisation et de la localisation

Du premier fichier de locale à la production : configurez le système de traduction de Laravel, gérez la pluralisation, corrigez le bug de repli JSON et ajoutez des chaînes de repli de locale intelligentes pour les variantes régionales.

1

Comprendre le système de traduction de Laravel

Laravel est fourni avec un système de traduction intégré qui prend en charge deux formats de fichiers : les tableaux PHP et le JSON. Les fichiers PHP utilisent des clés imbriquées organisées par fonctionnalité (auth.failed, validation.required). Les fichiers JSON utilisent la chaîne source comme clé, ce qui est plus simple mais ne prend pas en charge l'imbrication.

Terminal
composer create-project laravel/laravel my-app
cd my-app

# Laravel includes i18n out of the box
# No extra packages needed for basic usage
Le système de traduction de Laravel se trouve dans le répertoire lang/ (Laravel 9 et versions ultérieures) ou resources/lang/ (Laravel 8 et versions antérieures). Le framework détecte automatiquement le répertoire. Si les deux existent, lang/ est prioritaire.
2

Configurer les paramètres de locale

Définissez la locale par défaut et la locale de repli de votre application dans config/app.php. La locale de repli est utilisée lorsqu'une clé de traduction est manquante dans la locale active. Configurez les locales prises en charge par votre application et ajoutez un middleware pour détecter et définir la locale préférée de l'utilisateur.

config/app.php
// config/app.php
return [
    'locale' => 'en',            // Default locale
    'fallback_locale' => 'en',   // Fallback when key is missing
    'faker_locale' => 'en_US',

    // Available locales (for your language switcher)
    'available_locales' => ['en', 'de', 'ja', 'es', 'fr', 'pt-BR'],
];
app/Http/Middleware/SetLocale.php
// app/Http/Middleware/SetLocale.php
namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;

class SetLocale
{
    public function handle(Request $request, Closure $next)
    {
        $locale = $request->segment(1); // e.g. /de/about

        if (in_array($locale, config('app.available_locales'))) {
            app()->setLocale($locale);
        }

        return $next($request);
    }
}
3

Utiliser les fonctions de traduction

Laravel propose trois façons de traduire des chaînes : la fonction utilitaire __() (recommandée), la fonction trans() et la directive Blade @lang. Les trois acceptent la clé de traduction et des paramètres de remplacement facultatifs. Utilisez __() dans le code PHP et les modèles Blade, et @lang dans Blade lorsque vous n'avez pas besoin d'échapper le HTML.

lang/en/messages.php
// lang/en/messages.php
return [
    'welcome' => 'Welcome to our application',
    'greeting' => 'Hello, :name!',
    'nav' => [
        'home' => 'Home',
        'about' => 'About',
        'settings' => 'Settings',
    ],
];

// lang/de/messages.php
return [
    'welcome' => 'Willkommen in unserer Anwendung',
    'greeting' => 'Hallo, :name!',
    'nav' => [
        'home' => 'Startseite',
        'about' => 'Über uns',
        'settings' => 'Einstellungen',
    ],
];
Préférez __() à trans() dans le nouveau code. __() fonctionne à la fois avec les fichiers de traduction PHP et JSON, alors que trans() ne fonctionne qu'avec les fichiers PHP. La directive @lang équivaut à {'{ __() }'} dans les modèles Blade, mais avec une syntaxe légèrement plus propre.
4

Gérer la pluralisation

Laravel utilise une syntaxe séparée par des barres verticales pour les formes plurielles. La forme la plus simple est 'apples' => 'There is one apple|There are many apples'. Pour des plages explicites, utilisez 'apples' => '{0} No apples|{1} One apple|[2,*] :count apples'. L'utilitaire trans_choice() ou Str::plural() sélectionne la forme correcte en fonction du nombre.

lang/en.json
// lang/en.json
{
    "Welcome back!": "Welcome back!",
    "You have :count new notifications": "You have :count new notifications",
    "Copyright :year :company": "Copyright :year :company"
}

// lang/de.json
{
    "Welcome back!": "Willkommen zurück!",
    "You have :count new notifications": "Sie haben :count neue Benachrichtigungen",
    "Copyright :year :company": "Copyright :year :company"
}
La pluralisation intégrée de Laravel ne gère correctement que les règles simples un/autre pour la plupart des langues. Pour les langues aux formes plurielles complexes (l'arabe en compte 6, le russe 4, le polonais 3), vous devez définir toutes les catégories plurielles CLDR requises. Sans elles, les utilisateurs voient un texte grammaticalement incorrect.
5

Ajouter des chaînes de repli de locale

Le repli intégré de Laravel ne va que de la locale active à fallback_locale — il n'existe aucune étape intermédiaire. Un utilisateur pt-BR ayant une clé manquante voit s'afficher l'anglais au lieu d'une traduction pt-PT pourtant parfaitement valable. laravel-locale-chain corrige cela en fusionnant en profondeur les traductions d'une chaîne de repli configurable au chargement.

resources/views/example.blade.php
{{-- Simple translation --}}
<h1>{{ __('messages.welcome') }}</h1>

{{-- With variables --}}
<p>{{ __('messages.greeting', ['name' => $user->name]) }}</p>

{{-- Using @lang directive --}}
<h2>@lang('messages.nav.home')</h2>

{{-- JSON translations (use the string itself as key) --}}
<p>{{ __('Welcome back!') }}</p>

{{-- Pluralization --}}
{{ trans_choice('{0} No items|{1} One item|[2,*] :count items', $count) }}

{{-- Inside Blade components --}}
<x-button>{{ __('messages.nav.settings') }}</x-button>
6

Automatiser les traductions

Une fois votre configuration i18n Laravel terminée, traduisez vos fichiers de locale à l'aide de l'IA. Pointez votre assistant IA vers le fichier de locale source, ou utilisez le CLI i18n Agent dans votre pipeline CI/CD. Les fichiers de traduction PHP et JSON sont tous deux pris en charge.

config/locale-chain.php
// Install locale chain package
composer require i18n-agent/laravel-locale-chain

// config/locale-chain.php
return [
    'chains' => [
        'pt-BR' => ['pt-BR', 'pt', 'en'],
        'zh-Hant-TW' => ['zh-Hant-TW', 'zh-Hant', 'zh', 'en'],
        'es-419' => ['es-419', 'es', 'en'],
    ],
];

// In AppServiceProvider::boot()
use I18nAgent\LocaleChain\LocaleChainServiceProvider;

// The package automatically deep-merges translations
// across the chain: pt-BR -> pt -> en
Traduisez de manière incrémentale — lorsque vous ajoutez de nouvelles clés, traduisez uniquement le diff plutôt que de régénérer tous les fichiers. Cela préserve les traductions relues par des humains et évite les modifications inutiles.

Pièges courants

Logique singulier/pluriel codée en dur

Écrire $count == 1 ? 'item' : 'items' au lieu d'utiliser trans_choice() pose problème pour les langues où 0 est singulier (le français), où il existe 3 formes plurielles ou plus (le russe, le polonais), ou où il en existe 6 (l'arabe). Utilisez toujours la syntaxe plurielle de Laravel et définissez toutes les formes requises.

Les traductions JSON ne se replient pas

Le paramètre fallback_locale de Laravel ne fonctionne que pour les fichiers de traduction PHP. Les traductions JSON utilisent la chaîne source comme clé, donc une traduction manquante renvoie la clé elle-même (le texte anglais) plutôt que de chercher dans la locale de repli. Cela signifie que les traductions JSON n'ont aucun véritable repli de locale. Utilisez laravel-locale-chain pour corriger ce problème.

Mélanger PHP et JSON sans comprendre l'ordre de priorité

Lorsque la même clé existe à la fois dans un fichier PHP et un fichier JSON, le fichier PHP est prioritaire. Cela peut entraîner un comportement déroutant : la mise à jour du fichier JSON n'a aucun effet, car le fichier PHP le masque. Choisissez un seul format par espace de noms de fonctionnalité et tenez-vous-y.

Essayez i18n Agent maintenant

Déposez votre fichier de traduction ici

JSON, YAML, PO, XML, CSV, Markdown, Properties

ou cliquez pour parcourir

Langues cibles

Aucune inscription requiseEstimation instantanée

FAQ sur Laravel i18n