Show Menu
SUJETS×

Internationalisation des chaînes d’interface utilisateur

Les API Java et JavaScript vous permettent d’internationaliser des chaînes dans les types de ressources suivants :
  • Fichiers sources Java.
  • Scripts JSP.
  • JavaScript dans les bibliothèques côté client ou dans la source de la page.
  • Valeurs de propriété de nœud JCR utilisées dans les propriétés de configuration de composants et de boîtes de dialogue.
Pour obtenir un aperçu du processus d’internationalisation et de localisation, reportez-vous à la section Internationalisation de composants .

Internationalisation de chaînes dans le code Java et JSP

The com.day.cq.i18n Java package enables you to display localized strings in your UI. The I18n class provides the get method that retrieves localized strings from the AEM dictionary. Le seul paramètre requis de la méthode get est le littéral de chaîne en langue anglaise. L’anglais est la langue par défaut de l’interface utilisateur. L’exemple suivant localise le mot Search  :
i18n.get("Search");
L’identification de la chaîne en anglais diffère des structures d’internationalisation standard où un ID identifie une chaîne et est utilisé pour référencer la chaîne lors de l’exécution. L’utilisation du littéral de chaîne anglais présente les avantages suivants :
  • Le code est facile à comprendre.
  • La chaîne dans la langue par défaut est toujours disponible.

Définition de la langue de l’utilisateur

Pour déterminer la langue de préférence de l’utilisateur, deux méthodes peuvent être utilisées :
  • Pour les utilisateurs authentifiés, déterminez la langue dans les préférences du compte utilisateur.
  • Paramètre régional de la page demandée.
La propriété language du compte utilisateur est la méthode privilégiée, car elle est plus fiable. Cependant, pour pouvoir l’employer, l’utilisateur doit être connecté.

Création de l’objet Java I18n

La classe I18n fournit deux constructeurs. Le constructeur à utiliser dépend du mode de définition de la langue par défaut de l’utilisateur.
Pour afficher la chaîne dans la langue spécifiée dans le compte utilisateur, utilisez le constructeur suivant (après avoir importé com.day.cq.i18n.I18n)  :
I18n i18n = new I18n(slingRequest);

Le constructeur utilise l’objet SlingHTTPRequest pour récupérer le paramètre de langue de l’utilisateur.
Pour utiliser le paramètre régional de la page afin de déterminer la langue, vous devez d’abord obtenir le ResourceBundle relatif à la langue de la page demandée :
Locale pageLang = currentPage.getLanguage(false);
ResourceBundle resourceBundle = slingRequest.getResourceBundle(pageLang);
I18n i18n = new I18n(resourceBundle); 

Internationalisation d’une chaîne

Use the get method of the I18n object to internationalize a string. Le seul paramètre requis de la méthode get est la chaîne à internationaliser. La chaîne correspond à une chaîne d’un dictionnaire de traduction. La méthode get recherche la chaîne dans le dictionnaire et renvoie la traduction pour la langue en cours.
Le premier argument de la méthode get doit respecter les règles suivantes :
  • La valeur doit être un littéral de chaîne. Une variable de type String n’est pas acceptable.
  • Le littéral de chaîne doit être exprimé sur une seule ligne.
  • La chaîne est sensible à la casse.
i18n.get("Enter a search keyword");

Utilisation d’indices de traduction

Spécifiez l’ indice de traduction de la chaîne internationalisée afin de faire la distinction entre les chaînes en double dans le dictionnaire. Use the second, optional parameter of the get method to provide the translation hint. L’indice de traduction doit correspondre exactement à la propriété Comment de l’élément dans le dictionnaire.
Par exemple, le dictionnaire contient deux occurrences de la chaîne Request  : l’une sous la forme d’un verbe et l’autre sous la forme d’un substantif. Le code suivant inclut l’indice de traduction en tant qu’argument dans la méthode get  :
i18n.get("Request","A noun, as in a request for a web page");

Insertion de variables dans des phrases localisées

Insérez des variables dans la chaîne localisée pour renforcer la signification contextuelle dans une phrase. Par exemple, après vous être connecté à une application web, la page d’accueil affiche le message « Bienvenue à l’administrateur. Vous avez 2 messages dans votre boîte de réception. » Le contexte de page détermine le nom d’utilisateur et le nombre de messages.
Dans le dictionnaire , les variables sont représentées dans des chaînes sous la forme d’index entre crochets. Specify the values of the variables as arguments of the get method. Les arguments sont placés après l’indice de traduction et les index correspondent à l’ordre des arguments :
i18n.get("Welcome back {0}. You have {1} messages.", "user name, number of messages", user.getDisplayName(), numItems); 

La chaîne internationalisée et l’indice de traduction doivent correspondre exactement à la chaîne et au commentaire dans le dictionnaire. Vous pouvez omettre l’indice de traduction en fournissant une valeur null comme deuxième argument.

Utilisation de méthode get statique

La classe I18N définit une méthode get statique qui s’avère utile lorsque vous devez localiser un petit nombre de chaînes. Outre les paramètres de la méthode get d’un objet, la méthode statique nécessite l’objet SlingHttpRequest ou le ResourceBundle que vous utilisez, suivant la manière dont vous déterminez la langue par défaut de l’utilisateur :
  • Utilisation de la préférence de langue de l’utilisateur : indiquez l’objet SlingHttpRequest comme premier paramètre.
    I18n.get(slingHttpRequest, "Welcome back {}. You have {} messages.", "user name, number of messages", user.getDisplayName(), numItems);
  • Utilisation de la langue de la page : indiquez ResourceBundle comme premier paramètre.
    I18n.get(resourceBundle,"Welcome back {}. You have {} messages.", "user name, number of messages", user.getDisplayName(), numItems);

Internationalisation des chaînes dans le code JavaScript

L’API JavaScript vous permet de localiser des chaînes sur le client. As with Java and JSP code, the Javascript API enables you to identify strings to localize, provide localization hints, and include variables in the localized strings.
Le dossier de bibliothèques clientes granite.utils Utilisation de bibliothèques côté client fournit l’API JavaScript. Pour utiliser l’API, vous devez inclure ce dossier sur votre page. Localization functions use the Granite.I18n namespace.
Before you present localized strings, you need to set the locale using the Granite.I18n.setLocale function. Pour cette fonction, le code de langue du paramètre régional doit être défini comme argument :
Granite.I18n.setLocale("fr");

To present a localized string, use the Granite.I18n.get function:
Granite.I18n.get("string to localize");

L’exemple suivant internationalise la chaîne « Welcome back » :
Granite.I18n.setLocale("fr");
Granite.I18n.get("string to localize", [variables], "localization hint");

Les paramètres de la fonction sont différents de la méthode Java I18n.get :
  • Le premier paramètre est le littéral de chaîne à localiser.
  • Le deuxième paramètre est un tableau de valeurs à injecter dans le littéral de chaîne.
  • Le troisième paramètre est l’indice de localisation.
L’exemple suivant utilise JavaScript pour localiser la phrase « Welcome back Administrator. You have 2 messages in your inbox. »  :
Granite.I18n.setLocale("fr");
Granite.I18n.get("Welcome back {0}. You have {1} new messages in your inbox.", [username, numMsg], "user name, number of messages");

Internationalisation de chaînes à partir de nœuds JCR

Les chaînes d’interface utilisateur sont souvent basées sur les propriétés du nœud JCR. Par exemple, la propriété jcr:title d’une page est généralement utilisée comme contenu de l’élément h1 dans le code de la page. The I18n class provides the getVar method for localizing these strings.
L’exemple de script JSP suivant récupère la propriété jcr:title du référentiel et affiche la chaîne localisée sur la page :
<% title = properties.get("jcr:title", String.class);%>
<h1><%=i18n.getVar(title) %></h1>

Définition d’indices de traduction pour les nœuds JCR

À l’instar des indices de traduction dans l’API Java , vous pouvez fournir des indices pour faire la distinction entre des chaînes en double dans le dictionnaire. Fournissez l’indice de traduction en tant que propriété du nœud qui contient la propriété internationalisée. The name of the hint property is comprised of the name of the internationalized property name with the _commentI18n suffix:
${prop}_commentI18n
Par exemple, un nœud cq:page comprend la propriété jcr:title en cours de localisation. L’indice est fourni comme valeur de la propriété nommée jcr:title_commentI18n.

Test de la couverture d’internationalisation

Testez si vous avez internationalisé l’ensemble des chaînes de votre interface utilisateur. Pour afficher les chaînes qui sont couvertes, définissez la langue de l’utilisateur sur zz_ZZ et ouvrez l’IU dans le navigateur web. Les chaînes internationalisées apparaissent avec une traduction souche au format suivant :
USR_*Default-String*_尠
La capture d’écran ci-dessous illustre la traduction souche pour la page d’accueil d’AEM :
Pour définir la langue de l’utilisateur, configurez la propriété language du nœud preferences du compte utilisateur.
Le chemin d’accès du nœud preferences d’un utilisateur se présente comme suit :
/home/users/<letter>/<hash>/preferences