ZnetDK | Gestion multilingue

ZnetDK est configuré par défaut pour un affichage en langue anglaise. Le noyau de ZnetDK est cependant également traduit en langues française et espagnole, par exemple lorsque vous utilisez les fonctionnalités d'habilitation des utilisateurs de l'application.

A la génération d'une nouvelle application depuis l'Assistant d'application, une langue d'affichage autre que les 3 langues supportées en standard par ZnetDK, peut être choisie (par exemple Portuguese).
Si tel est le cas, alors un effort supplémentaire est nécessaire pour traduire dans cette autre langue, tous les libellés du noyau ZnetDK.

Les paragraphes qui suivent présentent en détail le mécanisme de traduction de l'application et les scripts PHP à compléter pour un affichage dans une ou plusieurs langues.

Mécanisme de traduction

Une seule langue d'affichage par défaut

Après génération de votre application via l'Assistant d'application, seule la langue sélectionnée à l'étape 1 de l'assistant est activée pour l'affichage des libellés de l'application.

Le répertoire /applications/default/app/lang contient alors un seul script de traduction nommé locale.php et pré-rempli des libellés saisis à l'étape 1 de l'Assistant d'application. Si une seule langue d'affichage est retenue pour l'application, ce script de traduction peut être complété des nouvelles constantes néccessaires à l'affichage des libellés de l'application, ce qui constitue une bonne pratique que de centraliser dans un même fichier tous les libellés de l'application. De plus, cela simplifie l'évolution de l'application vers un affichage multilingue (cas à ne pas exclure).

Exemple de contenu du script locale.php :

/* General labels */
define('LC_PAGE_TITLE', 'Ma première application');

/* Heading labels */
define('LC_HEAD_TITLE', 'Ma première application');
define('LC_HEAD_SUBTITLE', "Générée par l'assistant d'@pplication ZnetDK");

/* Heading images */
define('LC_HEAD_IMG_LOGO', ZNETDK_APP_URI.'images/logo.png');

/* Footer labels */
define('LC_FOOTER_LEFT', 'Version 1.0');
define('LC_FOOTER_CENTER', 'Développée avec ZnetDK');
define('LC_FOOTER_RIGHT', 'Copyright 2015');

/* Menu item labels */
define('LA_MENU_HOME','Bienvenue');
define('LA_MENU_THEMES','Thèmes');
define('LA_MENU_WIDGETS','Widgets');

D'autre part, la langue d'affichage par défaut est renseignée dans le fichier de configuration config.php pour le paramètre CFG_DEFAULT_LANGUAGE, via le code langue ISO 639-1 idoine.

Exemple de configuration en Français :

define('CFG_DEFAULT_LANGUAGE','fr');

Dans cette configuration d'affichage de l'application dans une seule langue, ZnetDK exécute à la fois le script PHP locale.php du répertoire /applications/default/app/lang et le script locale_[code_langue].php du répertoire /engine/core/lang, où [code_langue] est le code ISO 639-1 défini pour le paramètre CFG_DEFAULT_LANGUAGE.
Si ce dernier n'existe pas (autre langue paramétrée que le Français, Anglais ou Espagnol), alors le script locale_en.php est exécuté par défaut.

Pour traduire les libellés du noyau ZnetDK dans une langue non traduite en standard (par exemple en Portugais), ajoutez au script locale.php de votre application, les constantes définies dans le script locale_en.php puis, traduisez leur libellé dans la langue cible de l'application.

Affichage multilingue

En affichage multilingue (configuration décrite au paragraphe suivant), la langue présentée à l'utilisateur qui se connecte pour la première fois à votre application dépend de la langue préférée de son navigateur.

Si la langue préférée du navigateur est l'une des langues supportées par votre application, alors cette langue est retenue pour l'affichage.
Autrement, c'est la langue par défaut définie pour le paramètre CFG_DEFAULT_LANGUAGE qui est choisie pour l'affichage.

La langue affichée la première fois pour un utilisateur est mémorisée en session pour les affichages suivants.
Seul le choix d'une nouvelle langue par l'utilisateur permettra alors de changer la langue mémorisée en session la première fois.

Configuration d'un affichage multilingue

Pour offrir un affichage de votre application en 2 langues ou plus, vous devez activer la gestion multilingue en suivant la procédure suivante :

Mettez à jour les paramètres suivants du fichier /applications/default/app/config.php :
- CFG_MULTI_LANG_ENABLED : il doit être renseigné à la valeur TRUE.
- CFG_DEFAULT_LANGUAGE : il doit contenir le code ISO 639-1 de la langue affichée par défaut lors du premier accès à l'application.
  En effet, si la langue préférée du navigateur internet n'est pas reconnue par l'application, alors la langue par défaut définie dans ce paramètre est celle retenue par défaut.
  Par exemple fr pour un affichage par défaut en langue française si la langue préférée du navigateur ne fait pas partie des langues que l'application sait afficher.
- CFG_COUNTRY_LABELS : il permet de personnaliser les libellés de langues affichés en entête de l'application.
  Les libellés de langues ne figurant pas dans la liste peuvent être ajoutés et les libellés proposés par défaut personnalisés.
  Chaque libellé renseigné doit être préfixé du code ISO 639-1 qui lui correspond sous la forme d'un tableau PHP dont la clé représente le code langue.
```
			define('CFG_COUNTRY_LABELS', serialize(array(
				'fr'=>'Français',
				'en'=>'English',
				'es'=>'Español'
			)));
```
- CFG_COUNTRY_ICONS : ce paramètre contient pour chaque langue supportée par l'application, les images de drapeaux de pays affichées en complément du libellé de la langue. En standard, ZnetDK est livré avec 3 images correspondant aux langues française, anglaise et espagnole. Pour toute langue supplémentaire, vous pouvez ajouter une image du drapeau de la nouvelle langue dans le répertoire /applications/default/public/images et ajouter au paramètre son chemin d'accès et son nom.
```
			define('CFG_COUNTRY_ICONS', serialize(array(
			'fr'=>CFG_ZNETDK_IMG_DIR.'/lang_flag_fr.png',
			'en'=>CFG_ZNETDK_IMG_DIR.'/lang_flag_en.png',
			'es'=>CFG_ZNETDK_IMG_DIR.'/lang_flag_es.png'
			)));
```
Ajoutez les fichiers de traduction dans le répertoire /applications/default/app/lang :
- locale_[code_langue].php : il doit exister autant de fichiers de traductions que de langues reconnues par l'application.
  Le code [code_langue] représente le code ISO 639-1 de la langue traduite.
  Par exemple, si l'application est traduite en Français et en Anglais, les fichiers locale_fr.php et locale_en.php doivent être tous deux présents dans le répertoire des traductions.
Ajoutez le contenu traduit dans les différentes vues de l'application de la manière suivante :
- En utilisant une même vue pour toutes les langues reconnues par l'application.
  Les constantes définies dans le script locale_[code_langue].php pour chaque langue de votre application sont alors référencées dans la vue pour afficher le texte adapté à chaque langue.
  Par exemple : <p><?php echo LC_WELCOME_TEXT;?></p> pour afficher le texte défini pour la constante LC_WELCOME_TEXT renseignée dans chaque fichier locale_[code_langue].php.
- En créant autant de vues différentes que de langues reconnues par votre application.
  Par exemple, les vues mavue_fr.php et mavue_en.php dans le répertoire /applications/default/app/view pour afficher un même contenu dans les langues française et anglaise.

Dans le cas où un modèle de page personnalisé a été ajouté dans le répertoire /applications/default/app/layout, assurez-vous que la sélection des langues supportées par votre application est rendue possible par l'ajout dans la page d'un appel à la méthode \self::renderLangSelection().

Formatage des montants et des dates

Formatage global

Les montants et les dates extraits de la base de données et restitués à l'affichage à travers les vues sont formatés selon les paramètres du pays et de la langue renseignés dans le script locale_<code_pays>.php pour la constante PHP LC_LOCALE_ALL passée en paramètre d'appel de la fonction PHP setlocale.

En standard, la constante LC_LOCALE_ALL est définie aux valeurs indiquées ci-dessous, pour chacun des scripts de traduction situés dans le répertoire /engine/core/lang :

script locale_en.php :

define ('LC_LOCALE_ALL', serialize(array('en_US.UTF-8',
 'English_United States.1252', 'en_US', 'english')));

script locale_es.php :

define ('LC_LOCALE_ALL', serialize(array('es_ES.UTF-8',
 'Spanish_Spain.1252', 'es_ES', 'spanish')));

script locale_fr.php :

define ('LC_LOCALE_ALL', serialize(array('fr_FR.UTF-8',
 'French_France.1252', 'fr_FR', 'french')));

Les valeurs de la constante LC_LOCALE_ALL peuvent être surchargées dans les scripts de traduction de l'application situés dans le répertoire /applications/default/app/lang.

Formatage personnalisé

Le format d'affichage des montants et des dates peut être finement personnalisé à l'aide des constantes PHP ci-dessous ajoutées aux scripts de traduction de l'application dans le répertoire /applications/default/app/lang :

LC_LOCALE_DECIMAL_SEPARATOR : caractère séparateur des décimales (la virgule en Français, le point en Anglais).
LC_LOCALE_THOUSANDS_SEPARATOR : caractère séparateur des milliers (un espace en Français, un point en Anglais).
LC_LOCALE_NUMBER_OF_DECIMALS : nombre de décimales (généralement 2 décimales pour une monnaie).
LC_LOCALE_CURRENCY_SYMBOL : symbole monétaire (€ en Français, £ en Anglais, ...).
LC_LOCALE_CURRENCY_SYMBOL_PRECEDE : à la valeur TRUE, le symbole monétaire précède le montant.
LC_LOCALE_CURRENCY_SYMBOL_SEPARATE : caractère séparateur du symbole monétaire avec le montant.
LC_LOCALE_DATE_FORMAT : en version de ZnetDK <= 2.7, format de la date selon la syntaxe de la function PHP strftime.
En version de ZnetDK >= 2.8, format de date selon la syntaxe de méthode DateTime::format().

Exemple de personnalisation du format des montants et dates :

define('LC_LOCALE_DECIMAL_SEPARATOR', ',');
define('LC_LOCALE_THOUSANDS_SEPARATOR', ' ');
define('LC_LOCALE_NUMBER_OF_DECIMALS', 2);
define('LC_LOCALE_CURRENCY_SYMBOL', '€');
define('LC_LOCALE_CURRENCY_SYMBOL_PRECEDE', FALSE);
define('LC_LOCALE_CURRENCY_SYMBOL_SEPARATE', ' ');
define('LC_LOCALE_DATE_FORMAT', 'd-m-y');

Séparateur de données des fichiers CSV

Le caractère de séparation des données d'un fichier CSV retourné par le contrôleur applicatif via un appel à la méthode Response::setDataForCsv(), peut être personnalisé dans le script de traduction de l'application /applications/default/app/lang, en renseignant la constante LC_LOCALE_CSV_SEPARATOR.

En standard, le caractère séparateur d'un fichier CSV est définie aux valeurs indiquées ci-dessous, pour chacun des scripts de traduction situés dans le répertoire /engine/core/lang :