#About

Translate is an API for doing client-side translations in javascript. It is a fork of jquery-i18n by Dave Perrett, and is licensed under the MIT license.

#Installation

You'll need to download the jQuery library, and include it before cloudkid-translate.min.js in your HTML source.

This library is also available as a bower component under the name cloudkid-translate.

#Usage

##Setup

Before you can do any translation you have to load() the plugin with a dictionary (each language contains a property list mapping keys to their translations).

var translations = {
	"en" : {
		"greeting" : "Welcome",
		"intro" : "My name is %s, I'm %s years old"
	},
	"fr" : {
		"greeting" : "Accueil",
		"intro" : "Je m'appelle %s, je suis âgé de %s ans"
	}
};
Translate.load(translations);

The translations can also be loaded with a path to externalized JSON file.

Translate.load("locale/lang.json", function(){
	// Optional callback when load finished!
});

Or loading a specifc language JSON:

Translate.load("locale/en/lang.json", "en", function(){
	// Optional callback when load finished!
	// The locale is automatically set here to "en"
});

Then you must select the locale to use which can be done one of two ways. Either auto-detect method which identifies the locale based on the current browser's navigator object, or explicitly setting the locale.

// Auto detect based on navigator object
Translate.autoDetect();

// or explicitly set the locale
Translate.locale = "en";

If using autoDetect(), it's a good idea to set a fallback locale, in case the language doesn't exist in your dictionary.

Translate.fallbackLocale = "en";

##Translating

Once you've initialized it with a dictionary, you can translate strings using the _t() function, for example:

$('#example').html(_t('greeting'));

Or using the jQuery plugin $('selector')._t() method"

$('#example')._t('greeting');

Or using the data tag method"

<div data-localize="greeting"></div>

##Wildcards

It's straightforward to pass dynamic data into your translations. First, add %s in the translation for each variable you want to swap in :

var translations = {
	'en' : {
		"wildcard example"  : "We have been passed two values : %s and %s."
	}
};

Next, pass values in sequence after the dictionary key when you perform the translation :

$('#example').html(_t('wildcard example'), 100, 200));

or, again, the jQuery plugin method:

$('#example')._t('wildcard example', 100, 200);

This will output: We have been passed two values: 100 and 200.

If you need to explicitly output the string %s in your translation, use %%s :

var translations = {
	'en' : {
		"wildcard example"  : "I have %s literal %%s character"
	}
};

$('#example')._t('wildcard example', 1);

This will output: I have 1 literal %s character.

Copyright

Copyright (c) 2014 CloudKid Under the MIT License