Localisation et traduction

Introduction

Dans toute application, il y a le besoin de rendre l'application multilingue. Bow implémente un système simple de traduction.

Configuration

Pour utiliser le système de traduction, il faut d'abord considérer la configuration qui se trouve dans le fichier config/trans.php. Dans ce fichier, la langue par défaut est le français, donc 'lang' => 'fr'.

Dans le dossier lang sont rangées les traductions de votre application. Ce sont des fichiers php qui retournent un array. Si vous remarquez, il y a un dossier fr et en. Ce sont les dossiers pour chaque langue : fr pour le français et en pour l'anglais. S'il y avait une autre langue, par exemple l'espagnol, ce serait es le nom du dossier.

/lang
  /en
    messages.php
  /fr
    messages.php

Structure des fichiers

Tous les fichiers de langue renvoient un tableau de chaînes à clé. Chaque clé représente une traduction spécifique.

Par exemple :

lang/en/messages.php

return [
  'welcome' => 'Welcome to our application'
];

Configuration de la locale

La langue par défaut de votre application est stockée dans le fichier de configuration config/trans.php. Bien entendu, vous pouvez modifier cette valeur pour répondre aux besoins de votre application.

Vous pouvez également modifier la langue active au moment de l'exécution à l'aide de la méthode setLocale sur la classe Bow\Translate\Translator :

routes/app.php

use Bow\Translate\Translator;

$router->get('docs/:locale', function ($locale) {
  Translator::setLocale($locale);
  //
});

Langue de secours

Vous pouvez configurer une langue de secours qui sera utilisée lorsque la langue active ne contient pas une chaîne de traduction donnée. Comme la langue par défaut, la langue de secours est également configurée dans le fichier de configuration config/trans.php :

config/trans.php

'lang' => 'en',

Récupération de chaînes de traduction

Vous pouvez extraire des lignes de fichiers de langue à l'aide de la fonction helper trans ou t. La méthode t accepte le fichier et la clé de la chaîne de traduction comme premier argument. Par exemple, récupérons la chaîne de traduction de bienvenue dans le fichier de langue lang/messages.php :

echo t('messages.welcome');

// Ou bien
echo trans('messages.welcome');

// Ou bien
use Bow\Translate\Translator;

echo Translator::translate('messages.welcome');

Détermination de la locale actuelle

Vous pouvez utiliser les méthodes getLocale et isLocale sur la classe Translator ou par le helper trans pour déterminer les paramètres régionaux actuels ou vérifier si les paramètres régionaux correspondent à une valeur donnée:

use Bow\Translate\Translator;

$locale = Translator::getLocale();

if (Translator::isLocale('en')) {
 //
}

Via le helper trans

$locale = trans()->getLocale();

if (trans()->isLocale('en')) {
 //
}

Traductions manquantes

Si la chaîne de traduction spécifiée n'existe pas, la fonction t renverra la clé de la chaîne de traduction. Ainsi, à l'aide de l'exemple ci-dessus, la fonction t renverrait messages.welcome si la chaîne de traduction n'existe pas.

Remplacement de paramètres dans les chaînes de traduction

Si vous le souhaitez, vous pouvez définir des espaces réservés dans vos chaînes de traduction. Tous les espaces réservés sont encadrés par {}. Par exemple, vous pouvez définir un message de bienvenue avec un nom d'espace réservé:

'welcome' => 'Welcome, {name}',

Pour remplacer les espaces réservés lors de l'extraction d'une chaîne de traduction, transmettez un tableau de remplacements en tant que deuxième argument de la fonction t ou trans:

echo t('messages.welcome', ['name' => 'Galy']);

La pluralisation

La pluralisation est un problème complexe, car différentes langues ont une variété de règles complexes pour la pluralisation. En utilisant un caractère "pipe" (|), vous pouvez distinguer les formes singulière et plurielle d'une chaîne :

"names" => "C'est un utilisateur|Ce sont des utilisateurs",

Après avoir défini une chaîne de traduction comportant des options de pluralisation, vous pouvez utiliser la fonction t ou trans. Dans cet exemple, puisque le nombre est supérieur à un, la forme au pluriel de la chaîne de traduction est renvoyée:

echo t("messages.names", count($names) > 1);

Pluralisation avec remplacement

Avec les données remplacées :

"names" => "Bonjour {name}|Bonjour à tous",

echo t("messages.names", ["name" => "Newt"], count($names) == 1);
// => Bonjour Mewt

Il manque quelque chose ?

Si vous rencontrez des problèmes avec la documentation ou si vous avez des suggestions pour améliorer la documentation ou le projet en général, veuillez déposer une issue pour nous, ou envoyer un tweet mentionnant le compte Twitter @bowframework ou sur directement sur le github.