La localisation dans Laravel

Dans le développement d'applications modernes, le multilinguisme est devenu incontournable. Que ce soit pour toucher un public international ou simplement offrir une meilleure expérience utilisateur, il est essentiel de pouvoir gérer plusieurs langues de manière simple et efficace. Avec Laravel 12, comme c'était aussi le cas avec les versions précédentes, la localisation est intégrée au framework de manière flexible, puissante et personnalisable. Cet article vous propose d'explorer ces fonctionnalités pour mettre en place un système multilingue efficace dans vos projets.

Mise en place de la localisation

Par défaut, le squelette Laravel ne contient pas le répertoire lang. Pour commencer à personnaliser vos traductions, vous devez le générer avec une commande Artisan :

php artisan lang:publish

Cette commande publie les fichiers linguistiques par défaut du framework. Vous trouverez alors une organisation basée sur des sous-répertoires pour chaque langue (par exemple lang/en) et la possibilité d'ajouter vos propres locales, comme : lang/fr.

Une autre solution rapide et très efficace consiste à utiliser ce package. Le gros avantage est que vous disposez automatiquement de toutes les traductions pour de très nombreux langages et pour les projets officiels de Laravel. L'inconvénient est que vous allez sans doute avoir plein de traductions inutiles par la même occasion.

Méthodes de gestion des chaînes de traduction

Laravel propose deux approches distinctes pour gérer vos chaînes de traduction.

Fichiers PHP (Short Keys)

Les traductions sont stockées dans des fichiers PHP qui renvoient un tableau de clés-valeurs. Voici un exemple dans le fichier lang/en/pagination.php :

return [
	'next'     => 'Next &raquo;',
	'previous' => '&laquo; Previous',
];

Vous pouvez ensuite générer avec :

__('pagination.next');

Pour des variantes régionales, le nommage suit l’ISO 15897, par exemple en_CA.

Fichiers JSON (chaînes comme clés)

Alternativement, vous pouvez directement utiliser des fichiers JSON pour stocker des phrases entières comme clés. Exemple dans lang/fr.json :

{
    "A Timeout Occurred": "Un dépassement de délai s'est produit",
}

L’appel correspondant est :

__('A Timeout Occurred');

Cette méthode est idéale pour les applications comportant beaucoup de contenu dynamique. Attention toutefois à ne pas générer de conflits entre les noms de fichiers et les clés de traduction !

Configuration de la locale

La configuration des langues se fait principalement via le fichier config/app.php.

la locale par défaut est définie par la clé locale classiquement alimentée par APP_LOCALE
la locale de repli est définie par la clé APP_FALLBACK_LOCALE et est utilisée si la traduction n’existe pas dans la langue active

Exemple dans le fichier .env :

APP_LOCALE=fr
APP_FALLBACK_LOCALE=en

Vous pouvez aussi modifier la locale à l’exécution (par exemple selon l’utilisateur connecté) :

App::setLocale('es');

Et vérifier la locale active avec :

App::currentLocale();  
App::isLocale('fr');

Pluralisation et grammaire des langues

Laravel inclut un moteur de pluralisation utilisé notamment par Eloquent. Si vous travaillez dans une autre langue que l'anglais, vous pouvez le configurer dans un service provider.

use Illuminate\Support\Pluralizer;

public function boot()
{
    Pluralizer::useLanguage('french');
}

Les langages actuellement supportés sont : french, norwegian-bokmal, portuguese, spanish, et turkish.

Important : en cas de pluralisation personnalisée, définissez explicitement vos noms de tables Eloquent pour éviter les surprises !

Utilisation des chaînes de traduction

La fonction d’aide __ est au cœur de la récupération de chaînes traduites dans Laravel.

Avec des clés

__('pagination.previous')

Avec JSON

__('I am happy')

Dans Blade

{{ __('What a story!) }}

Si aucune traduction n’existe, __ retourne simplement la clé transmise.

Utilisation d'un helper

Il est aussi possible d'utiliser l'helper trans qui donne exactement le même résultat :

trans('I am sad.')

Paramètres dynamiques et placeholders

Laravel permet d'insérer des valeurs dynamiques dans les traductions grâce aux placeholders :

// lang/en/messages.php
return [
    'welcome' => 'Welcome, :name',
];

Utilisation :

__('messages.welcome', ['name' => 'robert'])

La casse est respectée (:NAME, :Name, etc.).

:NAME	ROBERT
:Name	Robert

Pour aller plus loin, vous pouvez également définir des formateurs personnalisés dans un provider :

Lang::stringable(Money::class, fn ($money) => $money->formatTo('fr'));

Pluralisation

La gestion du singulier et du pluriel se fait facilement à l'aide du séparateur « | » :

// lang/en/messages.php
return [
    'houses' => 'There is one house|There are many houses',
];

Ça fonctionne aussi dans les fichiers JSON :

{
    "There is one house|There are many houses": "Il y a une maison|Il y a plusieurs maisons"
}

Pour récupérer la bonne chaîne selon une valeur, on utilise trans_choice  :

echo trans_choice('messages.houses', 2);

Vous pouvez aussi définir des règles conditionnelles :

'houses' => '{0} There are none house|[1,5] There are few houses|[6,*] There are a lot of houses!',

Si on utilise ce code :

echo trans_choice('messages.houses', 4);

On va obtenir : "There are few houses".

On peut également utiliser des placeholders dans ces règles conditionnelles, mais ça devient un peu compliqué à lire :

'minutes_ago' => '{1} :value minute ago|[2,*] :value minutes ago',

On appelle ainsi :

trans_choice('time.minutes_ago', 3, ['value' => 3])

Ce qui donne "3 minutes ago".

Enfin, on dispose aussi du placeholder pré-établi :count qui récupère automatiquement la valeur entière transmise dans la fonction trans_choice :

'chats' => '{0} Il n\'y en a pas|{1} I y en a un|[2,*] Il y en a :count'

Conclusion

La localisation dans Laravel 12 allie simplicité et puissance.

les short keys conviennent aux petites applications bien structurées, tandis que les fichiers JSON sont parfaits pour les sites contenant beaucoup de contenu
la gestion flexible des locales et de la pluralisation facilite l'adaptation pour presque toutes les langues

En résumé, Laravel fournit un écosystème qui simplifie l'internationalisation et vous permet de vous concentrer sur l'expérience utilisateur.