Passer au contenu principal

Internationalisation

Présentation​

Si toutes les applications doivent être internationalisées, un grand nombre d'entre elles seront également localisées (ce qui, pour nos besoins, correspond essentiellement à une traduction). Si vous ne l’internationalisez pas correctement, la localisation complète devient difficile, voire impossible.

Jutro met à votre disposition un service d'assistance à l'internationalisation et à la localisation, mais vous devez gérer également l'implémentation.

Nous traitons la langue, les paramètres régionaux, le pays et la devise comme des variables entièrement indépendantes :

  • Langue : elle couvre les chaînes de caractères ordinaires de l'interface utilisateur.
    • Les applications peuvent configurer une série de availableLanguages et un preferredLanguage (par défaut)
  • Paramètre régional : également connu sous le nom de format régional, il régit la façon dont les dates, les heures, les nombres et les calendriers sont formatés Notez que toutes les chaînes classiques de l'interface utilisateur (régie par la langue) qui comprennent une variable de date, d'heure ou de nombre doivent être formatées en fonction des paramètres régionaux.
    • Les applications peuvent configurer une série de availableLocales et un preferredLocale (par défaut)
  • Pays : régit le comportement des composants de numéro de téléphone ou d'adresse
    • Les applications peuvent définir un defaultCountryCode, qui, à moins qu'il ne soit écrasé au niveau du composant, sera utilisé par des composants tels que IntlPhoneNumberField et Address pour définir le pays par défaut
  • Devise : la devise ne doit pas être déduite de la langue, du pays ou des paramètres régionaux d'un utilisateur
    • La devise est simplement une propriété d'une transaction
    • Les applications peuvent configurer une defaultCurrency, qui, à moins d'être écrasée au niveau du composant, sera utilisée pour configurer des composants tels que CurrencyInput

Avant de commencer​

L'application exemple Jutro vous propose les éléments suivants :

  • Toutes les chaînes de l'interface utilisateur sont marquées de manière à pouvoir être extraites dans le fichier lang.json, puis traduites
  • Le processus de développement crée automatiquement notre pseudo-langage, connu sous le nom de Sherlock
  • Tous les composants sensibles au paramètre régional comme le sélecteur de date et la saisie de la devise se comportent automatiquement de manière correcte

Prise en charge de l'internationalisation (i18n) dans Jutro​

  • react-intl : une bibliothèque qui fournit des composants React tels que FormattedDate et FormattedNumber, ainsi que des API pour formater les dates, les nombres et les chaînes et gérer les traductions. Certains de nos composants, comme CurrencyInput, englobent les composants fournis par react-intl.
  • jutro : cet utilitaire de ligne de commande fournit une sous-commande qui simplifie la gestion du texte traduisible. Pour en savoir plus, reportez-vous aux sections correspondantes sur les commandes CLI de la plate-forme Jutro.
  • jutro-locale : package Jutro qui contient, entre autres, les éléments suivants :
    • GlobalizationProvider : définit le contexte d'internationalisation d'une application au moyen du composant IntlProvider de react-intl
    • La globalisation stocke les données en fonction de zustand, que vous pouvez utiliser pour interagir avec les préférences des paramètres régionaux de l'utilisateur et les modifications apportées à la langue, aux paramètres régionaux, à la devise et au pays
  • jutro-components : contient une variété de composants qui tiennent compte des paramètres régionaux, tels que la combinaison suivante de champs de saisie et d'affichage de valeurs :
    • CurrencyInput, CurrencyValue
    • SimpleDate, DateRange, DateTime, DateTimeZone
    • InputNumber, NumberValue
    • IntlPhoneNumberField, PhoneNumberValue
    • GlobalizationChooser : widget vous permettant de sélectionner locale et language indépendamment l'un de l'autre
    • LanguageSelector : similaire à GlobalizationChooser, mais présente uniquement un sélecteur de langue

Votre structure de dossiers​

  • i18n/src/* : fichiers temporaires générés automatiquement qui contiennent uniquement les chaînes de l'interface utilisateur ayant été extraites de src/**. Ne les modifiez pas manuellement et ne les enregistrez pas dans le système de contrôle source. .gitignore est déjà configuré de façon à ignorer ces fichiers.
  • src/i18n/lang.json : le fichier de traduction généré (vous pouvez en changer dans package.json en modifiant les options de commande jutro). De même, ne modifiez pas manuellement ce fichier, car il est ajouté à .gitignore. Les traducteurs utiliseront ce fichier comme base de départ pour leurs traductions ultérieures. Ils ajouteront d'autres fichiers de langue dans le même dossier, par exemple ru.json, fr.json

Forme de chaîne​

Jutro fournit un type intlMessageShape, qui possède les propriétés suivantes :

  • id : doit être unique dans l'application
  • defaultMessage : texte réel de l'interface utilisateur. Il s'agit également de la chaîne de secours en l'absence de traduction
  • description (facultatif) : aide le traducteur à comprendre le contexte dans lequel la chaîne apparaît.
  • args (facultatif) : permet la transmission de valeurs d'argument. Voir Interpolation de variable

Les chaînes doivent respecter cette forme, sinon il n'est pas possible de les extraire en vue de leur traduction.

Voir également : intlMessageShape

Internationalisation de votre application​

react-intl fournit la plupart des composants d'internationalisation dont vous avez besoin pour les applications Jutro.

Note : Si vous utilisez l'application exemple livrée avec Jutro, vous bénéficierez gratuitement de la plupart des éléments ci-dessous, si ce n'est tous.

Ajouter le composant du fournisseur d’internationalisation​

Si vous n'utilisez pas la fonction Jutro start, vous pouvez ajouter des fonctionnalités de globalisation Jutro à votre application à l'aide de GlobalizationProvider.

À la racine de votre application, vous devez ajouter le composant GlobalizationProvider de Jutro à partir de jutro-locale. Celui-ci fournit un contexte d'internationalisation pour tout ce qu'il englobe. Il utilise le composant IntlProvider de la bibliothèque react-intl.

IntlProvider définit deux propriétés clés :

  • locale : élément qui affecte le comportement de tous les composants sensibles aux paramètres régionaux, tels que ceux utilisés pour la saisie et l'affichage de la date, du calendrier, de l'heure et du nombre
  • messages : la série de traductions à utiliser par les composants inclus

Notez que locale et messages sont indépendants l'un de l'autre. Cela signifie que vous pouvez définir locale sur fr-FR, mais que la série messages peut contenir des traductions en allemand, par exemple.

Configurer les paramètres régionaux​

Vous pouvez définir localeSettings dans src/config/config.json. Par exemple :

src/config/config.json
{
  "localeSettings": {
    "availableLocales": ["en-US", "es-ES", "es-MX", "de-DE", "pl"],
    "availableLanguages": ["en", "es", "de", "pl", "yy"],
    "preferredLocale": "en-US",
    "preferredLanguage": "en",
    "defaultCountryCode": "US",
    "defaultCurrency": "USD"
  }
}

Si localeSettings ou une partie de celui-ci ne figure pas dans votre configuration, l'application restaurera les valeurs par défaut suivantes :

src/config/config.json
{
  "localeSettings": {
    "availableLocales": ["en-US"],
    "availableLanguages": ["en"],
    "preferredLocale": "en-US",
    "preferredLanguage": "en",
    "defaultCountryCode": "US",
    "defaultCurrency": "USD"
  }
}

Fournir aux utilisateurs un moyen de sélectionner la langue et les paramètres régionaux​

Vous disposez de quelques options pour permettre aux utilisateurs de sélectionner la langue et les paramètres régionaux, ainsi que pour stocker ces sélections.

Composant de sélecteur d'internationalisation​

GlobalizationChooser permet à l'utilisateur de sélectionner la langue et les paramètres régionaux séparément. Ce composant accepte les propriétés suivantes :

  • className : noms de classe supplémentaires pour le composant (PropTypes.string)
  • containerStyle : noms de classe supplémentaires pour le conteneur du composant (PropTypes.string)
  • localeId : ID de l'élément « select » des paramètres régionaux (PropTypes.string)
  • languageId : ID de l'élément « select » de la langue (PropTypes.string)
  • localeValue : paramètres régionaux sélectionnés (PropTypes.string)
  • languageValue : langue sélectionnée (PropTypes.string)
  • languageLabelText : clé de message pour l'étiquette de langue (intlMessageShape)
  • localeLabelText : clé de message pour l'étiquette des paramètres régionaux (intlMessageShape)
  • availableLanguageValues : langues disponibles pour la sélection (PropTypes.arrayOf(PropTypes.string))
  • availableLocaleValues : paramètres régionaux disponibles pour la sélection (PropTypes.arrayOf(PropTypes.string))
  • onLocaleValueChange : rappel appelé lors d'une modification des paramètres régionaux (PropTypes.func)
  • onLanguageValueChange : rappel appelé lors d'une modification de la langue (PropTypes.func)
  • renderLocaleLabel : propriété d'affichage pour afficher les paramètres régionaux dans les options (PropTypes.func)
  • renderLanguageLabel : propriété d'affichage pour afficher la langue dans les options (PropTypes.func)
  • showLocaleLabel : indicateur permettant d'afficher ou de masquer l'étiquette des paramètres régionaux (PropTypes.bool)
  • showLanguageLabel : indicateur permettant d'afficher ou de masquer l'étiquette de la langue (PropTypes.bool)
  • showLocaleSelect : indicateur permettant d'afficher/de masquer la sélection des paramètres régionaux (PropTypes.bool)
  • showLanguageSelect : indicateur permettant d'afficher/de masquer la sélection de la langue (PropTypes.bool)
  • readOnly : si la valeur est « true », les listes déroulantes sont en lecture seule et ignorées dans Storybook (PropTypes.bool)
  • skipPropagation : si la valeur est « true », la configuration n'est pas mise à jour lors de la modification de valeur et GlobalizationChooser devient un composant contrôlé (PropTypes.bool)

Composant de sélecteur de langue​

Ce composant présente uniquement un menu de sélection de la langue. La valeur de langue sélectionnée sera également utilisée pour définir la valeur des paramètres régionaux. La sélection n'est pas conservée dans localStorage.

Note:

La dépendance @jutro/router et ses dépendances homologues telles que history et les packages react-router-dom sont désormais facultatives pour les packages de composants. Pour le composant LanguageSelector , il est toutefois nécessaire d'ajouter la dépendance à vos dépendances d'application afin de pouvoir l'utiliser.

Comment Jutro détermine la langue et le paramètre régional à utiliser​

Lorsqu'un utilisateur charge une application Jutro, les événements suivants se produisent :

  • L'application lit la préférence linguistique du navigateur de l'utilisateur (navigator.language)
  • La langue par défaut de l'application correspond à la préférence du navigateur de l'utilisateur, si cette préférence se trouve également dans availableLanguages, sinon l'application est définie par défaut sur preferredLanguage
  • Le paramètre régional de l'application sera également défini par défaut en fonction de la préférence linguistique du navigateur de l'utilisateur si cette préférence se trouve également dans availableLocales ; dans le cas contraire, il sera défini par défaut sur preferredLocale

Si la fonction createG11nLocalStorageStore est utilisée, les préférences de l'utilisateur sont également enregistrées dans localStorage et mémorisées d'une session à l'autre.

Important: Jutro ne lit pas réellement l'en-tête accept-language du protocole HTTP. Au lieu de cela, le JS côté client lit la propriété navigator.language.

Alors que accept-language peut contenir une liste ordonnée de préférences, navigator.language ne contient qu'une seule valeur. La première valeur dans accept-language sera identique à la valeur unique dans navigator.language.

Interaction avec le magasin g11n​

Le magasin de globalisation (g11n) est activé dans le fichier src/startApp.js. Par défaut, il est initialisé à l'aide des paramètres régionaux de src/config/config.json. Reportez-vous à la section sur la configuration pour en savoir plus.

Vous pouvez utiliser l'une des fonctions suivantes pour initialiser le magasin :

  • createG11nMemoryStore  : gère les paramètres régionaux en mémoire. Ce magasin correspond au paramètre par défaut. Cela signifie que les modifications apportées au magasin sont réinitialisées lorsque la page est actualisée et que vous revenez à votre configuration.
  • createG11nLocalStorageStore : gère les paramètres régionaux dans le stockage local, de sorte que les préférences de l'utilisateur soient conservées dans toutes les sessions. Reportez-vous à la section sur la persistance du choix de l'utilisateur pour en savoir plus.

Lorsque vous utilisez l'une de ces fonctions, vous pouvez remplacer les paramètres par défaut en transmettant un objet avec les propriétés suivantes :

src/startApp.js
const g11nStore = createG11nMemoryStore({
  country: 'PL',
  currency: 'PLN',
  language: 'pl',
  locale: 'pl-PL',
  locales: ['en-GB', 'pl-PL'],
  timeZone: 'Europe/Warsaw',
  languages: ['en', 'pl'],
});

Ensuite, vous devez transmettre le magasin à la fonction startApp :

src/startApp.js
startApp({
  g11nStore,
  // ... other settings
});

Réaction aux modifications des paramètres régionaux​

Si vous souhaitez réagir aux modifications des paramètres régionaux et de la langue, n'importe où dans votre application React, vous pouvez utiliser les crochets useLanguage et useLocale. Voici un exemple :

import { useLanguage, useLocale } from '@jutro/locale';

const MyPanel = () => {
  const {
    availableLocales,
    dateLocale,
    locale,
    defaultTimeZone,
    localeOnChangeCallback,
  } = useLocale();
  const { availableLanguages, language, languageOnChangeCallback } =
    useLanguage();

  return <div>Functionality coming soon, I promise!</div>;
};

Vous pouvez utiliser localeOnChangeCallback et languageOnChangeCallback pour forcer une modification des paramètres régionaux ou de la langue. Par exemple, vous pouvez les utiliser dans les gestionnaires de clics de bouton :

return (
  <>
    <button onClick={() => languageOnChangeCallback('lang')}>
      Change language to "lang"
    </button>
    <button onClick={() => localeOnChangeCallback('loc')}>
      Change locale to "loc"
    </button>
  </>
);

Interaction avec le magasin en dehors de l'arborescence React​

Si vous souhaitez accéder au magasin en dehors de l'arborescence React, vous pouvez utiliser l'une des fonctions createG11n*Store dans le fichier src/startApp.js.

Chaque fois que l'utilisateur modifie l'un des paramètres régionaux, le magasin est mis à jour. Vous pouvez vous abonner à ces modifications en appelant subscribe et en transmettant une fonction de rappel. Ce rappel sera appelé chaque fois que les paramètres régionaux changeront.

src/startApp.js
import { createG11nMemoryStore } from '@jutro/locale';
import { loadConfiguration } from '@jutro/config';
import appConfig from './config/config.json';

// load the configuration from the config.json file
// because globalization store gets defaults from this config
loadConfiguration(appConfig);

// create a store that will save changes in memory
const g11nStore = createG11nMemoryStore({});

// subscribe to all changes
g11nStore.subscribe((state) => {
  console.log('G11n store changed', state);
});

// subscribe to language changes specifically
g11nStore.subscribe(
  (state) => state.language,
  (language) => {
    console.log('Language changed to: ', language);

    window.location.reload();
  }
);

export const startApp = () => {
  start(Jutro, {
    // pass your new local store here
    g11nStore,
    // ... other options
  });
};

Persistance du choix de l'utilisateur​

Pour conserver le choix de l'utilisateur, vous pouvez utiliser la fonction createG11nLocalStorageStore à partir de jutro-locale. Il met automatiquement à jour les paramètres régionaux dans localStorage.

  1. Créez un magasin à l'aide de createG11nLocalStorageStore. Ce magasin enregistre les modifications dans le magasin local du navigateur. Dans l'exemple ci-dessous, nous appelons ce magasin g11nStore.
  2. Transmettez g11nStore à la fonction de démarrage de votre application.
src/startApp.js
import { createG11nLocalStorageStore } from '@jutro/locale';
import { loadConfiguration } from '@jutro/config';
import appConfig from './config/config.json';

// load the configuration from the config.json file
// because globalization store gets defaults from this config
loadConfiguration(appConfig);

// create a store that will save changes in the browser's local store
const g11nStore = createG11nLocalStorageStore({
  name: 'unique-store-name',
});

export const startApp = () => {
  start(Jutro, {
    // pass your new local store here
    g11nStore,
    // ... other options
  });
};

Marquer les messages nécessitant une traduction​

Il s'agit d'un aspect que les développeurs doivent prendre en compte début le début.

Voir également :

Pour les composants définis dans JSX​

Importez la fonction defineMessages à partir de @jutro/locale pour définir les chaînes à traduire.

Placez-les dans un fichier correspondant à votre composant (par exemple, MyPage.messages.js), puis exportez-les :

import { defineMessages } from '@jutro/locale';

export default defineMessages({
  clickMe: {
    id: 'jutro-app.pages.myPage.clickMe',
    defaultMessage: 'Click me!',
    description: 'Action message',
  },
  thanks: {
    id: 'pages.myPage.thanks',
    defaultMessage: 'Thanks for clicking me!',
    description: 'Result message that appears when user clicks a button',
  },
});

Importez les messages dans votre fichier .js correspondant et référencez-les :

import { useTranslator } from '@jutro/locale';
import messages from './MyPage.messages';
...
const translator = useTranslator();
...
const handleClick = () => {
    // eslint-disable-next-line no-alert
    alert(translator(messages.thanks));
};
...
<Button onClick={handleClick}>
    {translator(messages.clickMe)}
</Button>
Pourquoi utiliser un fichier distinct pour les messages JSX ?​

Ce n'est pas obligatoire, mais c'est plus propre. (L'idéal serait de faire quelque chose de similaire pour les chaînes basées sur JSON5 également. Mais pour l'instant, ce n'est pas possible. Dans les fichiers de métadonnées/JSON5, les chaînes doivent y être déclarées directement.)

Lorsque les chaînes sont plus isolées du code, il est plus facile de les modifier sans risquer de casser le code.

Utilisation de la syntaxe de format de message pour les arguments formatés​

Note: Pour plus d’informations sur cette rubrique, reportez-vous à Interpolation de variable.

react-intl (en particulier intl-messageformat) prend en charge la syntaxe MessageFormat de la bibliothèque ICU4J. Au lieu de vous contenter d'intégrer une variable/un argument dans une chaîne en utilisant la syntaxe MessageFormat, vous pouvez également déclarer le type d'un argument et son style de formatage.

Exemples :

  • Your premium is due on {someDate, date}
    • Formatera someDate dans un style abrégé (ce n'est généralement pas une bonne idée, car le format est ambigu)
  • Your premium is due on {someDate, date, long}
    • Formatera someDate dans le style long, comme pour en-US : February 17, 2019
  • You've had {numClaims, number} on this policy
    • Formatera numClaims en tant que nombre. C'est-à-dire qu'il utilisera les séparateurs décimaux et de groupe appropriés au paramètre régional
  • Your premium will increase by {somePercent, number, percent}
    • Formatera somePercent sous forme de chaîne de pourcentage

Pour en savoir plus, reportez-vous à la page FormatJS consacrée aux arguments formatés.

Syntaxe des messages et arguments relatifs aux devises​

Pour formater les devises au moyen de MessageFormat, vous devez utiliser la syntaxe suivante :

Your next payment is for {someAmount, number, :: currency/EUR}.

Le problème dans ce cas est que votre chaîne déclare la devise. Vous devez donc connaître la devise à l'avance. Cette approche ne pourra vraiment fonctionner que pour les applications qui n'utilisent qu'une seule devise

Gestion du texte de l'interface utilisateur traduisible​

Une fois que le texte de l'interface utilisateur a été correctement marqué dans le code, il doit être extrait et fusionné dans un seul fichier. Ce fichier peut ensuite être traduit.

Script d’internationalisation​

Le fichier package.json de votre application contient le script i18n. Ce script exécute jutro generate:i18n. Par défaut, cette opération effectue les opérations suivantes :

  • Extrait le texte correctement marqué des fichiers correspondant à ces modèles : src/**/*.metadata.json5, src/**/*.{ts,tsx,js,jsx}
    • Le texte est extrait dans le répertoire temporaire ./i18n/src/
  • Fusionne tout le texte de l'interface utilisateur à partir des différents fichiers présents dans ./i18n/src dans ./src/i18n/lang.json
  • Le fichier src/i18n/lang.json est pseudo-traduit en src/i18n/yy.json. Ce point est abordé plus en détail ci-dessous

Pour en savoir plus sur la commande jutro generate:i18n, reportez-vous à la section « Générer des traductions d’internationalisation » de la documentation CLI.

Veillez à extraire toutes les chaînes​

Les développeurs laissent souvent des chaînes codées en dur/intégrées dans les applications, ce qui rend la traduction impossible. C'est dans cet esprit que nous avons élaboré le langage Sherlock.

« Sherlock » : le / faux / pseudo langage​

Qu'est-ce que c'est ?​

Il s'agit d'un langage généré automatiquement qui convertit des chaînes de Codeless Form en [2zqq25_Codeless Form]. Cette option est incluse dans la configuration par défaut de l'application exemple.

Notre configuration par défaut possède yy dans availableLanguages. Cela permet à « Sherlock » d'apparaître dans le menu des langues du composant GlobalizationChooser. À proprement parler, dans le monde réel, yy n'est pas un code de langue valide. Cependant, notre logiciel fait correspondre ce code de langue à notre propre langage fictif « Sherlock ». Il doit être supprimé des configurations de production.

Quelle valeur cela apporte-t-il ?​
  • Toutes les chaînes qui apparaissent sans crochet ni hachage préétabli n'ont pas été correctement extraites. Cela signifie que votre code contient un bug. Évidemment, les chaînes de données client apparaissent normalement.
  • Le hachage lui-même : il peut sembler aléatoire, mais il est unique pour chaque paire clé/valeur.

Chaînes d'interface utilisateur et prévisualisation en direct​

Lorsque vous démarrez votre application en utilisant npm start, celle-ci passe en mode « aperçu en direct ». Cela signifie que les modifications que vous apportez à votre code sont immédiatement reflétées dans votre navigateur.

Malheureusement, les modifications apportées aux chaînes sources existantes ne sont pas mises à jour dans l'aperçu en direct. Il est nécessaire de relancer le pseudo-cycle d'extraction et de fusion au moyen de npm run i18n. La reconstruction de l'application appellera également ce script.

Traduire votre application​

La langue source par défaut est l'anglais, avec le code de langue en.

Par défaut, conformément à l'exemple d'application, ces chaînes se trouveront dans le fichier ./src/i18n/lang.json. Ce fichier est ajouté à .gitignore, les traducteurs doivent plutôt copier le fichier et le traduire dans d'autres langues, par ex. en.json, de.json...

N'oubliez pas non plus que seul npm run i18n (ou build) peut garantir que toutes les chaînes seront extraites du code et fusionnées dans ce fichier.

Vos fichiers de traduction doivent être ajoutés au même répertoire que le fichier lang.json.

Texte de l'interface utilisateur à partir de la structure Jutro​

Comme toute infrastructure d'interface utilisateur, Jutro comporte du texte d'interface utilisateur, distinct de celui de votre application. Votre application exposera probablement au moins une partie de ce texte. Ce texte couvre des chaînes telles que « OK », « Suivant », « Annuler » et « Soumettre ». Les composants qui exposent ce type de texte vous permettent souvent de remplacer le texte par défaut. Cependant, certains ne le font pas, comme la liste des pays à choisir dans le composant IntlPhoneNumberField.

Outre l'anglais de base (États-Unis), le texte-cadre est traduit dans les langues suivantes : danois, allemand, espagnol (Espagne), espagnol (États-Unis), français, italien, japonais, néerlandais, norvégien, portugais, russe et chinois simplifié.

Cela peut ne pas être suffisant pour vous.

Remplacement de chaînes d'infrastructure ou fourniture de vos propres traductions​

Supposons que vous rencontriez l'un des scénarios suivants :

  • Vous souhaitez modifier le texte par défaut utilisé par nos composants
  • Vous souhaitez modifier certaines des traductions que nous fournissons
  • Vous souhaitez traduire le cadre au-delà des langues que nous prenons en charge

Voici ce que vous faites :

  1. Quelque part en dessous de ./src, créez un fichier framework.messages.js, similaire à ce qui est décrit ici
  2. Copiez la liste des chaînes d'infrastructure source à partir de node_modules/@jutro/translations/lang-data/en.json
  3. Dans le framework.messages.js créé ci-dessus, ajoutez toutes ces chaînes d'infrastructure (ou seulement certaines d'entre elles) à l'aide de la forme de type paire id et defaultMessage. Si vous souhaitez modifier defaultMessage pour une chaîne particulière, faites-le ici
  4. Lors de la reconstruction, vous verrez que ces chaînes ont maintenant été ajoutées au fichier ./src/i18n/lang.json
  5. Vous pouvez maintenant traduire les chaînes de la structure comme vous le feriez pour les chaînes de votre application

Composants sensibles aux paramètres régionaux​

Des éléments tels que l'affichage, le formatage des dates, des heures, des nombres, des calendriers, des montants monétaires et des pourcentages varient selon les paramètres régionaux. Jutro propose plusieurs composants qui respectent les paramètres régionaux de l'utilisateur.

Dates, heures, calendriers​

Jutro offre une variété d'options de date, d'heure et de calendrier.

Composants​

Ils sont tous disponibles depuis @jutro/components.

DateField : affiche un élément de saisie de type sélecteur de date. Il offre un système complet pour la saisie et la sélection de la date et de l'heure, ainsi qu'un mode de lecture seule.

FormattedDate : affiche une date formatée intégrée (sans <div>). Prend en charge un certain nombre de formats prédéfinis :

Paramètres régionauxshortlongabbreviatedfull
en-USAug 30, 2018August 30, 2018Thu, Aug 30, 2018Thursday, August 30, 2018
fr-FR30 août 201830 août 2018jeu. 30 août 2018jeudi 30 août 2018
pl-PL30 sie 201830 sierpnia 2018czw., 30 sierpnia 2018czwartek, 30 sierpnia 2018

DateValue : affiche une date formatée au moyen de la propriété tag pour envelopper la valeur.

FormattedDateRange : similaire à FormattedDate, mais pour une plage de dates plutôt que pour une seule date.

Tous ces éléments sont présentés en fonction des paramètres régionaux.

API​

Disponible à partir de @jutro/components

formatDate et formatDateRange : API impératives pour le formatage des dates et des heures au moyen du paramètre régional.

Nombres (et non montants monétaires)​

Composants​

Disponible à partir de @jutro/components

InputNumberField : affiche un élément de saisie pour les champs numériques. Dispose également d'une option en lecture seule.

FormattedNumber : prend en charge le mode lecture seule et les notifications intégrées.

NumberValue : affiche une devise formatée au moyen de la propriété tag pour envelopper la valeur.

Paramètres régionauxSortie formatée
en-US23,234.34
fr-FR23 234,34
de-DE23.234,34

API​

Disponible à partir de @jutro/components

formatNumber : API impérative pour le formatage des nombres au moyen du paramètre régional

Montants monétaires​

Composants​

Disponible à partir de @jutro/components

CurrencyInput : permet de saisir ou d'afficher une valeur monétaire. Le formatage est basé sur les paramètres régionaux. Prend en charge les modes de saisie et de lecture seule.

FormattedCurrency : affiche une valeur de devise formatée intégrée. (Sans <div>).

CurrencyValue : affiche une devise formatée au moyen de la propriété tag pour envelopper la valeur.

Les composants ci-dessus vous permettent de définir la propriété currencyDisplay. Pour un montant en dollars américains, exprimé avec le paramètre régional en-US, si vous définissez la propriété currencyDisplay sur code, vous obtiendrez USD, alors que si vous la définissez sur symbol, vous obtiendrez $.

La devise elle-même (USD ou EUR, par exemple) est fournie en tant que propriété du composant et n'est absolument pas liée au paramètre régional ni au pays de l'utilisateur.

Le paramètre régional détermine la façon dont le montant de la devise est formaté, mais pas la devise elle-même.

Paramètres régionauxSortie formatée (code)Sortie formatée (symbol)
en-USUSD 23,234.34$23,234.34
fr-FR23 234,34 USD23 234,34 $US
de-DE23.234,34 USD23,234.34 $

API​

Disponible à partir de @jutro/components

formatCurrency : API impérative pour le formatage des valeurs monétaires au moyen du paramètre régional actuel

Il n'y a pas de paramètre defaultCurrency global pour les composants liés à la devise.

Cela signifie que vous devez transmettre la devise ou la devise par défaut à utiliser aux composants liés à la devise CurrencyInput, FormattedCurrency et CurrencyValue :

<CurrencyInput
  availableCurrencies={['USD']}
  label="Currency input component"
/>

Dans le cas de CurrencyValue, si defaultCurrency n'est pas défini, le composant est défini par défaut sur dollars US ou USD. Vous pouvez également lire cette valeur en appelant la fonction getDefaultCurrency à partir du package de paramètres régionaux de Jutro afin de la récupérer, puis de la transmettre au composant correspondant.

import { getDefaultCurrency } from '@jutro/locale';

Tri/classement​

Le classement de texte, également appelé tri, est spécifique à chaque langue. Chaque langue possède ses propres règles de tri.

Fuseau horaire​

Par défaut, toutes les dates accompagnées d'une heure sont stockées en tant que date UTC et converties dans le fuseau horaire local de l'utilisateur lors de l'affichage. Vous pouvez remplacer ce comportement en définissant defaultTimeZone dans localeSettings dans src/config/config.json.

"localeSettings": {
    ...
    "defaultTimeZone": "Atlantic/Faroe"
}

Lorsque defaultTimeZone est activé, toutes les dates accompagnées d'une heure sont converties en fuseau horaire defaultTimeZone lors de l'affichage (mais elles restent stockées sous la forme de dates UTC). La seule exception concerne le composant DateTimeZoneField, pour lequel l'utilisateur peut sélectionner un fuseau horaire dans la liste. Dans ce cas, defaultTimeZone est utilisé en tant que fuseau horaire par défaut.

La valeur de defaultTimeZone doit être un fuseau horaire IANA valide.

Noms au pluriel dans le texte de l'interface utilisateur​

Les noms au pluriel sont un problème linguistique délicat que Jutro résout grâce à son utilisation de la bibliothèque react-intl.

Utilisez ce pseudo-code :

if (numPolicies === 1) print('You have 1 policy with us');
else print('You have {numPolicies} policies with us');

Le code ci-dessus fonctionne pour l'anglais, mais la logique échoue pour de nombreuses autres langues.

De nombreuses langues possèdent des règles beaucoup plus complexes au sujet des noms au pluriel. Même le français présente des règles différentes de celles de l'anglais. (Le français utilise la forme singulière lorsque la quantité équivaut à 1 ou 0).

Certaines langues ont trois (polonais), quatre (russe) voire six (arabe) formes plurielles, toutes dépendantes de la valeur de l'entier qui ne peut être connue qu'au moment de l'exécution. Cette page Unicode CLDR explique la logique mathématique autour des pluriels pour de nombreuses langues.

Prise en charge de la pluralisation dans Jutro​

Reportez-vous à la documentation FormatJS et au guide de syntaxe ICU MessageFormat.

Note:
  • La syntaxe au pluriel n'est pas entièrement intuitive, ni pour les développeurs ni pour les traducteurs.
  • En cas de traduction, assurez-vous que vos fournisseurs d'outils de traduction comprennent et prennent en charge cette syntaxe.