La fonction t()

La fonction t() (translate) est une fonction du cœur de Drupal.

t($string, array $args = array(), array $options = array())

Cette fonction, implémentée dans le fichier ./includes/bootstrap.inc, permet de traduire une chaîne dans la langue courante ou une langue donnée (dans la variable $options).

La fonction t a deux finalités. Tout d'abord, elle traduit le texte visible par l'utilisateur dans la langue appropriée. Deuxièmement, si ce n'est pas déjà fait, elle ajoute le texte passé en argument dans la table de la base de données contenant les chaînes à traduire.

print t('This is a sample text.');

Pour rendre le site traduisible, il est préférable que la chaîne traitée par la fonction t soit écrite en anglais.

Il est préférable de ne jamais utiliser une variable en tant que chaîne à traduire.

// MAUVAISE PRATIQUE
$variable = 'This is a sample text.';
print t($variable);

// BONNE PRATIQUE
$variable = t('This is a sample text.');
print $variable;

L'utilisation d'une variable en tant que chaîne à traduire est donc à proscrire, sauf si la variable contient une chaîne qui a été traduite ailleurs par la fonction t.

Ceci étant dit, il existe un moyen d'intégrer des variables dans la chaîne à traduire. Cependant, pour des raisons de sécurité (empêcher le "cross-site scripting" et d'autres problèmes de sécurité), elles ne sont pas intégrés directement dans le premier argument de la fonction t. Elles sont présentes sous la forme d'"espaces réservés" ("placeholders") et sont, ensuite, reprises dans le second argument ($args) de la fonction t en tant que clés d'un tableau associatif. Les valeurs de ce tableau associatif peuvent être des variables ou des valeurs.

Voici comment insérer une variable dans la chaine à traduire :

// format_date() est une fonction du cœur de Drupal
$date = format_date(time(), 'custom', 'j F Y');
print t('Hello @name, this post was written the @date.', 
  array(
    '@name' => 'Jacques Dupont',
    '@date => $date'
  )
);

L'utilisation du caractère arobase ("@") devant le nom des "espaces réservés" n'est pas due au hasard. Sa présence en début d'un "espace réservé" indique que la valeur associée sera échappée au format HTML avant d'être insérée dans le texte traduit. Pour parler en terme Drupal, la valeur de la variable sera traitée par la fonction check_plain().

En réalité, lorsque vous souhaitez utiliser des "espaces réservés", vous pouvez choisir la manière dont il sera mis en forme dans la chaîne de caractère

Vous pouvez choisir la manière dont l'espace réservé sera mis en forme en le faisant commencer par l'un des caractères suivants :

  • @ : Avant de l'insérer dans la chaîne de caractère, échappe au format HTML la valeur associée à l'espace réservé en appelant la fonction check_plain().
  • % : Avant de l'insérer dans la chaîne de caractère, échappe au format HTML et formatte à l'aide de la fonction drupal_placeholder().
  • ! : La valeur associée à l'espace réservé n'est pas échappée au format HTML et donc il est possible d'utiliser des balises HTML autorisées (Il est conseillé d'utiliser la fonction check_plain en amont).