createI18n function #

Creating a new i18n instance using createI18n will create an instance of the I18n class.
This class provides methods for working with multiple languages and localisations.

The i18n instance will be created as a singleton - this ensures only one instance exists.

import { createI18n } from 'https://cdn.skypack.dev/ficusjs@3'

// create the i18n instance and add the messages
const i18n = createI18n()

The current locale is set according to the following rules:

  1. lang query string parameter ?lang=es
  2. HTML lang attribute <html lang="es">
  3. navigator.language property

Methods #

The following methods are available on the i18n instance.

add(items, locale, prefix) #

i18n.add({ greeting: 'Hello FicusJS' }, 'en')

The add() method adds messages to the i18n instance.

Message interpolation uses double handlebars {{ value }}.

The following arguments can be passed to the add() method.

ArgumentTypeRequiredDescription
itemsobjectYesThe object containing messages
localestringAn optional locale for the messages. For example es. The default is en
prefixstringAn optional prefix for the messages

t(key, templateData, options) #

The t() method retrieves the translation message for the current locale.

Translation messages are stored under the specified key according to the current locale.
If templateData is present, messages are interpolated with templateData.

A specific locale translation can be specified via options.locale.

Pluralization is done in reference to count template data value when an array is passed to the t() function (override with options.pluralizeTo).

The following arguments can be passed to the t() method.

ArgumentTypeRequiredDescription
keystringYesThe key for the specific message. This can be a nested key like navbar.buttons.home
templateDataobjectThe optional data for message interpolation. The keys must match the message value. For example; the message Greeting {{ name }} requires a templateData object containing { name: 'FicusJS' }
optionsobjectAn optional set of options for the message translation
i18n.add({
  navbar: {
    buttons: {
      home: "Home"
    }
  }
})

const value = i18n.t('navbar.buttons.home')

// value is 'Home'

setLocale(locale) #

The setLocale() method sets the current locale of the i18n instance.

The following arguments can be passed to the setLocale() method.

ArgumentTypeRequiredDescription
localestringYesThe locale string. The default is en
i18n.setLocale('es')

getLocale() #

The getLocale() method gets the current locale of the i18n instance.

const locale = i18n.getLocale()

// locale is 'es'

interpolateWith(userRE) #

The interpolateWith() method sets the regular expression for template strings interpolation.
By default, string interpolation uses double handlebars {{ value }}.

This can be overridden using the interpolateWith() with the following arguments.

ArgumentTypeRequiredDescription
userRERegExpYesThe regex for template string interpolation
i18n.add({ welcomeMessage: 'Hello $userName' })

i18n.interpolateWith(/\$(\w+)/g)

const value = i18n.t('welcomeMessage', { userName: 'George' })

// value is 'Hello George'

setPluralizationRule(locale, rule, options) #

The setPluralizationRule() method sets a locale-specific pluralization rule function to determine plural form variation index.

i18n.setPluralizationRule('en', function (count) {
    return (1 === count) ? 0 : 1
}, { pluralizeTo: 'count' })

whenUndefined(key, locale) #

The whenUndefined() method defines a custom handler for when the requested item is not available.

i18n.whenUndefined = function (key, locale) {
    return `${key}:undefined:${locale}`
}

const value = i18n.t('errors.dateInput')

// value is 'errors.dateInput:undefined:es'

clear() #

The clear() method empties the instance of messages.

i18n.clear()