gomoob / i18n Goto Github PK

Their is an issue to manage PO files here airbnb/polyglot.js#30.

With the implementation of #4 we could be able to add a custom PO parser, the following implementations could be useful :

• https://github.com/andris9/gettext-parser for example, this one will only work with NodeJS and not in the browser ;
• https://github.com/rubenv/pofile, this one works in the browser, but perhaps it could be useful to parse MO files on browser (don't knwo how to do this for now).

For now the load method returns nothing, it could be great if this method returned an ES6 promise to allow subsequent calls.

Add an el option transmitted to the constructor or the load method.

This would allow to pull translations from a DOM node, this technic is useful to speeup first page display.

If the el option is transmitted to the constructor then the locale, phrases, type and version options must not be provided.

The el option takes a CSS selector to select one to node which must have the following parameters :

• data-locales
• data-phrases
• data-type
• data-version (optional)

HTML sample

<div id="i18n" 
     data-locale="en" 
     data-phrases='{"hello" : "Hello you !", "please-login" : "Please login with your project X account."}' 
     data-type="public"></div>

Polyglot instance

var polyglot = new Polyglot(
    el : '#i18n',
    urlBuilder : function(type, locale, version) {
        ...
    }
);

polyglot.t('hello'); // Hello you !

For now the library cache translations using a plain Javascript object (i.e in memory), it works but it can be problematic with large translation files.

We could add a cache option transmitted to the Polyglot constructor. If this cache option is a string it allows to use a pre-defined cacheManager, if this cache option is a function it defined a custom cacheManager.

Pre-defined cache managers could be :

• MEMORY : Cache translations using a plain Javascript object
• LOCAL_STORAGE : Cache translations using the Local Storage
• SESSION_STORAGE : Cache translations using the Session Storage
• INDEXED_DB : Cache translations using IndexedDb
• WEB_SQL : Cache translations using Web SQL

Each pre-defined cache manager could also be configured using a Javascript object, for example.

var polyglot = new Polyglot(
    {
        cache : {
            type : 'LOCAL_STORAGE', 
            params : {
                key : 'myproject.i18n'
            }
        }
    }
);

Sample custom cache manager

var polyglot = new Polyglot(
    {
        cache : function(type, locale, version, data) {
            ...
        }
    }
);

For now the load method automatically reconfigures the Polyglot instance with the retrieved translations.

In some cases we do not want to do this and only want to pull the translations to put them into the translations cache.

We could add a reconfigure option with a default value equal to false to do this. For example at application starting this could be useful to preload several translation files.

For now the library only support JSON string to specify translations, for example :

{
    "key1" : "Translation for key 1",
    "key2" : "Translation for key 2"
}

It could be great if translation specified in other formats could be loaded, to do this the library could provided an additionnal parser option.

For example if translations are stored using a Base 64 encoded JSON string we could define the following custom parser.

Previous translations encoded using Base 64.

ew0KICAgICJrZXkxIiA6ICJUcmFuc2xhdGlvbiBmb3Iga2V5IDEiLA0KICAgICJrZXkyIiA6ICJUcmFuc2xhdGlvbiBmb3Iga2V5IDIiDQp9

Parsing this Base 64 string.

var polyglot = new Polyglot(
    {
        parser : function(from, data) {
            return JSON.parse(atob(data));
        }
    }
);

The parser method takes 2 parameters :

• from : Parameter which can take 2 values for the moment DOM_NODE or HTTP, it indicates if the translation string comes from a DOM node or an HTTP request. This can be useful if we want to use different formats for translations stored in DOM nodes and pulled from HTTP.
• data : The data to parse

The parser method must return an object which corresponds to the Polyglot phrases.

Terminate the documentation

• urlBuilder option
• forceReload option
• locale option
• type option
• version option
• constuctor(options) method
• cache(type, locale, version, phrases) method
• type(newType) method
• Best practices - Use a Polyglot singleton
• Best practices - Speedup first time display
• Best practices - Translation files versionning
• Best practices - Caching large translation files
• Best practices - Using common translation files in several projects
• Best practices - Create JSON translation files with Gulp and Browserify
• Best practices - Embed translation in a DOM node with Gulp and Preprocess
• Best practices - Expose the t method to templates

Additional feature not implemented for now :

• reconfigure option transmitted to the load method, this would allow to pull and cache translations without re-configuring the Polyglot instance
• el option transmitted to the constructor or the load method, this would allow to pull translation from a DOM node, this technic is useful to speeup first page display
• parser option transmitted to the constructor, this would allow to configure to read translations pulled from a DOM node or from AJAX HTTP requests
• cache option transmitted to the constructor, this option could take pre-defined strings to use pre-configured cache managers. If the option is a method its considered to be a custom cache manager.