17.2.2.1 Utiliser une traduction dans un programme PHP

17.2.2.1.1 Utiliser une forme simple

La fonction fournie en standard par PHP et la fonction gettext. Cette fonction permet de rechercher dans un catalogue la traduction correspondante au texte donné en paramètre.

// texte simple
print gettext("This is a text");
// texte avec une partie variable
printf(gettext("An error : [%s]"), $errorText);

Note : La fonction _ de PHP est un alias de gettext.

// écriture plus lisible en utilisant l'alias.
print _("This is a text");
printf(_("An error : [%s]"), $errorText);

Attention : La fonction gettext doit avoir comme argument un texte non vide. Si le texte est une chaîne vide alors c'est la description du catalogue qui est retournée.

Le texte à traduire est généralement écrit en anglais (ASCII) et ne comporte pas de caractère accentué. Ceci permet d'éviter les problème d'encodage lors de la génération du catalogue. Il est cependant possible de mettre des textes à traduire avec des accents (voir chapitre suivant).

Dans l'exemple précédent, le texte est très commun et il peut être défini dans un autre module avec une traduction différente.

Deux possibilités permettent de diminuer ce risque de doublon :

1. Utiliser un préfixe :

   print _("MyCatalog:This is a text");

2. Utiliser un contexte : 3.2.12

   print ___("This is a text", "MyContext");

La différence entre le préfixe et le contexte est que le contexte est explicitement indiqué dans le catalogue tandis que le préfixe est pris comme un texte simple.

La fonction ___ (triple blancs soulignés) est un alias de la fonction pgettext. Si le contexte est vide, cela est équivalent à l'utilisation de la fonction _ standard.

Ces fonctions ne sont pas natives de PHP, elles sont ajoutées par Dynacase.

17.2.2.1.2 Utiliser une forme plurielle

3.2.12 Les traductions des formes plurielles sont prises en compte par la bibliothèque gettext.

La forme plurielle est indiquée à l'aide la fonction php standard ngettext ou de la fonction npgettext et son alias n___ qui gèrent aussi les contextes.

printf(n___("%d document found", "%d documents found", $num, "MyContext") , $num);

Limitations : La localisation des formes plurielles fonctionne de manière partielle avec les nombres décimaux. En effet, la variable numérique de choix de la traduction doit être un entier. Pour un nombre décimal, seule la partie entière est prise en compte. Ainsi les nombres 1,3 et 1,6 seront pris comme 1. Cela sera correct pour le français qui considère que tout nombre compris entre ]-2, 2[ comme singulier. Mais cela sera incorrect en anglais qui considère que tout nombre différent de 1 ou -1 n'est pas singulier.