intl messageformat

Este repositorio fue migrado al monorepo

Intl MessageFormat

Formatos de cadenas de mensajes de la UCI con número, fecha, plural y seleccionan marcadores de posición para crear mensajes localizados.

Descripción general

Objetivos

Este paquete tiene como objetivo proporcionar una forma de administrar y formatear los mensajes de cadena de su aplicación JavaScript en cadenas localizadas para personas que usan su aplicación. Puede usar este paquete en el navegador y en el servidor a través de Node.js.

Esta implementación se basa en la propuesta de Strawman, pero hay algunos lugares que esta implementación diverge.

Nota: Esta API IntlMessageFormat puede cambiar para mantenerse en sincronización con ECMA-402, pero este paquete seguirá a Semver.

Cómo funciona

Los mensajes se proporcionan en el constructor como un mensaje String , o un objeto AST pre-cargado.

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

El message de cadena se analiza, luego se almacena internamente en un formulario compilado que está optimizado para el método format() para producir la cadena formateada para que se muestre al usuario.

 var output = msg . format ( values ) ;

Ejemplo de uso común

Un ejemplo muy común es formatear mensajes que tienen números con etiquetas plurales. Con este paquete, puede asegurarse de que la cadena esté formateada correctamente para la localidad de una persona, por ejemplo:

 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."

Sintaxis de mensajes

La sintaxis del mensaje que utiliza este paquete no es propietario, de hecho, es una sintaxis de mensaje estándar común que funciona en los lenguajes de programación y una con la que los traductores profesionales están familiarizados. Este paquete utiliza la sintaxis del mensaje de la UCI y funciona para todos los idiomas CLDR que tienen reglas de pluralización definidas.

Características

• Utiliza estándares de la industria: sintaxis de mensajes de la UCI y datos locales CLDR.

• Admite argumentos de mensajes plurales , seleccionados y seleccionados .

• Formatos de números y fechas/tiempos en mensajes utilizando Intl.NumberFormat e Intl.DateTimeFormat , respectivamente.

• Optimizado para llamadas repetidas al método format() de instancia IntlMessageFormat .

• Admite la definición de estilos/opciones de formato personalizado.

• Admite secuencias de escape para los caracteres de sintaxis de mensajes, por ejemplo, "\{foo\}" emitirá: "{foo}" en la salida formateada en lugar de interpretarlo como un argumento foo .

Uso

Dependencia Intl moderna

Este paquete supone que el objeto Global Intl existe en el tiempo de ejecución. Intl está presente en todos los navegadores modernos (IE11+) y el nodo (con UCI completo). Los métodos Intl en los que confiamos son:

1. Intl.NumberFormat para el formato de número (se puede poliizar usando intl.js)
2. Intl.DateTimeFormat para el formato de hora de fecha (puede ser poliñimentada usando intl.js)
3. Intl.PluralRules para formato plural/ordinal (puede ser poliñimentado usando intl-pluralrules)

Cargando intl MessageFormat en un navegador

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

Cargando intl MessageFormat en node.js

Simplemente require() este paquete:

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

Nota: Su nodo debe incluir UCI completo

API pública

IntlMessageFormat Constructor

Para crear un mensaje para formatear, use el constructor IntlMessageFormat . El constructor toma tres parámetros:

• Mensaje - {cadena | AST} - Mensaje de cadena (o AST prepsedado) que sirve como patrón de formato.

• Locos - {cadena | String []} - Una cadena con una etiqueta de idioma BCP 47, o una matriz de tales cadenas. Si no proporciona una ubicación local, se utilizará la ubicación predeterminada. Cuando se proporciona una variedad de locales, cada elemento y sus locales de antepasados ​​se verifican y se devuelve el primero con datos de locales registrados. Ver: Resolución local para más detalles.

• [Formatos] - {objeto} - Objeto opcional con opciones definidas por el usuario para estilos de formato.

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

Resolución local

IntlMessageFormat utiliza Intl.NumberFormat.supportedLocalesOf() para determinar qué datos locales usar en función del valor locales pasados ​​al constructor. El resultado de este proceso de resolución se puede determinar mediante la llamada del método prototipo resolvedOptions() .

método resolvedOptions()

Este método devuelve un objeto con los valores de opciones que se resolvieron durante la creación de instancias. Actualmente solo contiene una propiedad locale ; Aquí hay un ejemplo:

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

Observe cómo la ubicación especificada era el valor de mayor caso: "en-us" , pero se resolvió y se normalizó a: "en-US" .

Método format(values)

Una vez que se crea el mensaje, el formateo del mensaje se realiza llamando al método format() en la instancia y pasando una colección de values :

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

Nota: Se debe suministrar un valor para cada argumento en el patrón de mensaje con el que se construyó la instancia.

Formatos definidos por el usuario

Definir estilos de formato personalizado es útil que necesita proporcionar un conjunto de opciones al formateador subyacente; por ejemplo, generando un número 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"

En este ejemplo, estamos definiendo un estilo de formato de número USD que se pasa a la instancia de Intl.NumberFormat subyacente como sus opciones.

Ejemplos

Etiqueta plural

Este ejemplo muestra cómo usar la sintaxis del mensaje de la UCI para definir un mensaje que tenga una etiqueta plural; por ejemplo, "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."

Nota: Cómo, cuando numPhotos era 1000 , el número está formateado con el separador de miles correctos.

Licencia

Este software es gratuito bajo el Yahoo! Inc. Licencia BSD. Consulte el archivo de licencia para ver el texto de la licencia y la información de derechos de autor.