Internationalisation & Localisation¶

Fichiers de Langues¶

Les traductions peuvent être mises à disposition en utilisant des fichiers de langue stockés dans votre application. Le format par défaut pour ces fichiers est le format Gettext. Ces fichiers doivent être placés dans src/Locale/ et dans ce répertoire, il devrait y avoir un sous-dossier par langue que l’application doit prendre en charge:

/src
    /Locale
        /en_US
            default.po
        /en_GB
            default.po
            validation.po
        /es
            default.po

Le domaine par défaut est “default”, votre dossier locale devrait donc contenir au minimum le fichier default.po (cf. ci-dessus). Un domaine se réfère à un regroupement arbitraire de messages de traduction. Si aucun groupe n’est utilisé, le groupe par défaut est sélectionné.

Les messages du coeur extraits de la libairie CakePHP peuvent être stockés séparément dans un fichier cake.po dans src/Locale/. La librairie localized de CakePHP contient des traductions des chaînes de caractère du coeur (du domaine cake) pour l’interface client. Pour utiliser ces fichiers, liez les ou copiez les au bon endroit : src/Locale/<locale>/cake.po. Si votre locale est incomplète ou incorrecte, vous pouvez nous envoyer une PR dans ce dépôt pour corriger les erreurs.

Les plugins peuvent également contenir des fichiers de traduction, la convention est d’utiliser la version under_scored du nom du plugin comme domaine de la traduction des messages:

MyPlugin
    /src
        /Locale
            /fr
                my_plugin.po
            /de
                my_plugin.po

Les dossiers de traduction peuvent être composées d’un code à deux ou trois lettres ISO de la langue ou du nom de la locale ICU, par exemple fr_FR, es_AR, da_DK, qui contient en même temps la langue et le pays où elle est parlée.

La liste complète est disponible sur https://www.localeplanet.com/icu/.

Un fichier de traduction pourrait ressembler à ceci:

msgid "My name is {0}"
msgstr "Je m'appelle {0}"

msgid "I'm {0,number} years old"
msgstr "J'ai {0,number} ans"

Extraire les Fichiers Pot avec le Shell I18n¶

Pour créer les fichiers pot à partir de __() et des autres types de messages internationalisés qui se trouvent dans votre code, vous pouvez utiliser le shell i18n. Vous pouvez consulter le chapitre suivant pour en savoir plus.

Définir la Locale par Défaut¶

La locale par défaut se détermine dans le fichier config/app.php en définissant App.defaultLocale:

'App' => [
    ...
    'defaultLocale' => env('APP_DEFAULT_LOCALE', 'en_US'),
    ...
]

Cela permet de contrôler plusieurs aspects de votre application, incluant la langue de traduction par défaut, le format des dates, des nombres, et devises à chaque fois qu’un de ces éléments s’affiche, en utilisant les bibliothèques de localisation fournies par CakePHP.

Modifier la Locale pendant l’Exécution¶

Pour changer la langue des chaines de caractères traduites, vous pouvez appeler cette méthode:

use Cake\I18n\I18n;

// Avant 3.5, utilisez I18n::locale()
I18n::setLocale('de_DE');

Cela changera également le formatage des nombres et des dates lorsque vous utilisez les outils de localisation.

Utiliser des Variables dans les Traductions de Messages¶

Les fonctions de traduction vous permettent d’interpoler des variables dans les messages en utilisant des marqueurs définis dans le message lui-même ou dans la chaine traduite:

echo __("Hello, my name is {0}, I'm {1} years old", ['Sara', 12]);

Les marqueurs sont numériques et correspondent aux clés dans le tableau passé. Vous pouvez également passer à la fonction les variables en tant qu’arguments indépendants:

echo __("Small step for {0}, Big leap for {1}", 'Man', 'Humanity');

Toutes les fonctions de traduction intègrent le remplacement de placeholder:

__d('validation', 'The field {0} cannot be left empty', 'Name');

__x('alphabet', 'He read the letter {0}', 'Z');

le caractère ' (guillemet simple ou apostrophe) agit comme un caractère d’échappement dans les messages de traduction. Chaque variable entourée de guillemets simples ne sera pas remplacée et sera traitée en tant que texte littéral. Par exemple:

__("This variable '{0}' be replaced.", 'will not');

En utilisant deux guillemets simples côte à côte, vos variables seront remplacées correctement:

__("This variable ''{0}'' be replaced.", 'will');

Ces fonctions profitent des avantages du MessageFormatter ICU pour que vous puissiez traduire des messages, des dates, des nombres et des devises en même temps:

echo __(
    'Hi {0}, your balance on the {1,date} is {2,number,currency}',
    ['Charles', new FrozenTime('2014-01-13 11:12:00'), 1354.37]
);

// Retourne
Hi Charles, your balance on the Jan 13, 2014, 11:12 AM is $ 1,354.37

Les nombres dans les placeholders peuvent également être formatés avec un contrôle fin et précis sur la sortie:

echo __(
    'You have traveled {0,number} kilometers in {1,number,integer} weeks',
    [5423.344, 5.1]
);

// Retourne
You have traveled 5,423.34 kilometers in 5 weeks

echo __('There are {0,number,#,###} people on earth', 6.1 * pow(10, 9));

// Retourne
There are 6,100,000,000 people on earth

Voici la liste des balises spécifiques que vous pouvez mettre après le mot number:

• integer: Supprime la partie décimale

• currency: Ajoute le symbole de la devise locale et arrondit les décimales

• percent: Formate le nombre en pourcentage

Les dates peuvent également être formatées en utilisant le mot date après le nombre placeholder. Les options supplémentaires sont les suivantes:

• short

• medium

• long

• full

Le mot time après le nombre placeholder est également accepté et il comprend les mêmes options que date.

Pluriels¶

Une partie cruciale de l’internationalisation de votre application est de récupérer vos messages pluralisés correctement suivant les langues affichées. CakePHP fournit plusieurs possibilités pour sélectionner correctement les pluriels dans vos messages.

msgid "{0,plural,=0{No records found} =1{Found 1 record} other{Found # records}}"
msgstr "{0,plural,=0{Ningún resultado} =1{1 resultado} other{# resultados}}"

msgid "{placeholder,plural,=0{No records found} =1{Found 1 record} other{Found {1} records}}"
msgstr "{placeholder,plural,=0{Ningún resultado} =1{1 resultado} other{{1} resultados}}"

__('{0,plural,=0{No records found }=1{Found 1 record} other{Found # records}}', [0]);

// Retourne "Ningún resultado" puisque l'argument {0} est 0

__('{0,plural,=0{No records found} =1{Found 1 record} other{Found # records}}', [1]);

// Retourne "1 resultado" puisque l'argument {0} est 1

__('{placeholder,plural,=0{No records found} =1{Found 1 record} other{Found {1} records}}', [0, 'many', 'placeholder' => 2])
// Retourne "many resultados" puisque l'argument {placeholder} est 2 et
// l'argument {1} est 'many'

{ [count placeholder],plural, case1{message} case2{message} case3{...} ... }

msgid "search.results"
msgstr "{0,plural,=0{Ningún resultado} =1{1 resultado} other{{1} resultados}}"

__('search.results', [2, 2]);

// Retourne "2 resultados"

=0{No results} =1{...} other{...}

zero{No Results} one{One result} few{...} many{...} other{...}

# Un identificateur de message pour le singulier
msgid "One file removed"
# Une autre pour le pluriel
msgid_plural "{0} files removed"
# Traduction au singulier
msgstr[0] "Un fichero eliminado"
# Traduction au pluriel
msgstr[1] "{0} ficheros eliminados"

// Retourne: "10 ficheros eliminados"
$count = 10;
__n('One file removed', '{0} files removed', $count, $count);

// Il est également possible de l'utiliser dans un domaine
__dn('my_plugin', 'One file removed', '{0} files removed', $count, $count);

msgid "One file removed"
msgid_plural "{0} files removed"
msgstr[0] "{0} datoteka je uklonjena"
msgstr[1] "{0} datoteke su uklonjene"
msgstr[2] "{0} datoteka je uklonjeno"

Créer des Parsers de Messages¶

Il est possible de continuer à utiliser les mêmes conventions que CakePHP utilise mais d’utiliser un autre parser de messages que PoFileParser. Par exemple, si vous vouliez charger les messages de traduction en utilisant YAML, vous auriez d’abord besoin de créer la classe du parser:

namespace App\I18n\Parser;

class YamlFileParser
{

    public function parse($file)
    {
        return yaml_parse_file($file);
    }
}

Le fichier doit être créé dans le dossier src/I18n/Parser de votre application. Ensuite, créez les fichiers de traduction sous src/Locale/fr_FR/animals.yaml

Dog: Chien
Cat: Chat
Bird: Oiseau

Enfin, configurez le loader de traduction pour le domaine et la locale:

use Cake\I18n\MessagesFileLoader as Loader;

// Avant 3.5, utilisez translator()
I18n::setTranslator(
    'animals',
    new Loader('animals', 'fr_FR', 'yaml'),
    'fr_FR'
);

Créer des Traducteurs Génériques¶

Configurer des traducteurs en appelant I18n::setTranslator() pour chaque domaine et locale que vous devez supporter peut être fastidieux, spécialement si vous devez supporter plus que quelques locales. Pour éviter ce problème, CakePHP vous permet de définir des loaders de traduction génériques pour chaque domaine.

Imaginez que vous vouliez charger toutes les traductions pour le domaine par défaut et pour chaque langue depuis un service externe:

use Aura\Intl\Package;

I18n::config('default', function ($domain, $locale) {
    $locale = Locale::parseLocale($locale);
    $language = $locale['language'];
    $messages = file_get_contents("http://example.com/translations/$lang.json");

    return new Package(
        'default', // Formatter
        null, // Fallback (none for default domain)
        json_decode($messages, true)
    )
});

Le code ci-dessus appelle un service externe exemple pour charger un fichier JSON avec les traductions puis construit uniquement un objet Package pour chaque locale nécessaire dans l’application.

If you’d like to change how packages are loaded for all packages, that don’t have specific loaders set you can replace the fallback package loader by using the _fallback package:

I18n::config('_fallback', function ($domain, $locale) {
    // Custom code that yields a package here.
});

Pluriels et Contexte dans les Traducteurs Personnalisés¶

les tableaux utilisées pour setMessages() peuvent être conçus pour ordonner au traducteur d’enregistrer les messages sous différents domaines ou de déclencher une sélection de pluriel de style Gettext. Ce qui suit est un exemple d’enregistrement de traductions pour la même clé dans différents contextes:

[
    'He reads the letter {0}' => [
        'alphabet' => 'Él lee la letra {0}',
        'written communication' => 'Él lee la carta {0}'
    ]
]

De même vous pouvez exprimer des pluriels de style Gettext en utilisant le tableau de messages avec une clé de tableau imbriqué par forme plurielle:

[
    'I have read one book' => 'He leído un libro',
    'I have read {0} books' => [
        'He leído un libro',
        'He leído {0} libros'
    ]
]

Utiliser des Formateurs Différents¶

Dans les exemples précédents nous avons vu que les Packages sont construits en utilisant default en premier argument, et il était indiqué avec un commentaire qu’il correspondait au formateur à utiliser. Les formateurs sont des classes responsables d’interpoler les variables dans les messages de traduction et sélectionner la forme plurielle correcte.

Si vous avez à faire une application datée, ou que vous n’avez pas besoin de la puissance offerte par le formateur de message ICU, CakePHP fournit également le formateur sprintf:

return Package('sprintf', 'fallback_domain', $messages);

Les messages à traduire seront passés à la fonction sprintf() pour interpoler les variables:

__('Hello, my name is %s and I am %d years old', 'José', 29);

Il est possible de définir le formateur par défaut pour tous les traducteurs créés par CakePHP avant qu’ils soient utilisés pour la première fois. Cela n’inclut pas les traducteurs créés manuellement en utilisant les méthodes setTranslator() et config():

I18n::defaultFormatter('sprintf');

Parser les Données Datetime Localisées¶

Quand vous acceptez les données localisées, c’est sympa d’accepter les informations de type datetime dans un format localisé pour l’utilisateur. Dans un controller, ou Middleware, vous pouvez configurer les types Date, Time, et DateTime pour parser les formats localisés:

use Cake\Database\TypeFactory;

// Permet de parser avec le format de locale par défaut.
TypeFactory::build('datetime')->useLocaleParser();

// Configure un parser personnalisé du format de datetime.
TypeFactory::build('datetime')->useLocaleParser()->setLocaleFormat('dd-M-y');

// Vous pouvez aussi utiliser les constantes IntlDateFormatter.
TypeFactory::build('datetime')->useLocaleParser()
    ->setLocaleFormat([IntlDateFormatter::SHORT, -1]);

Le parsing du format par défaut est le même que le format de chaîne par défaut.

Convertir des Données de Requêtes du Fuseau Horaire de l’Utilisateur¶

Quand vous gérez des données d’utilisateurs situés dans différents fuseaux horaires, vous avez besoin de convertir ces datetimes de la requête vers le fuseau horaire de votre application. Vous pouvez utiliser setUserTimezone() depuis un controller ou Middleware pour faire cela plus simplement:

// Définir le fuseau horaire de l'utilisateur
TypeFactory::build('datetime')->setUserTimezone($user->timezone);

Une fois que c’est fait, quand votre application crée ou met à jour des entities à partir de la requête, l’ORM va convertir automatiquement les valeurs datetime du fuseau de l’utilisateur vers le fuseau de votre application. Cela garantit que l’application travaillera toujours dans le fuseau horaire défini dans App.defaultTimezone.

Si votre application gère des données datetime dans de nombreuses actions, vous pouvez utiliser un middleware pour définir à la fois la conversion du décalage horaire et le format localisé:

namespace App\Middleware;

use Cake\Database\TypeFactory;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\MiddlewareInterface;
use Psr\Http\Server\RequestHandlerInterface;

class DatetimeMiddleare implements MiddlewareInterface
{
    public function process(
        ServerRequestInterface $request,
        RequestHandlerInterface $handler
    ): ResponseInterface {
        // Obtenir l'utilisateur depuis la requête.
        // Cet exemple suppose que votre entity utilisteur a un attribut timezone.
        $user = $request->getAttribute('identity');
        if ($user) {
            TypeFactory::build('datetime')
                ->useLocaleParser()
                ->setUserTimezone($user->timezone);
        }

        return $handler->handle($request);
    }
}