Multilingual support

Setting the editor to use another language

First check the translations folder at the root of the project to see if the language you require is available (we're going to pretend it is for now and cover creating your own translations later). Each supported language is named after its 2 character ISO 639-1 code, for example the French translations would be in the file named fr.json.

At the time of writing the only translation available is pig latin (lp.json) - apollacray! However a number of people have kindly volunteered to provide translations for other languages so hopefully it won't take all that long before there are more available.

Languages have to be added to the ContentEdit namespace. This is done using the ContentTools.addTranslations(language, translations) function. The function expects a 2 character language code and an object mapping English strings to their translated counterparts. Our translations are held in a JSON file (e.g fr.json) and so we'll need to load them via an XMLHttpRequest like so:

var editor, xhr;

// Get the editor
editor = new ContentTools.EditorApp.get();

// Define our request for the French translation file
xhr = new XMLHttpRequest();
xhr.open('GET', '/translations/fr.json', true);

function onStateChange (ev) {
    var translations;
    if (ev.target.readyState == 4) {
        // Convert the JSON data to a native Object
        translations = JSON.parse(ev.target.responseText);
        
        // Add the translations for the French language
        ContentEdit.addTranslations('fr', translations);

        // Set French as the editors current language
        ContentEdit.LANGUAGE = 'fr';
    }
}

xhr.addEventListener('readystatechange', onStateChange);

// Load the language
xhr.send(null);

Notice that we set the value of ContentEdit.LANGUAGE to 'fr', this changes the language for the editor. If there's no matching translation then the editor will fall back to returning the default English versions of strings.

You could of course add the translations directly without loading a JSON file and if you're working locally you may want to do this as browsers won't allow an XMLHttpRequest to load local files (e.g using the file:// protocol).

Rolling your own translations

You may find that the language you want isn't yet supported (in fact right now you can be pretty sure of it), fortunately creating your own language file is straightforward (well provided you speak English and the language you want to translate to).

I recommend using an existing language file from the translations folder in the project root as a basis for your new file and simply replacing the translations. Once you've finished save your new language file using the relevant 2 character ISO 639-1 code.

Using translations in your own code

If you want to translate content in your own code then you need to wrap the string you want to translate with ContentEdit._(string), for example:

@_domInput.setAttribute(
    'placeholder', 
    ContentEdit._('Enter a date/time/duration') + '...'
    );

You'll also need to add a translation to the language files:

>> lp.json

{
    ...
    "Enter a date/time/duration": "Enterway away ateday/imetay/urationday"
}

If you want to add dynamic content within a translated string then you can either break it down and add the pieces together, or preferably use a simple replace mechanism:

// Breaking down a translation for dynamic content
var welcome = ContentEdit._('Hello ') + user.firstName + ContentEdit._(', welcome back.');

// Using replace (preferred option)
var welcome = ContentEditor._('Hello #name#, welcome back.');
welcome = welcome.replace('#name#', user.firstName);

One last piece of advice; translate at the point you add content to the DOM. Storing the translated value of a string will mean the initial value cannot be easily retrieved, so for example:

// Avoid doing this
this._caption = ContentEdit._('Properties');
@_domCaption.textContent = this._caption;

// Instead do this
this._caption = 'Properties';
@_domCaption.textContent = ContentEdit._(this._caption);

Au revoir.