I18n easy

version: 0.1.6

I18n easy provide a simple way to add i18n feature to your meteor app.

When adding translation, one can set the plural version as well. For translation without plural, an "s" is added to the singular version when plural is requested.

It is possible to group translations by sections: indeed each route can have his own translation, thus reducing the amount of records sent to client via publications. Section translations overwrite global ones – thoses not attached to any section.

Setup

Setting default language

First you need to set the default language both server side and client side, for instance in a file placed under the /lib directory of your meteor app

I18nEasy.setDefault('en');

Adding translations

Then add translations server side:

I18nEasy.mapAll({
	en: {
		home: "home",
		setting: "setting",
		greetings: "grettings {{name}}!",
		
		// singular and plural
		summary: ["summary","summaries"],
		
		// Client section
		clients: {
			name: "name",
			company: "company"
		}						
	},
	
	fr: {
		home: "acceuil",
		setting: "préférences",
		summary: "sommaire",
		greetings: "salutations {{name}}!",
		
		// Client section
		clients: {
			name: "nom",
			company: "société"
		}
	}
});

note: {{placeholders}} cannot have the following names: fallBack, autoPlural, useDefault or section

Setting publications and subscriptions

Finally setup publications and subscriptions

Server side

I18nEasy.publish();

Client side

I18nEasy.subscribe();

To limit publications to a list of sections

I18nEasy.subscribe({sections: ["section1", "section2"]});

This will tell I18n easy to load only translations pertaining solely to the given sections and those not attached to any section – global ones. If no section is provided, only global ones will be loaded.

note: When the subscribe API is used, only the following translations are published:

those in the selected language and not attached to any section;
those pertaining to the sections parameter;
those in the default language which are missing from the selected language

Setting current language

Every time language switch is necessary – client side most of the time – use the following api:

// Switching to french
I18nEasy.setLanguage('fr');

Security

To prevent unauthorized updates of translations, you should setup permissions — server side and client side — like this

I18nEasy.allowWrite(function(){
	return false;
});

note: This is used by I18n easy admin to restrict access to the admin UI. For example true could be returned only if user is authenticated.

Usage

Use the i18n helper to access translations within templates

{{i18n 'summary'}} // -> display "summary" according to previously added translations
{{i18n 'greetings' name='Sebastian'}} // -> display "grettings Sebastian!" according to previously added translations

To request plural translation, just add an "s" to the key or the helper

{{i18n 'summarys'}} // -> display "summaries" according to previously added translations
{{i18ns 'summary'}} // -> display "summaries" according to previously added translations

iron-router integration

Ease your setup

If you use iron-router, here is the better way to subscribe to translations

…

waitOn: function(){
	return I18nEasy.subscribe();
},

…

The easiest way to switch language is to add an optional language parameter to every routes and add a before hook that use the I18nEasy.setLanguage(<language parameter>) api to actually switch language

…

function navigatorLanguage(){
	var results = /(\w{2}).*/gi.exec(window.navigator.language);
	return results.length > 1 && results[1];
}

Router.before(function(){
	var language = this.params.language || navigatorLanguage();

	if(language && I18nEasy.getLanguage() !== language){
		I18nEasy.setLanguage(language);
	}
});

…

Router.map(function(){

	this.route('invoices', {
		path: '/:language?/invoices'
	});

	…

});

When no section is provided to I18nEasy.subscribe(), the current route name is used as section paramater. Therefore it is a good practice to put translations needed solely on a specific route under a section matching this route name: it will reduce the amount of records sent to the client, thus improve your app performances.

pathToLanguage helper

Finally, I18n easy comes with the handy helper pathToLanguage <language> which gives you the path to the current route translated to the given language. It is usefull to display navigations for languages switching.

footer.html

{{#each languages}}
<li class="{{activeLanguageClass this}}">
	<a href="{{pathToLanguage this}}">{{i18n this}}</a>
</li>
{{/each}}

footer.js

Template.footer.helpers({
	activeLanguageClass: function(language){
		if(language === I18nEasy.getLanguage()){
			return 'active';
		}else{
			return undefined;
		}	
	},
	
	languages: function(){return I18nEasy.getLanguages();}
});