fast-translation

A performant module for handling translations.

Installation

npm install fast-translation

Example

const { Translator } = require('fast-translation');

const translator = new Translator();
translator.addRule('en-US', [1, 2], (count) => count !== 1 ? 0 : 1);
translator.addTranslations({
  test: {
    key: '__count__ bird'
    key_plural_2: '__count__ birds'
  }
}, 'en-US', 'default');
await translator.initialize();
translator.translate('test.key', { language: 'en-US' }); // 1 bird
translator.translate('test.key', { language: 'en-US', count: 2 }); // 2 birds
translator.translate('test.key', { language: 'en-US', namespace: 'default' }); // 1 bird

Interpolation

Interpolation allows to insert values into the translations:

translator.addTranslations({
  birds: 'a __color__ bird'
}, 'en-US', 'default');
await translator.initialize();
translator.translate('birds', { language: 'en-US', color: 'blue' }) // a blue bird

Keys

There are three possible types of keys:

Keys representing the singular: key
Keys representing first plural: key_plural
Keys representing any plural (using the plurals specified with addRule): key_plural_3

API

Translator(options)

options

preloadLanguages (optional)

Array of languages to be loaded with sources.

preloadNamespaces (optional)

Array of namespaces to be loaded with sources.

reloadInterval (optional)

A number in milliseconds that defines the interval to reload the translations.

logger (optional)

If set it will log errors during reload using the provided logger. Needs at least an error() function.

Translator#use(source)

Adds a source for translations. There are two kind of sources being provided:

const { FileSource, HttpSource } = require('fast-translation');
const httpSource = new HttpSource({
  url: `http://localhost:${port}/locales/__language__/__namespace__`
});
const fileSource = new FileSource({
  filePath: __dirname + `/locales/__language__-__namespace__.json`
});
translator.use(httpSource);
translator.use(fileSource);

Translator#initialize()

Initializes the translator. Returns a Promise.

Translator#translate(key, options)

Translates the provided key using the provided options. All placeholders will be replaced by the values provided with the options.

translator.translate('a.key', { language: 'en' })

The process of finding a translation works as follows (assuming the key is known):

Determine the count: Either options.count or 1.
Determine the plural: Call the rule function for the language with the count.
Determine the namespace: Either options.namespace or default.
Build an identifier from the key, language, plural and namespace.
Use the identifier to find a translation function, execute it with the options and return the result.

Note: If translate() is being called with an unknown key the key will be returned.

options#language

The language that will be used to translate the key will be translated to.

options#namespace (optional)

The namespace that will be used to translate the key. Defaults to default.

options#count (optional)

A number used to determine the plural for the key. Defaults to 1.

Translator#addRule(language, plurals, rule)

Adds a plural rule function for a language along with an array of plurals that will be used to determine the correct plural.

translator.addRule('de-DE', [1, 2], (count) => count !== 1 ? 0 : 1)

Translator#addTranslations(translations, language, [namespace])

If no namespace is being passed it defaults to default. The translations may contain placeholders like __placeholder__.

For each key a function is being created and stored internally, that handles translation and interpolation for that key.

Translator#reload([handler])

Reloads the translations using the sources. Allows to pass a handler function that will be called if an error occurs.

Benchmark

> node benchmark/benchmark.js

i18next x 225,728 ops/sec ±1.10% (84 runs sampled)
fast-translation x 5,130,229 ops/sec ±0.59% (90 runs sampled)
Fastest is fast-translation

License

MIT

An in-range update of i18next is breaking the build 🚨

The devDependency i18next was updated from `11.9.1` to `11.10.0`.

🚨 View failing branch.

This version is covered by your current version range and after updating it in your project the build failed.

i18next is a devDependency of this project. It might not break your production code or affect downstream projects, but probably breaks your build or test tools, which may prevent deploying or publishing.

Status Details

❌ continuous-integration/travis-ci/push: The Travis CI build failed (Details).

Commits

The new version differs by 3 commits.

3e2d066 build new version
9743e7a Merge pull request #1118 from mogelbrod/master
1fc55ff Allow missingInterpolationHandler to be provided as t() option

See the full diff

FAQ and help

There is a collection of frequently asked questions. If those don’t help, you can always ask the humans behind Greenkeeper.

Your Greenkeeper Bot 🌴

serayaeryn / fast-translation Goto Github PK