messageformat-runtime

messageformat-runtime/messages

Accessor class for compiled message functions generated by messageformat

import Messages from 'messageformat-runtime/messages'

messageformat-runtime/messages
- module.exports ⏏
  - new module.exports(msgData, [defaultLocale])
  - .availableLocales : Array.<string>
  - .locale : string | null
  - .defaultLocale : string | null
  - .addMessages(data, [lc], [keypath]) ⇒ Messages
  - .resolveLocale(lc) ⇒ string | null
  - .getFallback([lc]) ⇒ Array.<string>
  - .setFallback(lc, fallback) ⇒ Messages
  - .hasMessage(key, [lc], [fallback]) ⇒ boolean
  - .hasObject(key, [lc], [fallback]) ⇒ boolean
  - .get(key, [props], [lc]) ⇒ string | Object.<string, (function()|object)>

module.exports ⏏

Kind: Exported class

new module.exports(msgData, [defaultLocale])

Param	Type	Description
msgData	`object`	A map of locale codes to their function objects
[defaultLocale]	`string`	If not defined, default and initial locale is the first entry of `locales`

Example

// build.js
import fs from 'fs';
import MessageFormat from 'messageformat';
 
const mf = new MessageFormat(['en', 'fi']);
const msgSet = {
  en: {
    a: 'A {TYPE} example.',
    b: 'This has {COUNT, plural, one{one user} other{# users}}.',
    c: {
      d: 'We have {P, number, percent} code coverage.'
    }
  },
  fi: {
    b: 'Tällä on {COUNT, plural, one{yksi käyttäjä} other{# käyttäjää}}.',
    e: 'Minä puhun vain suomea.'
  }
};
fs.writeFileSync('messages.js', String(mf.compile(msgSet)));

// runtime.js
import Messages from 'messageformat-runtime/messages';
import msgData from './messages';
 
const messages = new Messages(msgData, 'en');
 
messages.hasMessage('a')                // true
messages.hasObject('c')                 // true
messages.get('b', { COUNT: 3 })         // 'This has 3 users.'
messages.get(['c', 'd'], { P: 0.314 })  // 'We have 31% code coverage.'
 
messages.get('e')                       // 'e'
messages.setFallback('en', ['foo', 'fi'])
messages.get('e')                       // 'Minä puhun vain suomea.'
 
messages.locale = 'fi'
messages.hasMessage('a')                // false
messages.hasMessage('a', 'en')          // true
messages.hasMessage('a', null, true)    // true
messages.hasObject('c')                 // false
messages.get('b', { COUNT: 3 })         // 'Tällä on 3 käyttäjää.'
messages.get('c').d({ P: 0.628 })       // 'We have 63% code coverage.'

module.exports.availableLocales : `Array.<string>`

List of available locales

Kind: instance property of module.exports
Read only: true

module.exports.locale : `string` | `null`

Current locale

One of Messages#availableLocales or null. Partial matches of language tags are supported, so e.g. with an en locale defined, it will be selected by messages.locale = 'en-US' and vice versa.

Kind: instance property of module.exports

module.exports.defaultLocale : `string` | `null`

Default fallback locale

One of Messages#availableLocales or null. Partial matches of language tags are supported, so e.g. with an en locale defined, it will be selected by messages.defaultLocale = 'en-US' and vice versa.

Kind: instance property of module.exports

module.exports.addMessages(data, [lc], [keypath]) ⇒ `Messages`

Add new messages to the accessor; useful if loading data dynamically

The locale code lc should be an exact match for the locale being updated, or empty to default to the current locale. Use #resolveLocale for resolving partial locale strings.

If keypath is empty, adds or sets the complete message object for the corresponding locale. If any keys in keypath do not exist, a new object will be created at that key.

Kind: instance method of module.exports
Returns: Messages - The Messages instance, to allow for chaining

Param	Type	Description
data	`function` \| `object`	Hierarchical map of keys to functions, or a single message function
[lc]	`string`	If empty or undefined, defaults to `this.locale`
[keypath]	`Array.<string>`	The keypath being added

module.exports.resolveLocale(lc) ⇒ `string` | `null`

Resolve lc to the key of an available locale or null, allowing for partial matches. For example, with an en locale defined, it will be selected by messages.defaultLocale = 'en-US' and vice versa.

Kind: instance method of module.exports

Param	Type	Description
lc	`string`	Locale code

module.exports.getFallback([lc]) ⇒ `Array.<string>`

Get the list of fallback locales

Kind: instance method of module.exports

Param	Type	Description
[lc]	`string`	If empty or undefined, defaults to `this.locale`

module.exports.setFallback(lc, fallback) ⇒ `Messages`

Set the fallback locale or locales for lc

To disable fallback for the locale, use setFallback(lc, []). To use the default fallback, use setFallback(lc, null).

Kind: instance method of module.exports
Returns: Messages - The Messages instance, to allow for chaining

Param	Type
lc	`string`
fallback	`Array.<string>` \| `null`

module.exports.hasMessage(key, [lc], [fallback]) ⇒ `boolean`

Check if key is a message function for the locale

key may be a string for functions at the root level, or string[] for accessing hierarchical objects. If an exact match is not found and fallback is true, the fallback locales are checked for the first match.

Kind: instance method of module.exports

Param	Type	Default	Description
key	`string` \| `Array.<string>`		The key or keypath being sought
[lc]	`string`		If empty or undefined, defaults to `this.locale`
[fallback]	`boolean`	`false`	If true, also checks fallback locales

module.exports.hasObject(key, [lc], [fallback]) ⇒ `boolean`

Check if key is a message object for the locale

Kind: instance method of module.exports

Param	Type	Default	Description
key	`string` \| `Array.<string>`		The key or keypath being sought
[lc]	`string`		If empty or undefined, defaults to `this.locale`
[fallback]	`boolean`	`false`	If true, also checks fallback locales

module.exports.get(key, [props], [lc]) ⇒ `string` | `Object.<string, (function()|object)>`

Get the message or object corresponding to key

key may be a string for functions at the root level, or string[] for accessing hierarchical objects. If an exact match is not found, the fallback locales are checked for the first match.

If key maps to a message function, it will be called with props. If it maps to an object, the object is returned directly.

Kind: instance method of module.exports

Param	Type	Description
key	`string` \| `Array.<string>`	The key or keypath being sought
[props]	`object`	Optional properties passed to the function
[lc]	`string`	If empty or undefined, defaults to `this.locale`

messageformat-runtime