tranzlate

Provides support for parametrized runtime translation in JavaScript.

Usage

Loading Translations

The module itself doesn't contain any keys. It's recommended that they are injected on per-module basis or in the entry point of the application

// my-entry-point.js
import translate from 'tranzlate';
translate.inject({
    'key1': 'translation1',
    'key2': 'translation2 {0}, {1}',
});

If you want to completely replace the translations instead merging in the new ones, you can use replace function:

import translate from 'tranzlate';
translate.replace({
    'key1': 'translation1',
    'key2': 'translation2 {0}, {1}',
});

Translating Messages

Main function exposed by tranzlate tries to lookup a key in a internal storage, using empty string if no translation is found. Then it uses arguments after the first one (if present) for interpolating numbered placeholders.

import translate from 'tranzlate';
translate.inject({ 'title': 'Hello {0}!' });
document.title = translate('title', 'World'); // => 'Hello World!';

If a value is not provided for a particular placeholder, it's resolved to an empty string:

import translate from 'tranzlate';
translate.inject({ 'title': 'Hello {0}!' });
document.title = translate('title'); // => 'Hello !';

Here is full function signature:

/**
 * @param {string} key
 * @param {...(string|number)} replacement_var_args
 * @returns {string}
 */
function translate(key, ...replacement_var_args) {}

Pass Through Mode

During development, manual or automated testing it's often important to see raw keys in the interface rather than translated values, so tranzlate includes a switch to enable this pass through mode

import translate from 'tranzlate';
translate.passThrough = true;
document.title = translate('my.title.key'); // => 'my.title.key';

Raw String Interpolation

This module exposes interpolate method that can be used for cases where you need to use a custom string for interpolation instead of translated message:

import translate from 'tranzlate';
document.title = translate.interpolate('Hello {0}!', ['World']); // => 'Hello World!';

Here is full function signature:

/**
 * @param {string} text
 * @param {Array<string|array>} [replacements=[]]
 * @returns {string}
 */
function interpolate(text, replacements) {}

Local Sandbox

The library also allows you to create a local sandbox of translations to disallow sharing between different parts of the code.

import {createSandbox} from 'tranzlate';

// As an additional convenience you can pass initial
// translations right when creating the sandbox
const translate = createSandbox({
    foo: 'bar'
});
console.log(translate('foo')); // "bar"

License

Copyright 2015 Zalando SE

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.