L'étape suivante est la création des sources de traduction pour les multiples langues vers lesquelles vous traduisez. Chaque adaptateur est créé de sa propre manière comme décrit ici. Mais il y a quelques dispositifs généraux qui sont valables pour tous les adaptateurs.

Vous devrez savoir où stocker vos fichiers sources de traduction. Avec Zend_Translate vous n'avez aucune restriction. Les structures suivantes sont préférables :

Les fichiers source uniques et structurés par langue sont les plus utilisés pour Zend_Translate.

Maintenant, que nous connaissons la structure que nous voulons avoir, nous devons créer nos fichiers sources de traduction.

Les fichiers sources de type tableau sont simplement des tableaux. Mais vous devez les définir manuellement parce qu'il n'y a aucun outil pour automatiser cela. Mais parce qu'ils sont très simples, ils représentent la manière la plus rapide de rechercher des messages si votre code fonctionne comme prévu. C'est généralement le meilleur adaptateur pour démarrer avec des systèmes multilingues.

$english = array('message1' => 'message1',
                 'message2' => 'message2',
                 'message3' => 'message3');
$german = array('message1' => 'Nachricht1',
                'message2' => 'Nachricht2',
                'message3' => 'Nachricht3');

$translate = new Zend_Translate('array', $english, 'en');
$translate->addTranslation($deutsch, 'de');

Depuis la version 1.5 il est également possible d'avoir des tableaux inclus dans un fichier externe. Vous devez simplement fournir le nom de fichier, Zend_Translate l'inclura automatiquement et recherchera le tableau. Voir l'exemple suivant pour les détails :

// montableau.php
return array(
    'message1' => 'Nachricht1',
    'message2' => 'Nachricht2',
    'message3' => 'Nachricht3');

// contrôleur
$translate = new Zend_Translate('array',
                                'chemin/vers/montableau.php',
                                'de');

Des fichiers source Gettext sont créés par la bibliothèque GNU gettext. Il y a plusieurs outils libres disponibles qui peuvent analyser vos fichiers de code et créer les fichiers sources nécessaires à gettext. Ces fichiers se terminent par *.mo et ce sont des fichiers binaires. Un gratuiciel pour créer ces fichiers est poEdit. Cet outil vous aide également pour le processus de traduction lui-même.

// Les fichiers mo sont créés et déjà traduits
$translate = new Zend_Translate('gettext',
                                'chemin/vers/english.mo',
                                'en');
$translate->addTranslation('chemin/vers/german.mo', 'de');

Comme vous pouvez le voir, les adaptateurs sont utilisés exactement de la même manière, avec juste une petite différence : changer "array" en "gettext". Toutes autres utilisations sont exactement les mêmes qu'avec tous autres adaptateurs. Avec l'adaptateur de gettext vous ne devez plus vous occuper de la structure des répertoires, du "bindtextdomain" et du "textdomain". Fournissez juste le chemin et le nom de fichier à l'adaptateur.

La plupart des éditeur gettext ajoutent les informations de l'adaptateur comme chaines de traduction vides. C'est pour cela que traduire des chaines vides ne fonctionne pas avec l'adaptateur gettext. A la place, elles sont effacées de la table de traduction. getAdapterInfo() retourne les informations de l'adaptateur gettext, notamment les informations des fichiers gettext ajoutés.

// Informations sur l'adaptateur
$translate = new Zend_Translate('gettext',
                                'path/to/english.mo',
                                'en');
print_r $translate->getAdapterInfo();

Les fichiers sources TMX sont les nouveaux standards industriels. Ils ont l'avantage d'être des fichiers XML et ainsi ils sont lisibles par tout éditeur de fichier et naturellement ils sont lisibles pour l'homme. Vous pouvez soit créer des fichiers TMX manuellement avec un éditeur de texte, soit utiliser un outil. Mais la plupart des programmes actuellement disponibles pour développer des fichiers source TMX ne sont pas des gratuiciels.

<?xml version="1.0" ?>
<!DOCTYPE tmx SYSTEM "tmx14.dtd">
<tmx version="1.4">
 <header creationtoolversion="1.0.0" datatype="winres"
         segtype="sentence" adminlang="en-us" srclang="de-at"
         o-tmf="abc" creationtool="XYZTool" >
 </header>
 <body>
  <tu tuid='message1'>
   <tuv xml:lang="de"><seg>Nachricht1</seg></tuv>
   <tuv xml:lang="en"><seg>message1</seg></tuv>
  </tu>
  <tu tuid='message2'>
   <tuv xml:lang="en"><seg>message2</seg></tuv>
   <tuv xml:lang="de"><seg>Nachricht2</seg></tuv>
  </tu>

$translate = new Zend_Translate('tmx',
                                'chemin/vers/mytranslation.tmx',
                                'en');
// TMX peut contenir différentes langues dans le même fichier

Les fichiers TMX peuvent avoir plusieurs langues dans le même fichier. Toute autre langue incluse est ajoutée automatiquement, ainsi vous n'avez pas à appeler addLanguage().

Si vous voulez avoir seulement les langues spécifiées de la source traduite, vous pouvez régler l'option defined_language à TRUE. Avec cette option vous pouvez ajouter les langues souhaitées explicitement avec addLanguage(). La valeur par défaut pour cette option est d'ajouter toutes les langues.

Les fichiers sources CSV sont petits et lisibles pour l'homme. Si vos clients veulent eux-mêmes traduire, vous utiliserez probablement l'adaptateur CSV.

#Exemple de fichier csv
message1;Nachricht1
message2;Nachricht2

$translate = new Zend_Translate('csv',
                                'chemin/vers/matraduction.csv',
                                'de');
$translate->addTranslation('chemin/vers/autretraduction.csv',
                           'fr');

Il existe trois options différentes pour l'adaptateur CSV. Vous pouvez paramétrer "delimiter", "limit" et "enclosure".

Le délimiteur standard des fichiers CSV est le signe ";". Mais celui-ci n'est pas obligatoire. Avec l'option "delimiter" vous pouvez décider d'utiliser un autre signe de séparation.

La taille limite d'une ligne de fichier CSV est par défaut "0" Ce qui veut dire que la fin de la ligne est recherchée automatiquement. Si vous paramétrez l'option "limit" avec une valeur quelconque, alors le fichier CSV sera lu plus rapidement, mais toute ligne dont la longueur excédera la limite sera tronquée.

"L'échappement" par défaut d'un fichier CSV est le """. Vous pouvez en paramétrer un autre avec l'option "enclosure".

#Exemple de fichier csv
# original 'message,1'
"message,1",Nachricht1
# traduction 'Nachricht,2'
message2,"Nachricht,2"
# original 'message3,'
"message3,",Nachricht3

$translate = new Zend_Translate('csv',
                                'chemin/vers/matraduction.csv',
                                'de',
                                array('delimiter' => ','));
$translate->addTranslation('chemin/vers/autretraduction.csv',
                           'fr');

Les fichiers sources INI sont lisibles par l'homme mais habituellement pas très petits puisqu'ils incluent également d'autres données à côté des traductions. Si vous avez des données qui seront éditables par vos clients, vous pouvez aussi utiliser l'adaptateur INI dans ce cas.

[Test]
;Commentaires possibles
Message_1="Nachricht 1 (de)"
Message_2="Nachricht 2 (de)"
Message_3="Nachricht :3 (de)"

$translate = new Zend_Translate('ini',
                                'path/to/mytranslation.ini',
                                'de');
$translate->addTranslation('path/to/other.ini',
                           'it');

Les fichiers INI ont de multiples restrictions. Si une valeur dans le fichier INI contient un caractère non-alphanumérique, il doit être entouré avec des guillemets doubles ("). Il y a aussi des mots réservés qui ne doivent pas être utilisés en tant que clés des fichiers INI. Ceci inclut : NULL, yes, no, TRUE et FALSE. Les valeurs NULL, no et FALSE sont retournées sous la forme "". yes et TRUE sont retournés en "1". Les caractères {}|&~![()" ne doivent pas être utilisés dans la clé et ont une signification particulière dans la valeur. Ne les utilisez pas ou vous rencontrerez des comportements inattendus.

Les options peuvent être utilisées avec tous les adaptateurs. Bien sûr chacun d'eux accepte des options différentes. Vous pouvez passer des options quand vous créez l'adaptateur. Pour l'instant il y a qu'une option qui est valable pour tous les adaptateurs. 'clear' décide si des données de traduction peuvent être ajoutées à l'existant ou non. Le comportement standard est d'ajouter des nouvelles données de traduction à l'existant. Les données de traduction sont seulement effacées pour la langue choisie. Donc on ne touchera pas aux autres langues.

Vous pouvez régler des options temporaires en utilisant addTranslation($data, $locale, array $options = array()) comme troisième paramètre optionnel. Ou vous pouvez utiliser la fonction setOptions() pour régler une option.

// définir ':' comme séparateur pour les fichiers sources de traduction
$options = array('delimiter' => ':');
$translate = new Zend_Translate('csv',
                                'chemin/vers/matraduction.csv',
                                'fr',
                                $options);

...

// efface le langage défini et utilise de nouvelles données de traduction
$options = array('clear' => true);
$translate->addTranslation('chemin/vers/nouveau.csv',
                           'en',
                           $options);

Ici vous pouvez trouver toutes les options disponibles pour les différents adaptateurs avec une description de leur utilisation :

Si vous souhaitez avoir vos propres définitions d'options, vous pouvez les utiliser avec tous les adaptateurs. La méthode setOptions() peut être utilisée pour définir vos options. La méthode setOptions() nécessite un tableau avec les options que vous voulez paramétrer. Si une option fournie existe déjà, elle sera alors ré-assignée. Vous pouvez définir autant d'options que nécessaire car elles ne seront pas vérifiées par l'adaptateur. Vérifiez simplement que vous ne créez pas une option qui existe déjà dans l'adaptateur, vous affecteriez alors une nouvelle valeur.

Pour récupérer l'ensemble des options, vous pouvez utiliser la méthode getOptions(). Quand getOptions() est appelée sans paramètre, elle retourne l'ensemble des options. Si un paramètre est fourni, seule l'option particulière sera retournée.

En travaillant avec différentes langues il y a quelques méthodes qui seront utiles.

La méthode getLocale() peut être utilisée pour récupérer la langue actuellement réglée. Elle peut retourner soit une instance de Zend_Locale, soit un identifiant de localisation.

La méthode setLocale() règle une nouvelle langue standard pour la traduction. Ceci évite de placer le paramètre facultatif de langue plus d'une fois lors de l'appel de la méthode translate(). Si la langue donnée n'existe pas, ou si aucune donnée de traduction n'est disponible pour la langue, setLocale() essaye de remonter à la langue sans région si elle est indiquée. Une langue fr_FR serait remontée à fr. Si la remontée n'est pas possible, une exception sera levée.

La méthode isAvailable() vérifie si une langue donnée est déjà disponible. Elle retourne TRUE si des données existent pour la langue fournie.

Et enfin la méthode getList() peut être utilisée pour récupérer sous la forme d'un tableau tous les langues paramétrées pour un adaptateur.

...
// retourne la langue paramétrée actuelle
$actual = $translate->getLocale();

...
// vous pouvez utiliser le paramètre optionel au moment de la traduction
echo $translate->_("mon_texte", "fr");
// ou paramètrer une langue standard
$translate->setLocale("fr");
echo $translate->_("mon_texte");
// référence à la langue de base... fr_CH sera remonté à fr
$translate->setLocale("fr_CH");
echo $translate->_("mon_texte");
...
// vérifie si la langue existe
if ($translate->isAvailable("fr")) {
    // la langue existe
}

// Assumons que le navigateur retourne ces valeurs
// HTTP_ACCEPT_LANGUAGE = "de_AT=1;fr=1;en_US=0.8";

// Exemple 1 :
$translate = new Zend_Translate('gettext',
                                '\my_it.mo',
                                'auto',
                                array('scan' => Zend_Translate::LOCALE_FILENAME);
// pas de langue trouvée, on retourne le messageid

// Exemple 2 :
$translate = new Zend_Translate('gettext',
                                '\my_fr.mo',
                                'auto',
                                array('scan' => Zend_Translate::LOCALE_FILENAME);
// langue correspondante trouvée "en_US"

// Exemple 3 :
$translate = new Zend_Translate('gettext',
                                '\my_de.mo',
                                'auto',
                                array('scan' => Zend_Translate::LOCALE_FILENAME);
// langue correspondante trouvée "de" car "de_AT" est descendue à "de"

// Exemple 4 :
$translate = new Zend_Translate('gettext',
                                '\my_it.mo',
                                'auto',
                                array('scan' => Zend_Translate::LOCALE_FILENAME);
$translate->addTranslation('\my_ru.mo', 'ru');
$translate->setLocale('it_IT');
// retourne "it_IT" comme source de traduction et surcharge le réglage automatique

// En fichier d'amorçage (bootstrap)
$locale = new Zend_Locale('de_AT');
Zend_Registry::set('Zend_Locale', $locale);

// ailleurs dans votre application
$translate = new Zend_Translate('gettext', '\my_de.mo');
$translate->getLocale();

Zend_Translate peut détecter les sources de traduction de manière automatique. Ainsi vous n'avez pas à déclarer toutes les sources manuellement. Vous laissez Zend_Translate faire ce travail et scanner complètement tout un répertoire à la recherche de fichiers de langue de traduction.

L'utilisation est assez semblable à celle qui permet de spécifier une source de langue. Vous devez simplement donner un dossier, et non plus un fichier, à l'adaptateur. Ce dossier sera alors scanné

// Soit la structure suivante :
//  /language
//  /language/login/login.tmx
//  /language/logout/logout.tmx
//  /language/error/loginerror.tmx
//  /language/error/logouterror.tmx

$translate = new Zend_Translate('tmx', '/language');

Notez que Zend_Translate cherche dans tous les sous-repertoires. L'utilisation devient alors relativement simple. Aussi, Zend_Translate ignorera tout fichier qui ne l'interresse pas : des fichiers non représentatifs de traductions ou encore des fichiers illisibles. Vérifiez donc que le dossier principal ne contienne que des fichiers de traductions, car Zend_Translate ne renverra aucune erreur dans le cas contraire, il ignorera simplement de tels fichiers.

Dans notre exemple, nous utilisons l'adaptateur TMX qui inclut la langue à utiliser dans le fichier en question. D'autres adaptateurs n'agissent pas comme cela, ainsi les noms de fichiers devront comporter les noms des langues à considérer pour de tels adaptateurs.

// expect we have the following structure
//  /language
//  /language/de/login/login.mo
//  /language/de/error/loginerror.mo
//  /language/en/login/login.mo
//  /language/en/error/loginerror.mo

$translate = new Zend_Translate('gettext',
                                '/language',
                                null,
                                array('scan' =>
                                    Zend_Translate::LOCALE_DIRECTORY));

// expect we have the following structure
//  /language
//  /language/login/login_en.mo
//  /language/login/login_de.mo
//  /language/error/loginerror_en.mo
//  /language/error/loginerror_de.mo

$translate = new Zend_Translate('gettext',
                                '/language',
                                null,
                                array('scan' =>
                                    Zend_Translate::LOCALE_FILENAME));

/languages
  en.mo
  de.mo
  es.mo

/languages
  view.en
  view.de
  view.es

/languages
  view_en.mo  -> detects english
  view_de.mo  -> detects german
  view_it.mo  -> detects italian

/languages
  view_en_de.mo  -> detects english
  view_en_es.mo  -> detects english and overwrites the first file
                    because the same messageids are used
  view_it_it.mo  -> detects italian

/languages
  view_en-it.mo  -> detects english because '_' will be used before '-'
  view-en_it.mo  -> detects italian because '_' will be used before '-'
  view_en.it.mo  -> detects italian because '.' will be used before '_'

Normalement le texte sera traduit sans aucun calcul. Mais il est quelquefois nécessaire si un texte est traduit ou non dans la source. Dans ce cas la méthode isTranslated() peut être utilisé.

isTranslated($messageId, $original = false, $locale = null) prend comme premier paramètre le texte dont vous voulez vérifier que la traduction est possible. Et comme troisième paramètre optionnel la langue dont vous voulez connaître la traduction. Le second paramètre optionnel détermine si la traduction est fixée à la langue déclarée ou si une autre langue peut être utilisée. Si vous avez un texte qui peut être traduit en "fr" mais pas en "fr_fr" vous obtiendriez normalement la traduction fournie, mais avec $original réglé à TRUE, la méthode isTranslated() retournera FALSE dans ce cas.

$english = array('message1' => 'Nachricht 1',
                 'message2' => 'Nachricht 2',
                 'message3' => 'Nachricht 3');
$translate = new Zend_Translate('array', $english, 'de_AT');

if ($translate->isTranslated('message1')) {
    print "'message1' peut être traduit";
}
if (!($translate->isTranslated('message1', true, 'de'))) {
    print "'message1' ne peut pas être traduit en 'de', "
        . "il est seulement disponible en 'de_AT'";
}
if ($translate->isTranslated('message1', false, 'de')) {
    print "'message1' peut être traduit en 'de_AT' "
        . "et par conséquent en 'de'";}

When you have a bigger site or you are creating the translation files manually, you often have the problem that some messages are not translated. But there is a easy solution for you when you are using Zend_Translate.

You have to follow two or three simple steps. First, you have to create a instance of Zend_Log. And then you have to attach this instance to Zend_Translate. See the following example:

$translate = new Zend_Translate('gettext', $path, 'de');

// Create a log instance
$writer = new Zend_Log_Writer_Stream('/path/file.log');
$log = new Zend_Log($writer);

// Attach it to the translation instance
$translate->setOptions(array(
    'log' => $log,
    'logUntranslated' => true));

$translate->translate('unknown string');

Now you will have in the log a new notice: Untranslated message within 'de': unknown string.

This feature can not only be used to log messages but also to attach this not translated messages into a empty translation file. To archive this you will have to write your own log writer which writes the format you want to have and strips the prepending "Untranslated message" for you.

You can also set the 'logMessage' option when you want to have your own log message. Use the '%message%' token for placing the messageId within your log message, and the '%locale%' token for the requested locale. See the following example for a self defined log message:

$translate = new Zend_Translate('gettext', $path, 'de');

// Create a log instance
$writer = new Zend_Log_Writer_Stream('/path/to/file.log');
$log    = new Zend_Log($writer);

// Attach it to the translation instance
$translate->setOptions(array(
    'log'             => $log,
    'logMessage'      => "Missing '%message%' within locale '%locale%'",
    'logUntranslated' => true));

$translate->translate('unknown string');

Of course sometimes it is useful to have access to the translation source data. Therefor two functions exist.

The getMessageIds($locale = null) method returns all known message ids as array.

And the getMessages($locale = null) method returns the complete translation source as array. The message id is used as key and the translation data as value.

Both methods accept an optional parameter $locale which, when set, returns the translation data for the specified language. If this parameter is not given, the actual set language will be used. Keep in mind that normally all translations should be available in all languages. Which means that in a normal situation you will not have to set this parameter.

Additionally the getMessages() method is able to return the complete translation dictionary with the pseudo-locale 'all'. This will return all available translation data for each added locale.

...
// returns all known message ids
$messageids = $translate->getMessageIds();
print_r($messageids);

...
// or just for the specified language
$messageids = $translate->getMessageIds('en_US');
print_r($messageids);

...
// returns all the complete translation data
$source = $translate->getMessages();
print_r($source);