intl messageformat

Ce repo a été migré vers le monorepo

INTL MessageFormat

Formats des chaînes de messages USI avec numéro, date, pluriel et sélectionner les espaces réservés pour créer des messages localisés.

Aperçu

Objectifs

Ce package vise à vous fournir un moyen de gérer et de formater les messages de chaîne de votre application JavaScript en chaînes localisées pour les personnes utilisant votre application. Vous pouvez utiliser ce package dans le navigateur et sur le serveur via Node.js.

Cette implémentation est basée sur la proposition de Strawman, mais il existe quelques endroits que cette implémentation diverge.

Remarque: Cette API IntlMessageFormat peut changer pour rester en synchronisation avec ECMA-402, mais ce package suivra Semver.

Comment ça marche

Des messages sont fournis dans le constructeur en tant que message String ou un objet AST pré-payé.

 var msg = new IntlMessageFormat ( message , locales , [ formats ] ) ;

Le message de chaîne est analysé, puis stocké en interne sous une forme compilée qui est optimisée pour la méthode format() afin de produire la chaîne formatée à afficher à l'utilisateur.

 var output = msg . format ( values ) ;

Exemple d'usage commun

Un exemple très courant est la mise en forme de messages qui ont des nombres avec les étiquettes plurielles. Avec ce package, vous pouvez vous assurer que la chaîne est correctement formatée pour les paramètres régionaux d'une personne, par exemple:

 var MESSAGES = {
    'en-US' : {
        NUM_PHOTOS : 'You have {numPhotos, plural, ' +
            '=0 {no photos.}' +
            '=1 {one photo.}' +
            'other {# photos.}}'
    } ,

    'es-MX' : {
        NUM_PHOTOS : 'Usted {numPhotos, plural, ' +
            '=0 {no tiene fotos.}' +
            '=1 {tiene una foto.}' +
            'other {tiene # fotos.}}'
    }
} ;

var output ;

var enNumPhotos = new IntlMessageFormat ( MESSAGES [ 'en-US' ] . NUM_PHOTOS , 'en-US' ) ;
output = enNumPhotos . format ( { numPhotos : 1000 } ) ;
console . log ( output ) ; // => "You have 1,000 photos."

var esNumPhotos = new IntlMessageFormat ( MESSAGES [ 'es-MX' ] . NUM_PHOTOS , 'es-MX' ) ;
output = esNumPhotos . format ( { numPhotos : 1000 } ) ;
console . log ( output ) ; // => "Usted tiene 1,000 fotos."

Syntaxe de message

La syntaxe du message que ce package utilise n'est pas propriétaire, en fait, c'est une syntaxe de message standard commune qui fonctionne dans les langages de programmation et celui que les traducteurs professionnels connaissent. Ce package utilise la syntaxe du message ICU et fonctionne pour toutes les langues CLDR qui ont des règles de pluralisation définies.

Caractéristiques

• Utilise les normes de l'industrie: Syntaxe des messages USI et données locales CLDR.

• Prend en charge les arguments de message pluriel , sélectionné et sélectionné .

• Formats Nombres et Dates / Temps dans les messages à l'aide de Intl.NumberFormat et Intl.DateTimeFormat , respectivement.

• Optimisé pour les appels répétés vers la méthode format() d'une instance IntlMessageFormat .

• Prend en charge la définition des styles / options de format personnalisés.

• Prend en charge les séquences d'échappement pour les chars de syntaxe de message, par exemple: "\{foo\}" sera sorti: "{foo}" dans la sortie formatée au lieu de l'interpréter comme un argument foo .

Usage

Dépendance Intl moderne

Ce package suppose que l'objet global Intl existe dans l'exécution. Intl est présent dans tous les navigateurs modernes (IE11 +) et le nœud (avec USI complet). Les méthodes Intl sur lesquelles nous comptons sont:

1. Intl.NumberFormat pour le formatage des nombres (peut être polyvalent en utilisant intl.js)
2. Intl.DateTimeFormat pour le formatage de date de date (peut être polyvalent en utilisant intl.js)
3. Intl.PluralRules pour le formatage pluriel / ordinal (peut être polyvalent en utilisant INTL-PLURALRULES)

Chargement INTL MessageFormat dans un navigateur

 < script src =" intl-messageformat/intl-messageformat.min.js " > </ script >

Chargement INTL MessageFormat dans Node.js

require() ce package:

 var IntlMessageFormat = require ( 'intl-messageformat' ) ;

Remarque: votre nœud doit inclure une ICU complète

API publique

Constructeur IntlMessageFormat

Pour créer un message au format, utilisez le constructeur IntlMessageFormat . Le constructeur prend trois paramètres:

• Message - {String | AST} - Message de chaîne (ou AST pré-payé) qui sert de modèle de formatage.

• LOCALES - {String | String []} - une chaîne avec une balise de langue BCP 47, ou un tableau de ces chaînes. Si vous ne fournissez pas de paramètre régional, les paramètres par défaut seront utilisés. Lorsqu'un éventail de localités est fourni, chaque élément et ses lieux d'ancêtre sont vérifiés et le premier avec des données locales enregistrées est renvoyé. Voir: Résolution des paramètres régionaux pour plus de détails.

• [Formats] - {objet} - Objet facultatif avec des options définies par l'utilisateur pour les styles de format.

 var msg = new IntlMessageFormat ( 'My name is {name}.' , 'en-US' ) ; 

Résolution des paramètres régionaux

IntlMessageFormat utilise Intl.NumberFormat.supportedLocalesOf() pour déterminer les données des zones à utiliser en fonction de la valeur locales transmise au constructeur. Le résultat de ce processus de résolution peut être déterminé par l'appel de la méthode du prototype resolvedOptions() .

Méthode resolvedOptions()

Cette méthode renvoie un objet avec les valeurs d'options qui ont été résolues pendant la création d'instructions. Il ne contient actuellement qu'une propriété locale ; Voici un exemple:

 var msg = new IntlMessageFormat ( '' , 'en-us' ) ;
console . log ( msg . resolvedOptions ( ) . locale ) ; // => "en-US"

Remarquez comment les paramètres régionaux spécifiés étaient la valeur toutes les cas inférieurs: "en-us" , mais il a été résolu et normalisé en: "en-US" .

Méthode format(values)

Une fois le message créé, le formatage du message est effectué en appelant la méthode format() sur l'instance et en passant une collection de values :

 var output = msg . format ( { name : "Eric" } ) ;
console . log ( output ) ; // => "My name is Eric."

Remarque: Une valeur doit être fournie pour chaque argument du modèle de message avec lequel l'instance a été construite.

Formats définis par l'utilisateur

Définir les styles de format personnalisés est utile, vous devez fournir un ensemble d'options au formateur sous-jacent; par exemple, en sortant un nombre en USD:

 var msg = new IntlMessageFormat ( 'The price is: {price, number, USD}' , 'en-US' , {
    number : {
        USD : {
            style   : 'currency' ,
            currency : 'USD'
        }
    }
} ) ;

var output = msg . format ( { price : 100 } ) ;
console . log ( output ) ; // => "The price is: $100.00"

Dans cet exemple, nous définissons un style de format de numéro USD qui est transmis à l'instance Intl.NumberFormat sous-jacente comme options.

Exemples

Label pluriel

Cet exemple montre comment utiliser la syntaxe du message USI pour définir un message qui a une étiquette plurielle; Par exemple, "You have 10 photos" :

 You have {numPhotos, plural,
    =0 {no photos.}
    =1 {one photo.}
    other {# photos.}
}

 var MESSAGES = {
    photos : '...' , // String from code block above.
    ...
} ;

var msg = new IntlMessageFormat ( MESSAGES . photos , 'en-US' ) ;

console . log ( msg . format ( { numPhotos : 0 } ) ) ;    // => "You have no photos."
console . log ( msg . format ( { numPhotos : 1 } ) ) ;    // => "You have one photo."
console . log ( msg . format ( { numPhotos : 1000 } ) ) ; // => "You have 1,000 photos."

Remarque: Comment lorsque numPhotos était 1000 , le nombre est formaté avec le bon séparateur de milliers.

Licence

Ce logiciel est gratuit sous le Yahoo! Inc. Licence BSD. Voir le fichier de licence pour le texte de licence et les informations sur le droit d'auteur.