agevio.js v0.7.13

Agevio.js - Let's get your product speak the language of the customer!

A translation library for browser, CommonJS and AMD.

Features:

• Translation
• Interpolation

Example Usage

Agevio.js is friendly to any execution environment: it can work as CommonJS and AMD module or a just script included on a web page, it support Node.js, any modern browser (also IE8+ browsers), it plays well with WebPack, Browserify and ES2015 modules loaders as such as jspm.io.

CommonJS

Just npm install --save agevio.js and use it as CommonJS module in Node.js or with WebPack, Browserify or with any other compatible bundler.

Note: if exports or module are defined library will export itself as CommonJS module.

Examples:

var t = require('agevio.js');

// Initializes library. It will download latests translation files using
// the project key. You can create your own translations using
// web application at https://agevio.com
t.initialize({key: 'yjUQVeTWQOefZhPMydEfVQ'});

// Once translation file downloaded,
// the library will emit `initialized` event.
t.on('initialized', function() {
    // set current locale to Spanish
    t.setLocale('es');

    // translate string by key 'hello.world',
    // the second argument is default translation.
    console.log(t('hello.world', 'Hello World!'));
});

or if you using ES2015:

import t from 'agevio.js';

// Initializes library. It will download latests translation files using
// the project key. You can create your own translations using
// web application at https://agevio.com
t.initialize({key: 'yjUQVeTWQOefZhPMydEfVQ'});

// Once translation file downloaded,
// the library will emit `initialized` event.
t.on('initialized', () => {
    // set current locale to Spanish
    t.setLocale('es');

    // translate string by key 'hello.world',
    // the second argument is default translation.
    console.log(t('hello.world', 'Hello World!'));
});

AMD

You can bundle the script from https://agevio.com/js/agevio.js with you source code or fetch it using npm - requirejs support both way.

Note: if function define is defined and it has got amd property (i.e. typeof define === 'function' && define.amd) then Agevio.js will export itself as AMD module.

Example:

var t = require('agevio.js');

// Initializes library. It will download latests
// translation files using the project key.
// You can create your own translations using
// web application at https://agevio.com
t.initialize({key: 'yjUQVeTWQOefZhPMydEfVQ'});

// Once translation file downloaded,
// the library will emit `initialized` event.
t.on('initialized', () => {
    // set current locale to Spanish
    t.setLocale('es');

    // translate string by key 'hello.world',
    // the second argument is default translation.
    console.log(t('hello.world', 'Hello World!'));
});

Browser

Note: if library can't detect CommonJS or AMD will export itself through window object.

Example:

<!-- require Agevio.js library -->
<script src="https://agevio.com/js/agevio.js"></script>

// Initializes library. It will download latests translation files using
// the project key. You can create your own translations using
// web application at https://agevio.com
t.initialize({key: 'yjUQVeTWQOefZhPMydEfVQ'});

// Once translation file downloaded,
// the library will emit `initialized` event.
t.on('initialized', function() {
    // set current locale to Spanish
    t.setLocale('es');

    // translate string by key 'hello.world',
    // the second argument is default translation.
    console.log(t('hello.world', 'Hello World!'));
});

t.noConflict()

By default Agevio.js uses t as shourtcut. If you're using another JavaScript library that uses the t variable, you can run into conflicts with Agevio.js. In order to avoid these conflicts, you need to put Agevio.js in no-conflict mode immediately after it is loaded onto the page and before you attempt to use Agevio.js in your page.

Example:

var translate = t.noConflict();

// the `t` will revert back to its meaning in original library

Demo

https://github.com/agevio/agevio-react-demo - Demonstrates how to integrate Agevio with React library.

API

t.initialize(options)

Options:

• key - a project public key used to find translations. String, required
• defaultLocale - default locale code. String (default is 'en')
• fallbackLocale - fallback locale code. String (default is 'en')
• shouldWarn - if it turns on - the library will use console.warn to inform about different situations. Boolean (default is true)
• drawWidget - will draw language select widget on a page. Boolean (default is true)
• widgetLocation - specifies the location of the widget on a page. String, can be 'left' or 'right' (default is 'left')
• widgetTheme - specifies the color theme of the widget. String, can be 'dark' or 'light' (default is 'dark')
• widgetTranslatePage - scans whole web page and translates it regarding Agevio.js' markup. Boolean (default is true)

Example:

t.initialize({
    key: 'yjUQVeTWQOefZhPMydEfVQ',
    defaultLocale: 'fr',
    shouldWarn: true
});

t(key, defaultMessage = '', params = {})

That function expects a key, a defaultMessage and and params. It translates and interpolates a given key using a given locale and fallback, as well as interpolation values.

Example:

t.setLocale('fr');

t('hello.world', 'Hello World!'); // => 'Bonjour le monde!'

t('format.array.simple', 'Hello #{0}!', ['buddy']); // => 'Bonjour buddy!'

t('format.object.simple', 'Hello #{name}!', {name: 'esse'}); // => 'Bonjour esse!'

t.setLocale('es');

t('hello.world', 'Hello World!'); // => 'Hola Mundo!'

t('format.array.simple', 'Hello #{0}!', ['buddy']); // => 'Hola buddy!'

t('format.object.simple', 'Hello #{name}!', {name: 'esse'}); // => 'Hola esse!'

t.new()

t is the singleton. You can require it from different modules and places and every time it will be same. It is convenient because you don't need to initialize or configure it whenever it was imported. But if you need a new instance of t you should use t.new() - it returns fresh new function, which you must initialize first before use.

Example:

var translate = t.new();

t === t; // => true
translate === t; // => false

t.getLocale(language = undefined)

Returns current locale code. If language argument is string - lookups for that language's locale code.

Example:

t.getLocale(); // => 'en'

t.getLocale('Spanish'); // => 'es'

t.setLocale(locale)

Changes current locale to locale.

Example:

t.setLocale('es');

t.getLocale(); // => 'es'
t.getLanguage(); // => 'Spanish'

t.getLocales()

Returns a list of defined in translation file.

Example:

t.getLocales(); // => ['en', 'es', 'fr']

t.getFallback()

Returns fallback locale code.

Example:

t.getFallback(); // => 'en'

t.setFallback(locale)

Changes current fallback language.

Example:

t.setFallback('es);

t.getFallback(); // => 'Spanish'

t.getLanguage(locale)

Returns current language name. If locale argument is string - lookups for that locale's language name.

Example:

t.getLanguage(); // => 'English'

t.getLanguage('fr'); // => 'French'

t.setLanguage(language)

Changes current language (and locale) to language.

Example:

t.setLanguage('French');

t.getLocale(); // => 'fr'
t.getLanguage(); // => 'French'

t.getLanguages()

Returns a list of languages defined in translation files.

Example:

t.getLocales(); // => ['English', 'Spanish', 'French']

t.drawWidget()

Draws language selection widget on a page.

Example:

t.drawWidget();

t.removeWidget()

Remove the widget from a page.

Example:

t.removeWidget();

t.translatePage()

It scans web page and translates it regarding Agevio.js markup.

Example:

t.translatePage();

t.on(type, listener)

Add listener for type.

type can be one of:

• initialized
• localeChanged
• fallbackChanged

Example:

t.on('localeChanged', function(locale) {
    console.log('localeChanged', locale);
});

t.setLocale('fr');

// will print in console:
//  localeChanged fr

t.remove(type, listener)

Removes event listener for type. If listener is undefined - removes all listeners for type.

Example:

var a = function(fallback) {
    throw new TypeError(fallback);
};

var b = function(fallback) {
    console.log('fallbackChanged', locale);
};

t.on('fallbackChanged', a);
t.on('fallbackChanged', b);

t.remove('fallbackChanged', a);

t.setFallback('es');

// will print in cosole:
// fallbackChanged es

// it won't raise any exception -
// event listener `a` was removed.

t.remove('fallbackChanged');

t.setFallback('es');

// won't print anything on console -
// all event listeners for `fallbackChanged` event
// were removed.

t.emit(type, ...args)

Emits event type with any number of arguments.

Example:

t.emit('localeChanged', 'es', 'and', 'more');