piral-translate

Piral Translate ·

This is a plugin that only has a peer dependency to piral-core. What piral-translate brings to the table is a set of Pilet API extensions that is used by piral. The set features a simple yet sufficient translation system.

Documentation

The following functions are brought to the Pilet API.

translate()

Returns the translation (i.e., a string defined for the currently selected language) of a provided language key.

Variables can also be provided using an object as the second argument. The variable replacement looks for occurrences of double curly braces, e.g., {{foo}}.

setTranslations()

Sets the translations (custom language to key to string mapping) for the pilet.

getTranslations()

Gets the translations defined in the pilet.

Setup and Bootstrapping

The provided library only brings API extensions for pilets to a Piral instance.

For the setup of the library itself you'll need to import createLocaleApi from the piral-translate package.

import { createLocaleApi } from 'piral-translate';

The integration looks like:

const instance = createInstance({
  // important part
  extendApi: [createLocaleApi()],
  // ...
});

Via the options the available languages, translations, as well as the currently selected language can be chosen.

For example:

const localizer = setupLocalizer({
  language: 'en',
  messages: {
    en: {
      'greeting': 'Hello',
    },
    de: {
      'greeting': 'Hallo',
    },
  },
});

const instance = createInstance({
  // important part
  extendApi: [createLocaleApi(localizer)],
  // ...
});

Alternatively, the current language can also be inferred via a function.

const localizer = setupLocalizer({
  language: getUserLocale,
  messages: {
    en: {
      'greeting': 'Hello',
    },
    de: {
      'greeting': 'Hallo',
    },
  },
});

The function getUserLocale retrieves either the cookie with name _culture or local storage value for key locale. In any case either the first found language or ultimately en is used as a fallback.

License

Piral is released using the MIT license. For more information see the license file.