JavaScript API¶

createTranslator¶

import { createTranslator } from 'dash-i18n';
myTranslator = createTranslator( [options] );

Creates a new Translator object and returns it. This factory function accepts an optional JavaScript Object argument options. You can specify the following properties:

Prop	Default	Value
`messages`	`{}`	Message resources (JavaScript Object key-values)
`messageList`	`[]`	Message resources (`[key, value]` array)
`locale`	`'en'`	Initial locale – language code (String)
`fallbackLocale`	`'en'`	Initial fallback locale (String)
`sep`	`'.'`	Separator for resource key and locale (String)

The prop messages specifies the initial message resources represented in the JavaScript Object key-value pairs. See addMessages for the details.

The prop messageList specifies the initial message resources represented in [key, value] array. See addMessageList for the details.

The prop locale specifies the initial locale value which defaults to 'en'.

The prop fallbackLocale specifies the initial fallback locale value which defaults to 'en'.

Note

The fallback locale is the supplemental locale which will be tried when the query with the current locale fails.

The prop sep specifies the separator string to separate the last locale component in keys. The value of the separator defaults to '.'.

Hint

If you choose '_' (underscore) as a separator, then keys can be represented strings which equivalent to JavaScript identifiers. In that case, you can omit quotes around the keys.

Example:

const myTranslator = createTranslator({
  messages: {
    greeting_morning_en: 'Good morning',
    greeting_morning_ja: 'おはよう',
  },
  sep: '_',
});

const myTranslator2 = createTranslator({
  locale: 'ja',
  fallbackLocale: 'ja',
  messageList: [
    ['greeting.evening.en', 'Good evening'],
    ['greeting.evening.ja', 'こんばんは'],
  ],
});

addMessages¶

myTranslator.addMessages( messages );

The method function addMessages adds message resources to the translator object via a JavaScript Object key-values.

The message resources are represented as key-value pairs in a JavaScript Object messages.

Note

The key of a message resource designates a certain internationalization (i18n) message. The key must be an unique string and end with ${separator}${locale} (e.g. '.en').

Hint

You can use any string as a separator. (See createTranslator for the details.)

The value of a message resource can be a string, an array of strings, or a function (closure).

When the value of a message resource is an array of strings, all the strings are concatenated. This is a convenient way to write a long, mult-line message.

When the value of a message resource is a function, the function will be evaluated with a supplemental argument props. The function must return a string. (See tr for the further details.)

Example:

const myTranslator = createTranslator();
myTranslator.addMessage({
  'greeting.morning.en': 'Good morning',
  'greeting.morning.ja': 'おはよう',
});
myTranslator.addMessage({
  'greeting.evening.en': 'Good evening',
  'greeting.evening.ja': 'こんばんは',
});

myTranslator.tr('greeting.morning');  // → 'Good morning'
myTranslator.setLocale('ja');
myTranslator.tr('greeting.evening');  // → 'こんばんは'

Note

If you add a message resource which has the key already registered in your translator object, then it shadows the previous one.

addMessageList¶

myTranslator.addMessages( messageList );

The method function addMessageList adds message resources to the translator object via a [key, value] array.

Note

The key of a message resource designates a certain internationalization (i18n) message. The key must be an unique string and end with ${separator}${locale} (e.g. '.en').

Hint

You can use any string as a separator. (See createTranslator for the details.)

The value of a message resource can be a string, an array of strings, or a function (closure).

When the value of a message resource is an array of strings, all the strings are concatenated. This is a convenient way to write a long, mult-line message.

When the value of a message resource is a function, the function will be evaluated with a supplemental argument props. The function must return a string. (See tr for the further details.)

Example:

const myTranslator = createTranslator();
myTranslator.addMessage([
  ['greeting.morning.en', 'Good morning'],
  ['greeting.morning.ja', 'おはよう'],
});
myTranslator.addMessage([
  ['greeting.evening.en', 'Good evening'],
  ['greeting.evening.ja', 'こんばんは'],
]);
myTranslator.tr('greeting.morning');  // → 'Good morning'
myTranslator.setLocale('ja');
myTranslator.tr('greeting.morning');  // → 'おはよう'

Note

If you add a message resource which has the key already registered in your translator object, then it shadows the previous one.

setLocale¶

myTranslator.setLocale( locale );

The method function setLocale sets the locale of the translaor object to translate messages.

Example:

const myTranslator = createTranslator({
  messages: {
    'greeting.morning.en': 'Good morning',
    'greeting.morning.ja': 'おはよう',
  }
});
myTranslator.tr('greeting.morning');  // → 'Good morning'
myTranslator.setLocale('ja');
myTranslator.tr('greeting.morning');  // → 'おはよう'

tr¶

myTranslator.tr( key [, props]);

The method function tr returns the message for the given resource key (string) with the current locale. When there is no message resource matches to the key and the current locale (language code), the fallback locale (language code) will be used to retry.

If the value of resource is a function (closure), then the optional second argument will be passed to the function and the return value of the function will be returned.

If no message resource is found, then this function returns null.

Example:

const myTranslator = createTranslator({
  messages: {
    'greeting.en': ['Hello, ', 'world!'],
    'greeting.ja': 'こんにちは世界！',
    'greeting.personalized.en': props => {
       const { name = 'Unknown' } = props;
       return `Hello, ${name}`;
    },
  }
});
myTranslator.tr('greeting');  // → 'Hello, world!'
myTranslator.setLocale('ja');
myTranslator.tr('greeting');  // → 'こんにちは世界！'
myTranslator.setLocale('en');
myTranslator.tr('greeting.personalized', { name: 'Dave');  // → 'Hello, Dave'
myTranslator.tr('notFound');  // → null