It's a smart way of providing support to multiple languages without having to rely on many HTML files, it will also not require a page reload to change languages. The original requirement for creating this script was to provide multilingual support to a CMS in which I only had control to its template code (in my case it was a Shopify store) but the script is very flexible and can be used in any HTML page.
Features: UMD definition, IE9+ support, examples provided.
Just add the script in your HTML file, then invoke the
domI18n method defining the languages you will support:
Mark what elements should be translatable within your page by adding a
Two simple ways to specify translations
Both methods can be used at the same time in an HTML page, just make sure that you don't mix them within the same element.
Using child elements
Inside your translatable element, define one child element for each language you support, in the same order as they appear in the
Hello worldBonjour le monde
This is the most flexible way of defining translations and it allows for the use of nested child elements! If you need to support translated links, this is the only possible choice
Using string separators
Just provide both language values separated by
// - note that this is the standard value and can be changed on the initialization options that we are going to cover in more detail below.
Hello world // Bonjour le monde
This is the most simple way to define translations and is very useful if you're limited to a CMS interface.
The script is highly configurable, many options are available when invoking the
domI18n method that allows the customization of your multi language support.
Here is the complete list of properties you can set on startup and their default values:
- rootElement:HtmlElement - Container element used to narrow the lookup for translatable elements, can be used to define more restricted translatable areas on your page, defaults to
- selector:string | array-like object - Defines which objects have multilingual support, can be a query selector string or an array like object, such as a jQuery selector. Defaults to a
'[data-translatable]'query selector string.
- separator:string - A string that will be used to separate the different languages on your element, defaults to
' // '.
- languages:array - The main source to define what languages the translation should support, please note that the languages should be listed on the same order as they appear here. Defaults to a
- defaultLanguage:string - Defines a default language to be used in the application. Should be a string reference to one of the languages defined on the
languagesarray. Defaults to
- currentLanguage:string - Defines the language to be used when starting the transation script, defaults to
- translatableAttr:string - Reference to a dataset attribute name that points to an element text attribute that should be tranlsated, useful when you want to translate attributes such as
altor similar. Defaults to
Below is an example of initializing
domI18n with the most common used options:
Hello world // Bonjour le mondeThe quick brown fox jumps over the lazy dog. // Le rapide renard marron saute par-dessus le chien paresseux.
domI18n method also returns an object providing a
changeLanguage method to change the language on the fly. That can be very useful for setting up a language selection interface.
var i18n = window;i18n;
MIT © Ruy Adorno