Joomla! Documentation™

Introduction à la traduction de template

Joomla! a vocation à être utilisé à l'international et doit donc permettre la traduction de toutes les chaînes de caractères qu'il contient. Les templates ne font pas exception et le peu de temps passé pour vous assurer que les chaînes de caractères utilisées dans vos templates sont traduisibles est un véritable plus.

Le système de traduction été conçu pour être aussi simple que possible tout en limitant la possibilité d'erreurs. Par exemple, même si un fichier de langue est manquant, ou qu'une chaîne de caractères n'a pas été traduite, Joomla affichera la chaîne non traduite. De plus, il existe quelques outils très utiles et intégrés dans Joomla! pour aider les traducteurs pour la création de nouvelles traductions.

Dans ce document, vous apprendrez comment créer des fichiers de définition de langue pour votre template et comment intégrer les traductions dans votre paquet template. Vous apprendrez également comment vous assurer que toutes les chaînes de caractères utilisées dans le template sont traduisibles et comment déboguer une nouvelle traduction.

Emplacement des fichiers de définition de langue

Les fichiers de définition de langue pour les templates de front-end sont situés dans

[path-to-Joomla]/language/[ln-LN]

où [ln-LN] est le code de langue. Les codes de langue sont définis dans RFC3066 Le fichier doit être nommé

[ln-LN].tpl_[template-name].ini

où [template-name] est le nom du template (en minuscules). Par exeple, le fichier langue pour l'anglais britannique du template Beez est

[path-to-Joomla]/language/en-GB/en-GB.tpl_beez.ini

Vous devez également créer un fichier langue séparé pour traduire le back-end de votre template. Celui-ci sera stocké dans

[path-to-Joomla]/administrator/language/[ln-LN]

mais la convention de nommage de fichier est la même.

Pour les templates d'administration, étant distincts des templates de front-end, seul le deuxième fichier est requis. Par exemple, le fichier langue pour l'anglais britannique du template d'administration Khepri est situé dans

[path-to-Joomla]/administrator/language/en-GB/en-GB.tpl_khepri.ini

Création d'un fichier de définition de langue

Joomla! 

3.x

série

This Article Needs Your Help

Les fichiers de définition des langues pour Joomla sont écrits de gaçon très basique au Format de fichier INI. Ils doivent être enregistrés en respectant l'encodage UTF-8. Les lignes vierges et autres lignes qui commencent par ; sont ignorées et sont utilisées pour ajouter des commentaires au fichier. Chaque ligne consiste en une paire de valeurs clés séparée par un signe égal comme ceci :

CLÉ="Valeur"

où CLÉ est la chaîne devant être traduite Valeur est la chaîne traduite. Par exemple :

INFORMATIONS_COMPLEMENTAIRES="Informations complémentaires"

Les différentes versions de Joomla! ont utilisé différentes façons de lire les fichiers de langue (à savoir, un analyseur personnalisé et un analyseur natif PHP INI, dont le dernier a présenté des anomalies pour les versions PHP 5.2 et supérieures), conduisant à des règles différentes sur ce qui devait ou non être autorisé dans les clés et/ou dans les valeurs. Les fichiers de langue qui respectent les règles suivantes devraient fonctionner sous la plupart de versions Joomla et en tous cas pour Joomla! et supérieures.

La CLÉ ne devrait utiliser que des caractères ASCII. Elle ne doit contenir que des lettres majuscules, des chiffres, des traits de soulignement (underscore _) et des traits d'union (-). Les points (.) sont autorisés mais ne semblent pas être totalement pris en charge. Il est de convention de remplacer les espaces dans la chaîne à traduire, par des underscores. Si plus d'une entrée a la même clé, la dernière rencontrée sera utilisée. Lorsque vous utilisez la clé dans un appel JText::_, les majuscules n'ont pas d'importance puisque les chaînes seront analysées en majuscules. Donc informations_complementaires, Informations_Complementaires ou même iNforMaTioNs_cOmPlemEntAires seront traîtées.

La valeur doit toujours être entourée par des guillemets doubles ("), comme dans l'exemple. La valeur elle-même ne peut pas inclure les guillemets doubles ("), même si les guillemets simples (') sont valides. Il convient d'utiliser "_QQ_" (y compris les guillemets doubles) afin d'utiliser un guillemet dans votre valeur. Par exemple, pour utiliser la valeur <span class="red">Avertissement !</span> avec la clé WARNING_TEXT, il conviendra d'utiliser la ligne suivante :

WARNING_TEXT="<span class=\"red\">Warning!</span>"

Notez que ces règles sont plus strictes que celles requises par le parser PHP INI. Par exemple, l'analyseur PHP INI vous permet d'omettre les guillemets autour de la valeur tant qu'ils ne contiennent pas certains caractères. Cependant, l'utilisation des règles ci-dessus devrait permettre d'éviter les erreurs, comme l'oubli des guillemets lorsqu'ils "sont" nécessaires.

Pour obtenir plus d'informations sur les changements opérés entre les séries 1.5, 2.5 et 3.x, veuillez consulter la page sur les spécifications pour les fichiers langue

Modifier le fichier templateDetails.xml

Afin de vous assurer que votre template est entièrement internationalisé, vous devez vous assurer que certains éléments XML sont traduits et que les fichiers de définition de langue sont répertoriés dans le fichier templateDetails.xml.

Traduction du templateDetails.xml

Deux éléments du fichier templateDetails.xml sont utilisés dans le Gestionnaire de template et sont eux-mêmes traduisible. La description doit toujours être traduite.

name	Nom du template. Par exemple, Beez
description	Description du template

Ces champs sont également présentés à l'utilisateur pendant l'installation du template.

Ajout des fichiers de définition de langue au templateDetails.xml

Tous les fichiers de langue doivent être déclarés dans le fichier templateDetails.xml. Cela se fait en ajoutant deux éléments <language> pour chaque langue à inclure au template ; une pour les chaînes du fontend ; l'autre pour les chaînes du backend. Par exemple, les deux fichiers de langue anglais britannique et les deux fichiers de langue allemande pour le template Beez sont déclarés ainsi :

<?xml version=”1.0” encoding=”utf-8” ?>
<install version=”1.5” type=”template”>

     .........

    <languages>
        <language tag=”en-GB”>en-GB.tpl_beez.ini</language>
        <language tag=”de-DE”>de-DE.tpl_beez.ini</language>
    </languages>

     .........

    <administration>
        <languages folder=”admin”>
            <language tag=”en-GB”>en-GB.tpl_beez.ini</language>
            <language tag=”de-DE”>de-DE.tpl_beez.ini</language>
        </languages>
    </administration>

</install>

Notez que pour la balise <languages> d'administration, l'attribut folder (dossier) est utilisé. Cela du fait que les fichiers de langue pour le frontend et le backend ont les mêmes noms et ne peuvent donc exister dans un même répertoire du paquet de template. Dans cet exemple, les fichiers de langue de l'administration ont été placés dans un sous-répertoire nommé admin afin de les séparer des fichiers de langue du frontend.

Intégrer des chaînes de caractères traduisibles dans un template

Dans le template lui-même, les traductions sont traitées en utilisant la classe statique JText. On parle ici de “statique” car il ne nécessite pas d'instanciation comme objet avant que ses méthodes ne soient utilisées.

Chaînes de texte simple

La plupart des chaînes de texte peuvent être traduites en utilisant la méthode “_” (trait de soulignement). Par exemple, supposons que votre template contienne le texte anglais “Welcome” qui a besoin d'être traduisible.

<?php
    echo 'Welcome';
?>

Vous remplacez alors la chaîne statique comme ceci :

<?php
    echo JText::_( 'Welcome' );
?>

Cela va amener le système de traduction à rechercher le fichier langue approprié pour le “WELCOME” situé à gauche du signe égal. La recherche n'est pas sensible à la casse. Si cette chaîne de définition de langue est trouvée :

WELCOME=Welcome!

cela affichera ainsi la chaîne “Welcome!” dans le navigateur. Si l'utilisateur passe à la langue allemande, le fichier de définition de langue allemande cherchera “WELCOME” et devrait trouver la chaîne :

WELCOME=Willkommen

ainsi, “Willkommen” sera envoyé au navigateur. Et de plus, si l'utilisateur passe à l'Allemand alors qu'il n'existe pas de fichier langue allemand ou que la chaîne appropriée n'apparaît pas dans le fichier langue allemand, Joomla! retournera la chaîne non traduite “Welcome” au navigateur, tout en conservant sa casse d'origine.

Champs formatés dans les chaînes de traduction

Parfois, il est nécessaire d'inclure des champs spécialement formatés dans une chaîne à traduire. Cela se produit généralement lorsque des nombres sont concernés, mais cela peut se produire pour des dates et heures ou lorsque des instructions de formatage précis sont requis. Si les chaînes n'ont pas à être traduites, les fonctions PHP standard printf et sprintf peuvent être utilisées. La fonction printf renvoie une chaîne formatée en utilisant des instructions de formatage intégrées ; la fonction sprintf renvoie une chaîne formatée en utilisant les mêmes instructions de formatage intégrées.

La classe JText fournit des méthodes de permutation (wrapper) pour les fonctions printf et sprintf permettant à du texte statique d'être traduit tout en permettant aux champs formatés d'être intégrés en utilisant la même syntaxe que les fonctions PHP.

Par exemple, supposons que vous avez une chaîne du type : "Donations of 12.45 GBP have been received" dont le montant est donné par la variable $donations. Vous pourriez alors diviser la chaîne en deux parties comme ceci :

JText::_( 'Donations of' ) . “ $donations GBP “ . JText::_( 'have been received' )

avec les chaînes de définition de langue :

DONATIONS OF=Donations of
HAVE BEEN RECEIVED=have been received

mais cela ne fonctionne pas correctement pour les langues lorsque les données intégrées ne sont pas au même endroit que dans la chaîne traduite. Plutôt que d'utiliser la méthode sprintf comme ceci

JText::sprintf( 'Donations have been received', $donations )

avec la chaîne de définition de langue :

DONATIONS HAVE BEEN RECEIVED=Donations of %.2f GBP have been received

Vous pouvez inclure plus d'un spécificateur de format dans une chaîne de traduction. Les substitutions sont effectuées dans l'ordre, et cela fonctionne ainsi comme attendu

JText::sprintf( 'String with numbers in it', $num1, $num2, $num3 )

avec la chaîne de définition de langue :

STRING WITH NUMBERS IN IT=First %d, second %d, third %d

Syntaxe de spécificateurs de format

Le spécificateur de format consiste en un signe de pourcentage (%), suivi par un ou plusieurs des éléments suivants, dans l'ordre :

Ordre	Type	Valeurs	Description
1.	Signe	+ ou -	Facultatif. Force l'utilisation d'un signe (+ ou -) pour les nombres. Par défaut, seul le signe - est utilisé sur un nombre s'il est négatif. Ce spécificateur force également les nombres positifs à s'adjoindre le signe +.
2.	Padding	<space> ou 0 ou '<char>	Facultatif. Caractère devant être utilisé pour la bonne dimension du padding pour les résultats. Peut-être un espace ou un 0 (zéro). Par défaut, il convient d'utiliser les espaces. Un padding alternatif peut être spécifié en préfixant avec un guillemet simple (').
3.	Alignement	<null> ou -	Facultatif. Détermine si le résultat doit être justifié à gauche ou à droite. La valeur par défaut est justifié à droite ; un caractère - ici va le justifier à gauche.
4.	Longueur	Nombre	Facultatif. Le nombre (minimum) de caractères qui devrait résulter de la conversion.
5.	Précision	Nombre	Facultatif. Le nombre de décimale devant être affiché pour les nombres à virgule. Lors de l'utilisation de ce spécificateur dans une chaîne, il servira comme point limite, fixant le nombre de caractère maximum de la chaîne.
6.	Type	Obligatoire. Le type de données d'argument. Les types possibles sont :
		%	Un caractère pourcentage. Aucun argument n'est requis.
		b	L'argument est traité comme un nombre entier et présenté comme un nombre binaire.
		c	L'argument est traité comme un nombre entier et présenté comme un caractère avec cette valeur ASCII.
		d	L'argument est traité comme un nombre entier et présenté comme un nombre décimal.
		e	L'argument est traité comme une notation scientifique (ex : 1.2e+2). Depuis PHP 5.2.1, le spécificateur de précision représente le nombre de chiffres après le point décimal. Dans les versions antérieures, il servait à définir le nombre de chiffres significatifs (un de moins).
		u	L'argument est traité comme un nombre entier et présenté comme un nombre décimal.
		f	L'argument est traité comme flottant et présenté comme un nombre à virgule flottante (paramètres locaux courant).
		F	L'argument est traité comme flottant et présenté comme un nombre à virgule flottante (sans prise en compte des paramètres locaux).
		o	L'argument est traité comme un nombre entier et présenté comme un nombre octal.
		s	L'argument est traité et présenté sous forme de chaîne de caractères.
		x	L'argument est traité comme un nombre entier et présenté comme un nombre hexadécimal (avec des lettres minuscules).
		X	L'argument est traité comme un nombre entier et présenté comme un nombre hexadécimal (avec des lettres majuscules).

Format d'argument de permutation

La chaîne de format prend en charge l'argument de numérotation et même de permutation. C'est utile lorsque deux ou plusieurs éléments de données doivent être intégrés dans une chaîne mais que les différences dans la structure de la langue implique que l'ordre d'utilisation des éléments de données ne sont pas les mêmes.

Par exemple, supposons que nous ayons ce code :

echo JText::sprintf( 'Balls in the bucket', $number, $location );

avec cette chaine de traduction :

BALLS IN THE BUCKET=There are %d balls in the %s

Puis, si

$number = 3
$location = 'hat'

Cela affichera “There are 3 balls in the hat”. Mais présumons que vous souhaitez changer cette traduction en :

BALLS IN THE BUCKET=The %s contains %d balls

Cela affichera désormais “The 3 contains hat balls”, ce qui n'a aucun sens. Plutôt que de changer le code, vous pouvez indiquer dans la chaine de traduction à quel argument chacun des libellés se réfère. Modifiez la traduction en :

BALLS IN THE BUCKET=The %2$s contains %1$d balls

et le rendu devient comme attendu “The hat contains 3 balls”.

Un avantage supplémentaire de pouvoir numéroter les arguments est que vous pouvez répéter les libellés sans avoir à ajouter plus d'arguments au code. Par exemple, changez la traduction en :

BALLS IN THE BUCKET=The %2$s contains %1$d balls, so there are %1$d balls in the %2$s

et cela affichera correctement “The hat contains 3 balls, so there are 3 balls in the hat”.

Débogage d'une traduction

Joomla! prend en charge certains mécanismes de débogage très utiles et qui permettent notamment de localiser les chaînes non traduites et de diagnostiquer des problèmes avec les traductions de langues dans les extensions installées.

Débogage de langue

Vous activez le système de débogage de langue via le backend en allant dans Configuration et en cliquant sur l'onglet Système. Trouvez le Débogage de la langue et modifiez la valeur par "Oui", puis enregistrez vos modifications.

Avec cette option activée, toutes les chaînes traduisibles sont représentées entourées de caractères spéciaux qui indiquent leur statut.

Code	Statut
**Joomla CMS**	(texte entouré d'astérisques) indique qu'une correspondance a été trouvée dans le fichier de définition de la langue et que la chaîne a été traduite.
??Joomla CMS??	(texte entouré par des paires de points d'interrogation) indique que la chaîne est traduisible mais qu'aucune correspondance n'a été trouvée dans le fichier de définition de langue.
Joomla CMS	(texte sans caractères autour) indique que la chaîne n'est pas traduisible.

Débogage système

Les Informations de débogage des langues supplémentaires peuvent être obtenues en activant le débogage du système. Allez dans Configuration et cliquez sur l'onglet Système. Trouvez le champ Débogage système et modifiez la valeur par "Oui", puis enregistrez vos modifications.

Avec cette option activée, des informations de débogage supplémentaires s'affichent en bas de chaque page. Ce qui inclut actuellement :

• Profil d'information. C'est le temps nécessaire pour exécuter du code dans divers points de repère du code.
• Occupation de la mémoire. La quantité de RAM utilisée.
• Requêtes de bases de données. Toutes les requêtes SQL exécutées lors du processus de construction de la page.
• Fichiers de langue chargés. Une liste de tous les fichiers de langue chargés lors du processus de création de la page, y compris informations du chemin d'accès. Ceci peut être utile pour vérifier que les fichiers attendus ont bien été chargés. Le nombre situé après chaque chemin d'accès de fichier correspond au nombre de fois où le fichier a été référencé.
• Diagnostic des Chaînes non traduites. Une liste de toutes les chaînes non traduites trouvées et l'emplacement probable du fichier dans lequel l'appel JText a été effectué.
• Style des chaînes non traduites. Une liste de toutes les chaînes non traduites trouvées mais listées au format CLE=Valeur pouvant ainsi être copiées-collées directement dans un fichier de définition de langue (INI).

Plugin de débogage

Ce plugin système contrôle ce qui est affiché lorsque le dégogage est activé dans Configuration. Il est activé par défaut. Pour accéder aux paramètres de ce plugin, allez dans Extensions → Gestion des plug-ins. Localisez le plugin “Système - Débogage” et ouvrez-le et cliquez sur l'onglet Paramètres de langue. Vous y trouverez trois paramètres intéressants pour les traducteurs.

• Affiche les chaînes de langue chargés. Si paramétré sur “Oui”, alors les informations de dégogage incluront une liste des fichiers de langue demandés par la page en cours de chargement.
• Affiche les chaînes de langues indéfinies. Si paramétré sur “Mode diagnostic”, alors une liste des chaînes non traduites et l'emplacement du fichier contenant l'appel à JText sont inclus aux informations de débogage. Si paramétré sur “Mode concepteur”, alors une liste des chaînes non traduites sera inclus aux informations de débogage dans un format pouvant être copié/collé directement dans un fichier de définition de langue. C'est à dire que la liste sera affichée au format CLE=Chaîne. Si paramétré sur “Tous les modes”, alors les listes des deux modes diagnostic et concepteur seront incluses aux informations de débogage.
• Exclure le préfixe de clé. Utilisé uniquement lorsque Affiche les chaînes de langues indéfinies est paramétré sur “Mode concepteur” ou "Tous les modes". Cela vous permet d'exclure un préfixe de la chaîne pour former la clé. C'est utile si le concepteur utilise un préfixe commun pour ses extensions lors de l'utilisation de méthodes JText. Voir l'exemple ci-dessous.

Notez que l'affichage des chaînes non traduites n'afficheront que les valeurs transmises par la méthode appropriée JText. Par exemple, dans le code suivant :

echo JText::_( 'Reports Import Configuration' );

Si non traduite, le Mode concepteur affichera cela comme suit :

# /administrator/components/com_reports/views/reports/tmpl/default.php
REPORTS IMPORT CONFIGURATION=Reports Import Configuration

Si Exclure le préfixe de clé est paramétré sur "Rapports", alors l'affichage sera légèrement modifié en :

# /administrator/components/com_reports/views/reports/tmpl/default.php
REPORTS IMPORT CONFIGURATION=Import Configuration

Notez que le chemin indiqué est seulement la meilleure estimation basée sur un appel à la fonction PHP debug_backtrace. Parfois, le résultat est précis, parfois il ne l'est pas et parfois aucun fichier ne peut être déterminé. Dans ces cas, il vous faudra juger par vous-même.

---