Livi18n

Internationalisation (i18n) for backend and frontend node.js

Instalation

Install from command line

npm install livi18n

Install from package.json

"dependencies": {
  "livi18n": "~0.3.0"
}

Run this command to install

npm install

Getting Started

var livi18n = require('livi18n');
 
//Initialize Settings
app.use(livi18n.init(app, {
  defaultLanguage: 'en',
  languages: ['en'],
  path: __dirname + '/lang',
  socket: true,
  serveClient: true
}));
//The Livi18n can only be used before the `app.route`
app.use(app.router);

Documentation

.init(app, options, cb)

Parameter: app Type: express app Example: var app = express();

Parameter: options Type: JSON Object

Example:

{
  defaultLanguage: 'en',
  languages: ['en'],
  storageKey: 'lang',
  cookie: true,
  cookieSettings: {},
  socket: true,
  serveClient: true,
  path: __dirname + '/lang',
}

Parameter: cb Type: Function Example: function(){};

How to use init method

// So the middleware init call should look like:
app.use(livi18n.init(app, {
  defaultLanguage: 'en',
  languages: ['en'],
  storageKey: 'lang',
  cookie: true,
  cookieSettings: {},
  socket: true,
  serveClient: true,
  path: __dirname + '/lang'
}));

It is necessary to define the default language and the path where livi18n finds the i18n resource files.

Available options:

defaultLanguage: Define default system language (String)

languages: Define available languages for use in your app (Array)

storageKey: Define cookie and querystring name (String)

cookie: Enable Cookie support for currentLanguage (Boolean)

cookieSettings: Define Cookie settings (JSON Object)

socket: Enable socket support for use in Livi18n

serveClient: Provide clientSide API to use Livi18n on frontend (Boolean)

path: Define path of the language files (String)

.t(data)

Parameter: data Type: JSON Object Example: {key: '', options: {}, defaultValue: ''};

Provide translate method for use in requests and views

How to use this method

livi18n.t({key: 'languageFilename.path.to.value', options: {}, defaultValue: 'Test'});

key: The first value of the key separated by . is the name of the language file where the message, the second value is the path to the chosen message. Example: {key: 'messages.welcome'} // 'Welcome to Livi18n'

options: The options attribute receives an object with the names of the elements to be changed in the value of the message.

MessageExample: Hi, :name. Example: {name: 'Princess Bella'} // 'Hi, Princess Bella.'

defaultValue: If the chosen message is not found, the value passed in defaultValue will be used as the default value of the message. Example: Test Value // 'Test Value'

.p(data)

Parameter: data Type: JSON Object Example: {key: '', options: {}, value: 14, defaultValue: ''};

Provide pluralize method for use in requests and views

How to use this method

livi18n.p({key: 'languageFilename.path.to.value', options: {}, value: 10, defaultValue: 'Test'});

key: The first value of the key separated by . is the name of the language file where the message, the second value is the path to the chosen message. Example: {key: 'messages.pluralized'} // 'Bella have 4 The Vampire Diaries Books!'

options: The options attribute receives an object with the names of the elements to be changed in the value of the message.

MessageExample: Hi, :name. Example: {name: 'Princess Bella'} // 'Hi, Princess Bella.'

value: The value attribute is a value used in the method to pluralize a chosen message, if the value passed is greater than 1, the first value of the message will be returned, if greater than 1, the second value of the message will be returned and pluralize a chosen message.

MessageExample: :name have :&: The Vampire Diaries Book||:name have :&: The Vampire Diaries Books

Example: livi18n.p({key: 'messages.pluralized', options: {name: 'Bella'}, value: 4}); // 'Bella have 4 The Vampire Diaries Books!'

Info: The :&: is a constant that takes the value that was passed in the method.

Info: The || is the separator that separates the message for be pluralized.

defaultValue: If the chosen message is not found, the value passed in defaultValue will be used as the default value of the message. Example: 'Test Value' // 'Test Value'

.setLanguage(language)

Parameter: language Type: String Example: en

The 'setLanguage' method is responsible for define current language for all requests and response between client and server.

How to use this method

livi18n.setLanguage('en');
// or
app.use(livi18n.setLanguage('en'));
// or
req.setLanguage('en');

.socketManager(io)

Parameter: io Type: socket.io instance Example: var io = require('socket.io').listen(server);

The 'socketManager' method is responsible for managing all requests and response between client and server.

How to use this method

livi18n.socketManager(io);

.socketEnabled()

Return true if socket support is enabled, if not return false

livi18n.socketEnabled();

if(socketEnabled())
    script(src='/socket.io/socket.io.js')

.version()

Return Livi18n version.

livi18n.version();

Examples

Usage examples

Socket Support

Add Livi18n libraries dynamically in example/views/layout.jade

script(src='/javascripts/jquery.min.js')
script(src='/livi18n/livi18n.js')
if(socketEnabled())
    script(src='/socket.io/socket.io.js')
script(src='/javascripts/livi18n_init.js')
script(src='/javascripts/livi18n_test.js')

AddSocketManager in example/app.js

// Create Server
 
var server = app.listen(app.get('port'));
 
// Show Status
 
console.log('Express server listening on port ' + app.get('port'));
 
//Create Socket instance
 
var io = require('socket.io').listen(server);
 
// Require Socket Manager
 
// This method receive a `io` instance and manage socket requests and responses.
 
livi18n.socketManager(io);

Jade Example

#test-translate(data-livi18n='messages.welcome' data-options='{"name": "Princess", "nick": "Bella"}' data-default='Tested')
#test-pluralize(data-livi18n='messages.test2' data-options='{"name": "Princess", "nick": "Bella"}' data-value='10' data-default-value='Tested')

Controller Example

exports.index = function(req, res){
  res.render('index', { title: req.t({key: 'messages.welcome'}) });
};

jQuery Example

$('elem').livi18nT({enableOptions: true});
//
$('elem').livi18nP({enableOptions: true});

See documentation of jQuery integration

AngularJS Example

var demoCtrl = function($scope, $livi18n) {
    $scope.livi18ndemo = $livi18n.t(options);
        // or
    $scope.livi18ndemo = $livi18n.p(options);
};

See documentation of AngularJS integration

Example App

See example application in example

See demo in livi18n.herokuapp.com

JS Version

See documentation Livi18n.js

Contributing

Please submit all issues and pull requests to the chrisenytc/livi18n repository!

Support

If you have any problem or suggestion please open an issue here.

License

Copyright (c) 2013 Christopher EnyTC

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Release History

• 2013-11-18    v0.3.0    Adding support for unique instance of socket.io
• 2013-11-17    v0.2.0    Adding support for new package livi18n-parser
• 2013-11-9    v0.1.1   Fixed error in lib/client/ngSocket.js and update example
• 2013-11-6    v0.1.0   Initial release.