multilang

An offline capable local - JS only - multilanguage setup for static HTML pages.

Plain HTML/JS Internationalization using R.js

multilang is a library-wrapper implementation demonstrating the R.js lib written by Keith Cirkel.

I began this project as R.js-evaluation to be used for client side internationalization within static HTML pages. I did this, to learn how to use and handle the R.js lib, with the vision in mind to integrate it later on into an existing project of mine. It finally grew to some kind of interface (API/Wrapper) around R.js.

The main purpose of multilang is to generate translations as easy and separted from the rest of the webpage as possible. Steps for adding new languages are intuitive and almost automized. One time setup and easy maintenance are major aims. The initialization uses a prefined default language, while providing the users an ability to switch languages on demand. The users selected language is always backed up in the browsers local storrage for further usage - page reload.

This demo code is published with gh-pages. Check it out here: http://mxklb.github.io/multilang/.

Initial Setup - How to use it

To use multilang in your own project all you need is the content of multilang's tr/ folder and R.js itself (multilang depends on R.js). If you experience compatibility issues with some actual versions of R.js try using my fork of it - therefore simple checkout multilang's submodule rjs.

Follow these steps to initially setup multilang:

• Make sure to load R.js within your HTML document first and afterwards load multilang.js

    <script type="text/javascript" src="rjs/R.js"></script>
    <script type="text/javascript" src="tr/multilang.js"></script>

• Set class="multilang" attribute and a unique id=".." for each HTML element to translate

    <div class="multilang" id="fancy">initial text</div>
    <div class="multilang" id="number">text with num 7.5</div>

• Add an empty <select> to let multilang autogenerate language select options ux

    <select id="selectLanguage" onChange="selectedLanguageChanged();"></select>

• Trigger multilang's initialisation method initLanguages() in your onload function

    window.onload = function() { initLanguages(); }

Now make sure to register translations for all elements with the class="multilang" attribute ...

Register Translations - Adding languages

Single translations are defined within single js files for best abstraction purpose. For each language generate one js file with UTF8 character encoding.

• Register translations for each class="multilang" element id's

    // English translation -> en_GB.js 
    R.registerLocale('en-GB',
    {
      'fancy': "translated text",
      'number': "text with num %i"
    });

    // German translation -> de_DE.js 
    R.registerLocale('de-DE',
    {
      'fancy': "übersetzter text",
      'number': "text mit nr %i"
    });

• Define a name for each language (viewed as <select> option)

    // Language names -> langdef.js
    R.registerLocale('langs',
    { 
      'en-GB': "English",
      'de-DE': "German"
    });    

• Define which js translation-files shall be loaded

    // Setup languages -> multilang.js
    var langfiles = ['en_GB', 'de_DE'];

Note: As best practice make sure to use standard POSIX locale names for new translation file names. For example execute locale -a in a shell to get locale names of your system. Make although sure to use underscore _ in filenames while minus sign - for R.js language registration id's.

Default Setup - Configuration

The initial setup section within multilang.js provides some configuration controls for multilang. The initial default language, R.js' advanced string formating (asf) and some other configurations can be controlled ...

• The default language is en-GB. To change this edit var defaultlang = 'en-GB'

• The default translation directory is tr/. To change it set var langdirectory = your/dir/

• The default <select id="selectLanguage">. To use an other id set var langSelectId

• Per default the asf-feature of R.js is enanbled. To change it set var asfEnable = false

  If asf is enabled provide a custom.js file within your translation directory and overwrite multilang's translateCustomTexts() function in it. This function will always be executed if the language was changed or updateLanguage() was called. In it you are able to perfom custom translations and special R.js calls. To get an idea view the following custom.js code ..

    // Custom translations -> custom.js
    function translateCustomTexts() {
        // hard coded substitution of innerHTML
        updateTranslation('fancy', 'any fancy string');
        
        // using R.js advanced string formating
        updateTranslation('number', R('number', 7.5));
        
        // simplified for one %i or %s replacement
        updateTranslationParameter('number', 7.5);
    }

custom.js will be loaded automatically as final script during multilang's initialisation initLanguages(). To manually load custom.js at a later point in runtime set var loadCustomjs = false.

License

This code is licensed under MIT. See LICENSE file for further informations about this.

Feel free to play around with the code and/or send some pull requests for further translations or improvements. Arabic, Russian, Chinese, Thai, Greek, e.g. foreign characters would be nice to see ..