table des matières
Le terme «internationalisation» (souvent abrégé en i18n ) se réfère au processus de chaînes de résumés et d'autres paramètres régionaux spécifiques pièces hors de votre demande et dans une couche où ils peuvent être traduits et convertis sur la base locale de l'utilisateur (la langue soit et par pays). Pour le texte, cela signifie envelopper chacun ayant une fonction capable de traduire le texte (ou "message") dans la langue de l'utilisateur:
// text will *always* print out in English echo 'Hello World'; // text can be translated into the end-user's language or default to English echo $translator->trans('Hello World');
Le terme se réfère locale à peu près à la langue de l'utilisateur et le pays. Il peut être n'importe quelle chaîne que votre application utilise ensuite pour gérer les traductions et les différences de format (format monétaire d'autres, par exemple). Nous avons recommandé le code ISO639-1 langue, un trait de soulignement (_), puis le code ISO3166 pays (par exemple fr_FR pour le français/France).
Dans ce chapitre, nous allons apprendre à préparer une demande d'appuyer plusieurs paramètres régionaux, puis la façon de créer des traductions pour plusieurs locales. Globalement, le processus a plusieurs étapes communes:
Les traductions sont traitées par un traducteur de service qui utilise la locale de l'utilisateur pour rechercher et retourner des messages traduits. Avant de l'utiliser, de permettre le traducteur dans votre configuration:
# app/config/config.yml framework: translator: { fallback: en }
<!-- app/config/config.xml -->
<framework:config>
<framework:translator fallback="en" />
</framework:config>
// app/config/config.php $container->loadFromExtension('framework', array( 'translator' = > array('fallback' = > 'en'), ));
L'option de repli définit les paramètres régionaux de secours quand une traduction n'existe pas dans la localisation de l'utilisateur.
Si la traduction n'existe pas pour un lieu, le traducteur essaie d'abord de trouver la traduction de la langue (fr si la locale est fr_FR, par exemple). Si cette tentative échoue également, il cherche une traduction à l'aide locale de secours.
Le local utilisé dans les traductions est celle stockée dans la session utilisateur.
Traduction du texte se fait par l'intermédiaire du service de traduction ( Traducteur ). Pour traduire un bloc de texte (appelé un message), utilisez la trans() méthode. Supposons, par exemple, que nous la traduction d'un message simple à l'intérieur d'un contrôleur:
public function indexAction() { $t = $this->get('translator')->trans('Symfony2 is great'); return new Response($t); }
Lorsque ce code est exécuté, Symfony2 va tenter de traduire le message "Symfony2 est grand" sur la base de la localisation de l'utilisateur. Pour que cela fonctionne, nous devons dire à Symfony2 comment traduire le message par l'intermédiaire d'une «ressource de traduction", qui est une collection de traductions de messages pour un endroit donné. Ce «dictionnaire» des traductions peuvent être créés dans plusieurs formats différents, XLIFF est le format recommandé:
<!-- messages.fr.xliff --> <?xml version="1.0"?> <xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2"> <file source-language="en" datatype="plaintext" original="file.ext"> <body> <trans-unit id="1"> <source>Symfony2 is great</source> <target>J'aime Symfony2</target> </trans-unit> </body> </file> </xliff>
// messages.fr.php return array( 'Symfony2 is great' = > 'J\'aime Symfony2', );
# messages.fr.yml Symfony2 is great: J'aime Symfony2
Maintenant, si la langue de localisation de l'utilisateur est le français (par exemple fr_FR ou fr_BE), le message sera traduit en Symfony2 J'aime.
Pour réellement traduire le message, Symfony2 utilise un processus simple:
Lorsque vous utilisez la méthode trans(), Symfony2 recherche la chaîne exacte à l'intérieur du catalogue de messages approprié et elle renvoie (si elle existe).
Parfois, un message contenant une variable doit être traduit:
public function indexAction($name) { $t = $this->get('translator')->trans('Hello '.$name); return new Response($t); }
Toutefois, la création d'une traduction pour cette chaîne est impossible puisque le traducteur va essayer de rechercher le message exact, y compris les parties variables (par exemple "Bonjour Ryan" ou "Bonjour Fabien"). Au lieu d'écrire une traduction pour chaque itération possible de la variable $name, nous pouvons remplacer la variable avec un "espace réservé":
public function indexAction($name) { $t = $this->get('translator')->trans('Hello %name%', array('%name%' = > $name)); new Response($t); }
Symfony2 allons maintenant examiner pour une traduction du message brut (Hello %name%), puis remplacer les espaces réservés avec leurs valeurs. Création d'une traduction se fait comme avant:
<!-- messages.fr.xliff --> <?xml version="1.0"?> <xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2"> <file source-language="en" datatype="plaintext" original="file.ext"> <body> <trans-unit id="1"> <source>Hello %name%</source> <target>Bonjour %name%</target> </trans-unit> </body> </file> </xliff>
// messages.fr.php return array( 'Hello %name%' = > 'Bonjour %name%', );
# messages.fr.yml 'Hello %name%': Hello %name%
Les espaces réservés peuvent prendre n'importe quelle forme que l'intégralité du message est reconstruite en utilisant le PHP fonction strtr . Cependant, la notation %var% est nécessaire lors de la traduction dans le template Twig, et est globalement une convention raisonnable à suivre.
Comme nous l'avons vu, la création d'une traduction est un processus en deux étapes:
La deuxième étape se fait en créant des catalogues de messages qui définissent les traductions pour un certain nombre de lieux différents.
Quand un message est traduit, Symfony2 compile un catalogue de messages correspondant à la localisation de l'utilisateur et il se regarde dans une traduction du message. Un catalogue de messages est comme un dictionnaire de traduction pour une langue spécifique. Par exemple, le catalogue de la locale fr_FR peut contenir la traduction suivante:
Symfony2 est grand = > J'aime Symfony2
C'est la responsabilité du développeur (ou le traducteur) d'une application internationalisée pour créer ces traductions. Les traductions sont stockées sur le système de fichiers et découvert par Symfony, grâce à des conventions.
Chaque fois que vous créez une ressource nouvelle traduction (ou d'installer un paquet qui comprend une ressource de traduction), assurez-vous de vider votre cache afin que symfony puisse découvrir la ressource une nouvelle traduction:
php app/console cache:clear
Symfony2 cherche les fichiers de messages (traductions) dans deux endroits:
Le nom du fichier des traductions est également important que Symfony2 utilise une convention pour déterminer les détails sur les traductions. Chaque fichier de message doit être nommé selon le schéma suivant: domain.locale.loader:
Le chargeur peut être le nom d'un chargeur recommandé. Par défaut, Symfony fournit les chargeurs suivants:
Le choix du chargeur à utiliser est entièrement à vous et est une question de goût.
Vous pouvez également stocker des traductions dans une base de données, ou tout autre stockage en fournissant une classe personnalisée mise en œuvre de d'interface LoaderInterface.
L'acte de créer des fichiers de traduction est un élément important de la «localisation» (souvent abrégé L10n ). Les fichiers de traduction se composent d'une série de paires id-traduction pour le domaine donné et locale. L'id est l'identificateur de la traduction individuelle, et peut être le message dans l'environnement local principal (par exemple "Symfony est grand») de votre application ou un identifiant unique (par exemple "symfony2.great" - voir l'encadré ci-dessous):
<!-- src/Acme/DemoBundle/Resources/translations/messages.fr.xliff --> <?xml version="1.0"?> <xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2"> <file source-language="en" datatype="plaintext" original="file.ext"> <body> <trans-unit id="1"> <source>Symfony2 is great</source> <target>J'aime Symfony2</target> </trans-unit> <trans-unit id="2"> <source>symfony2.great</source> <target>J'aime Symfony2</target> </trans-unit> </body> </file> </xliff>
// src/Acme/DemoBundle/Resources/translations/messages.fr.php return array( 'Symfony2 is great' = > 'J\'aime Symfony2', 'symfony2.great' = > 'J\'aime Symfony2', );
# src/Acme/DemoBundle/Resources/translations/messages.fr.yml Symfony2 is great: J'aime Symfony2 symfony2.great: J'aime Symfony2
Symfony2 découvrirez ces fichiers et de les utiliser lors de la traduction soit "Symfony2 est grand» ou «symfony2.great" dans un paramètre régional de langue française (par exemple fr_FR ou fr_BE).
Cet exemple illustre les deux philosophies différentes lors de la création des messages à être traduits:
$t = $translator->trans('Symfony2 is great'); $t = $translator->trans('symfony2.great');
Dans la première méthode, les messages sont écrits dans la langue de la langue par défaut (en anglais dans ce cas). Ce message est ensuite utilisé comme "id" lors de la création traductions.
Dans la seconde méthode, les messages sont en fait des «mots clés» qui véhiculent l'idée du message. Le message clé est ensuite utilisée comme "id" pour toutes les traductions. Dans ce cas, les traductions doivent être faites pour la langue par défaut (c.-à-traduire symfony2.great à Symfony2 est grand).
La seconde méthode est pratique car la clé de message n'aura pas besoin d'être changé dans chaque fichier de traduction si nous décidons que le message devrait effectivement lire "Symfony2 est vraiment super» dans la langue par défaut.
Le choix de la méthode à utiliser est entièrement à vous, mais le "mot-clé" format est souvent recommandé.
En outre, le php et les formats de fichier YAML Support d'IDS imbriqués pour éviter de vous répéter si vous utilisez des mots-clés plutôt que du texte réel pour vos identifiants:
symfony2: is: great: Symfony2 is great amazing: Symfony2 is amazing has: bundles: Symfony2 has bundles user: login: Login
return array( 'symfony2' => array( 'is' => array( 'great' => 'Symfony2 is great', 'amazing' => 'Symfony2 is amazing', ), 'has' => array( 'bundles' => 'Symfony2 has bundles', ), ), 'user' => array( 'login' => 'Login', ), );
Les multiples niveaux sont aplaties dans une paire de simple id/traduction en ajoutant un point entre tous les niveaux, par conséquent, les exemples ci-dessus sont équivalentes à ce qui suit:
symfony2.is.great: Symfony2 is great symfony2.is.amazing: Symfony2 is amazing symfony2.has.bundles: Symfony2 has bundles user.login: Login
return array( 'symfony2.is.great' = > 'Symfony2 is great', 'symfony2.is.amazing' = > 'Symfony2 is amazing', 'symfony2.has.bundles' = > 'Symfony2 has bundles', 'user.login' = > 'Login', );
Comme nous l'avons vu, les fichiers de messages sont organisés dans les différents lieux qu'ils traduisent. Les fichiers de messages peuvent également être organisées plus loin dans "Domaines". Lors de la création des fichiers de messages, le domaine est la première partie du nom de fichier. Le nom de domaine par défaut est messages. Par exemple, supposons que, pour l'organisation, les traductions sont divisés en trois domaines différents: messages, admin et de navigation. La traduction française aurait les fichiers de messages suivants:
Lors de la traduction des chaînes qui ne sont pas dans le domaine par défaut (messages), vous devez spécifier le nom de domaine que le troisième argument de trans():
$this->get('translator')->trans('Symfony2 is great', array(), 'admin');
Symfony2 va maintenant chercher le message dans le domaine d'administration de la localisation de l'utilisateur.
La localisation de l'utilisateur courant est stockée dans la session et est accessible via le service de session:
$locale = $this->get('session')->getLocale(); $this->get('session')->setLocale('en_US');
Si les paramètres régionaux n'a pas été défini explicitement dans la session, le paramètre de configuration fallback_locale seront utilisées par le traducteur. Le paramètre par défaut (voir en configuration ).
Alternativement, vous pouvez garantir que les paramètres régionaux sont mis sur la session de l'utilisateur en définissant un default_locale pour le service de session:
# app/config/config.yml framework: session: { default_locale: en }
<!-- app/config/config.xml -->
<framework:config>
<framework:session default-locale="en" />
</framework:config>
// app/config/config.php $container->loadFromExtension('framework', array( 'session' => array('default_locale' => 'en'), ));
Depuis que la localisation de l'utilisateur est stocké dans la session, il peut être tentant d'utiliser la même URL pour afficher une ressource dans de nombreuses langues différentes en fonction de la localisation de l'utilisateur. Par exemple, http://www.example.com/contact pourrait afficher le contenu en anglais pour un utilisateur et en français pour un autre utilisateur. Malheureusement, cela viole une règle fondamentale du Web: l'URL particulière que retournerait la ressource suivant l'utilisateur. Encore plus embrouillée quelle version du contenu sera indexé par les moteurs de recherche?
Une meilleure politique est d'inclure la localisation dans l'URL. Ceci est entièrement supporté par le système de routage à l'aide du paramètre spécial _locale:
contact: pattern: /{_locale}/contact defaults: { _controller: AcmeDemoBundle:Contact:index, _locale: en } requirements: _locale: en|fr|de
<route id="contact" pattern="/{_locale}/contact"> <default key="_controller">AcmeDemoBundle:Contact:index</default> <default key="_locale">en</default> <requirement key="_locale">en|fr|de</requirement> </route>
use Symfony\Component\Routing\RouteCollection; use Symfony\Component\Routing\Route; $collection = new RouteCollection(); $collection->add('contact', new Route('/{_locale}/contact', array( '_controller' => 'AcmeDemoBundle:Contact:index', '_locale' => 'en', ), array( '_locale' => 'en|fr|de' ))); return $collection;
Lorsque vous utilisez le paramètre spécial _locale dans un itinéraire, la localisation adaptée sera automatiquement réglé sur la session de l'utilisateur. En d'autres termes, si un utilisateur visite l'URI/fr/contact, le fr locale aura automatiquement les paramètres régionaux pour la session de l'utilisateur.
Vous pouvez maintenant utiliser la localisation de l'utilisateur pour créer des itinéraires à d'autres pages traduites dans votre application.
Pluralisation des messages est un sujet difficile que les règles peuvent être assez complexes. Par exemple, voici la représentation mathématique des règles de pluriel des noms russes:
(($number % 10 == 1) && ($number % 100 != 11)) ? 0 : ((($number % 10 >= 2) && ($number % 10 <= 4) && (($number % 100 < 10) || ($number % 100 >= 20))) ? 1 : 2);
Comme vous pouvez le voir, en russe, vous pouvez avoir trois formes plurielles différentes, chacune étant donné un indice de 0, 1 ou 2. Pour chaque formulaire, le pluriel est différente, et donc la traduction est également différente.
Si la traduction a des formes différentes en raison de la pluralisation, vous pouvez fournir toutes les formes comme une chaîne séparée par un pipe (|):
'There is one apple|There are %count% apples'
Pour traduire les messages pluriel, utiliser la méthode transChoice()
$t = $this->get('translator')->transChoice( 'There is one apple|There are %count% apples', 10, array('%count%' => 10) );
Le second argument (10 dans cet exemple), est le nombre d'objets décrits et est utilisé pour déterminer quelle traduction à utiliser et aussi pour remplir l'espace réservé %count%.
Basé sur le nombre donné, le traducteur choisit la forme du pluriel droite. En anglais, la plupart des mots ont une forme singulière quand il ya exactement un objet et une forme plurielle pour tous les autres numéros (0, 2, 3 ...). Donc, si le compte est 1, le traducteur va utiliser la première chaîne (Il y a une pomme) que la traduction. Sinon, il utilisera des pommes %count%.
Voici la traduction française:
'Il y a %count% pomme|Il y a %count% pommes'
Même si la chaîne ressemble (il est constitué de deux sous-chaînes séparées par un tuyau), les règles françaises sont différentes: la première forme (pas de pluriel) est utilisé lorsque le nombre est 0 ou 1. Ainsi, le traducteur utilise automatiquement la première chaîne (Il y a pomme% count%) lorsque le nombre est 0 ou 1.
Chaque locale a son propre ensemble de règles, certaines ayant jusqu'à six différentes formes plurielles avec des règles complexes derrière laquelle numéros de carte à la forme plurielle qui. Les règles sont assez simples pour l'anglais et le français, mais pour le russe, vous voudrez peut-être un soupçon de savoir quelle règle correspond à quelle chaîne. Pour aider les traducteurs, vous pouvez éventuellement "tag" de chaque chaîne:
'one: There is one apple|some: There are %count% apples' 'none_or_one: Il y a %count% pomme|some: Il y a %count% pommes'
Les balises ne sont des indices en réalité que pour les traducteurs et n'affectent pas la logique utilisée pour déterminer quel pluriel à utiliser. Les étiquettes peuvent être n'importe quelle chaîne descriptive qui se termine par deux points (:). Les balises aussi n'ont pas besoin d'être le même dans le message d'origine comme dans la traduction.
La meilleure façon de mettre au pluriel un message est de laisser Symfony2 utilisation logique interne choisir quelle chaîne à utiliser en fonction d'un nombre donné. Parfois, vous aurez besoin de plus de contrôle ou si vous voulez une traduction différente pour les cas spécifiques (pour 0, ou lorsque le nombre est négatif, par exemple). Pour de tels cas, vous pouvez utiliser des intervalles mathématiques explicites:
'{0} There are no apples|{1} There is one apple|]1,19] There are %count% apples|[20,Inf] There are many apples'
Les intervalles suive la notation ISO 31-11 . La chaîne ci-dessus spécifie quatre intervalles différents: exactement 0, 1, 2-19 exactement, et 20 et plus.
Vous pouvez également mélanger les règles mathématiques explicites et des règles standard. Dans ce cas, si le décompte n'est pas compensée par un intervalle spécifique, les règles standard en vigueur après la suppression des règles explicites:
'{0} There are no apples|[20,Inf] There are many apples|There is one apple|a_few: There are %count% apples'
Par exemple, pour 1 pomme, la règle standard "Il y a une pomme" sera utilisé. Pour les pommes 2-19, la deuxième règle la norme "Il y a %count% pommes" seront sélectionnés.
Un intervalle peut représenter un ensemble fini de nombres:
{1, 2, 3, 4}
Ou des nombres compris entre deux autres nombres:
[1, +Inf[ ]-1,2[
Le délimiteur gauche peut être [(inclus) ou] (exclusif). Le droit délimiteur peut être [(exclusif) ou] (inclus). A côté des chiffres, vous pouvez utiliser-Inf et Inf + l'infini.
La plupart du temps, la traduction se produit dans les modèles. Symfony2 fournit un support natif pour les deux rameaux et PHP modèles.
Symfony2 offre des services spécialisés Twig balises (trans et transchoice) pour aider à la traduction des messages de blocs statiques de texte:
{% trans %}Hello %name%{% endtrans %}
{% transchoice count %}
{0} There are no apples|{1} There is one apple|]1,Inf] There are %count% apples
{% endtranschoice %}
La balise transchoice obtient automatiquement la variable% count% à partir du contexte actuel et il passe pour le traducteur. Ce mécanisme fonctionne uniquement lorsque vous utilisez un espace réservé suivant la pattern %var%
Si vous avez besoin d'utiliser le caractère pour cent (%) dans une chaîne, il faut l'échapper en le doublant: {% trans %} Pourcentage: %pour cent%%% {% endtrans %}
Vous pouvez également spécifier le domaine de message et passer quelques variables supplémentaires:
{% trans with {'%name%': 'Fabien'} from "app" %}Hello %name%{% endtrans %}
{% trans with {'%name%': 'Fabien'} from "app" into "fr" %}Hello %name%{% endtrans %}
{% transchoice count with {'%name%': 'Fabien'} from "app" %}
{0} There is no apples|{1} There is one apple|]1,Inf] There are %count% apples
{% endtranschoice %}
Les filtres trans et transchoice peut être utilisé pour traduire des textes variables et des expressions complexes:
{{ message|trans }}
{{ message|transchoice(5) }}
{{ message|trans({'%name%': 'Fabien'}, "app") }}
{{ message|transchoice(5, {'%name%': 'Fabien'}, 'app') }}
En utilisant les balises de traduction ou des filtres ont le même effet, mais avec une différence subtile: sortie automatique qui s'échappe est seulement appliquée aux variables traduites en utilisant un filtre. En d'autres termes, si vous avez besoin pour être sûr que votre variable traduit n'est pas sortie échappée, vous devez appliquer le filtre brut après le filtre de traduction:
{# text translated between tags is never escaped #}
{% trans %}
<h3>foo</h3>
{% endtrans %}
{% set message = '<h3>foo</h3>' %}
{# a variable translated via a filter is escaped by default #}
{{ message|trans|raw }}
{# but static strings are never escaped #}
{{ '<h3>foo</h3>'|trans }}
Le service de traduction est accessible dans templates PHP grâce à l'assistant traducteur:
<?php echo $view['translator']->trans('Symfony2 is great') ?> <?php echo $view['translator']->transChoice( '{0} There is no apples|{1} There is one apple|]1,Inf[ There are %count% apples', 10, array('%count%' = > 10) ) ?>
Lors de la traduction d'un message, Symfony2 utilise les paramètres régionaux de la session de l'utilisateur ou l'environnement local de repli si nécessaire. Vous pouvez également spécifier manuellement les paramètres régionaux à utiliser pour la traduction:
$this->get('translator')->trans( 'Symfony2 is great', array(), 'messages', 'fr_FR', ); $this->get('translator')->trans( '{0} There are no apples|{1} There is one apple|]1,Inf[ There are %count% apples', 10, array('%count%' => 10), 'messages', 'fr_FR', );
La traduction du contenu de base de données devrait être gérée par Doctrine par l'extension traduisible . Pour plus d'informations, consultez la documentation de cette bibliothèque.
La meilleure façon de comprendre la traduction contrainte est de la voir en action. Pour commencer, supposons que vous avez créé un objet simple-old-PHP que vous avez besoin d'utiliser quelque part dans votre application:
// src/Acme/BlogBundle/Entity/Author.php namespace Acme\BlogBundle\Entity; class Author { public $name; }
Ajouter des contraintes quoique l'une des méthodes prises en charge. Réglez l'option de message au texte source de traduction. Par exemple, pour garantir que la propriété $name n'est pas vide, ajouter ce qui suit:
# src/Acme/BlogBundle/Resources/config/validation.yml Acme\BlogBundle\Entity\Author: properties: name: - NotBlank: { message: "author.name.not_blank" }
// src/Acme/BlogBundle/Entity/Author.php use Symfony\Component\Validator\Constraints as Assert; class Author { /** * @Assert\NotBlank(message = "author.name.not_blank") */ public $name; }
<!-- src/Acme/BlogBundle/Resources/config/validation.xml --> <?xml version="1.0" encoding="UTF-8" ?> <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd"> <class name="Acme\BlogBundle\Entity\Author"> <property name="name"> <constraint name="NotBlank"> <option name="message">author.name.not_blank</option> </constraint> </property> </class> </constraint-mapping>
// src/Acme/BlogBundle/Entity/Author.php use Symfony\Component\Validator\Mapping\ClassMetadata; use Symfony\Component\Validator\Constraints\NotBlank; class Author { public $name; public static function loadValidatorMetadata(ClassMetadata $metadata) { $metadata->addPropertyConstraint('name', new NotBlank(array( 'message' => 'author.name.not_blank' ))); } }
Créer un fichier de traduction dans le cadre du catalogue des validateurs pour les messages de contraintes, généralement dans les répertoires Resources/translations/ des traductions du bundle.
<!-- validators.fr.xliff --> <?xml version="1.0"?> <xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2"> <file source-language="en" datatype="plaintext" original="file.ext"> <body> <trans-unit id="1"> <source>author.name.not_blank</source> <target>Please enter an author name.</target> </trans-unit> </body> </file> </xliff>
// validators.fr.php return array( 'author.name.not_blank' = > 'Please enter an author name.', );
# validators.fr.yml author.name.not_blank: Please enter an author name.
Avec le composant de traduction Symfony2, la création d'une application internationalisée n'a plus besoin d'être un processus difficile et se résume à quelques étapes de base: