dom-i18n

by ruyadorno

ruyadorno / dom-i18n

Provides a very basic HTML multilingual support using JavaScript

125 Stars 16 Forks Last release: about 1 year ago (v1.2.0) MIT License 55 Commits 5 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

dom-i18n

NPM version Build Status Code coverage

Provides a very basic HTML multilingual support using JavaScript

http://ruyadorno.github.io/dom-i18n

Sauce Test Status

About

This is a lightweight (less than 1KB minified/gzipped) JavaScript module that offers an alternative for supporting internationalization on HTML static pages that have no better option than to serve many languages at once.

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.

Usage

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

data-translatable
attribute:
  

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

languages
property.
  

Hello world Bonjour 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.

Options

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
    window.document
    .
  • 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
    ['en']
    array.
  • 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
    languages
    array. Defaults to
    'en'
    .
  • currentLanguage:string - Defines the language to be used when starting the transation script, defaults to
    'en'
    .
  • 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
    title
    ,
    alt
    or similar. Defaults to
    'data-translatable-attr'
    .
  • enableLog:boolean - If
    true
    log messages are enabled (e.g. error if language not found). Defaults to
    true
    .

Example:

Below is an example of initializing

domI18n
with the most common used options:
  

Hello world // Bonjour le monde

The quick brown fox jumps over the lazy dog. // Le rapide renard marron saute par-dessus le chien paresseux.

API

The

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.domI18n({
  selector: '[data-translatable]',
  separator: ' // ',
  languages: ['en', 'fr'],
  defaultLanguage: 'en'
});

i18n.changeLanguage('fr');


DISCLAIMER: Please note that this is a hacky way of integrating internationalization support into your application and its use probably only makes sense when you have big limitations, such as having zero control over the server-side code or no JavaScript framework in use.

License

MIT © Ruy Adorno

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.