i18next-text

Using i18next translations without the need to maintain i18n keys.

It's recommended to use i18next-scanner as a Gulp or Grunt plugin to scan your code, extract translation keys/values, and merge them into i18n resource files.

i18n._('Save your time and work more efficiently.');

Demo

Check out our demo on JSFiddle.

Features

Supports most i18next features.
Provides built-in support for Handlebars i18n helper.
Automatically generates a hash for an i18n text string as its unique key. It is not necessary to manually maintain resource files.
Supports CRC32, MD5, and SHA-1 hash (The default is SHA-1).
You can customize your own hash function by including the i18next-text.custom.js file with only 2KB in size.

Installation

With bower:

bower install i18next-text

With npm:

npm install i18next-text

Initialization

Normally i18next-text can be initialized with options by calling i18nText.init():

// You can omit this step if using default options
i18nText.init({
    debug: true, // default: false
    hash: 'sha1' // default: 'sha1'
});

Then extends i18n object to provide a new _() method:

i18n._ = i18nText._;

Initializes i18next with options:

i18n.init({lng: 'en'});

// later
i18n.t('key');
i18n._('It is no longer needed by specifying the key.');

or initializes i18next with both options and callback:

i18n.init({lng: 'en'}, function(t) {
    i18n.t('key');
    i18n._('It is no longer needed by specifying the key.');
});

Usage

For example, assume that you have the following directory structure:

index.html
vendor/
    i18next.js
    i18next-text.js
i18n/
    en/
        resource.json
    de/
        resource.json

index.html

<!doctype html>
<html class="no-js" lang="">
    <head>
        <meta charset="utf-8">
        <meta http-equiv="x-ua-compatible" content="ie=edge">
    </head>
    <body>
        <script src="vendor/i18next.js"></script>
        <script src="vendor/i18next-text.js"></script>
        <script>
            // See "Browser globals" below for example
        </script>
    </body>
</html>

English resource file (i18n/en/resource.json):

{
    "loading": "Loading...",
    "b04ba49f848624bb97ab094a2631d2ad74913498": "Loading..."
}

German resource file (i18n/de/resource.json):

{
    "loading": "Wird geladen...",
    "b04ba49f848624bb97ab094a2631d2ad74913498": "Wird geladen..."
}

All SHA-1 keys are automatically generated using i18next-scanner. You do not need to maintain resource files.

In Node.js

var i18n = require('i18next');
var i18nText = require('i18next-text');
var options = {
    lng: 'en',
    preload: ['en', 'de'],
    load: 'current',
    fallbackLng: false,
    resGetPath: 'i18n/__lng__/__ns__.json',
    ns: {
        namespaces: [
            'resource' // default
        ],
        defaultNs: 'resource'
    }
};

// extends i18n object to provide a new _() method
i18n._ = i18nText._;

i18n.init(options, function() {
    i18n.t('loading'); // will return "Loading..."
    i18n._('Loading...', {lng: 'de'}); // will return "Wird geladen..."
});

Browser globals

(function(root) {
    var i18n = root.i18n;
    var i18nText = root.i18nText;
    var options = {
        lng: 'en',
        preload: ['en', 'de'],
        load: 'current',
        fallbackLng: false,
        resGetPath: 'i18n/__lng__/__ns__.json',
        ns: {
            namespaces: [
                'resource' // default
            ],
            defaultNs: 'resource'
        }
    };

    // extends i18n object to provide a new _() method
    i18n._ = i18nText._;

    i18n.init(options, function() {
        i18n.t('loading'); // will return "Loading..."
        i18n._('Loading...', {lng: 'de'}); // will return "Wird geladen..."
    });
}(this));

Translation features

i18next-text supports most i18next features, for example:

Access value in different language:

i18n._('Loading...', {lng: 'de'}); // will get value in de instead of en

Replacing variables:

i18n._('YouTube has more than __count__ billion users.', {count: 1});

Visit http://i18next.com/pages/doc_features.html to see more examples.

Advanced Usage

Gets the hashed key with a given string

You can call the key() function to get the hashed key with a given string:

var i18nText = require('i18next-text');
i18nText.key('Loading...'); // will return a hash string

Checks if a string exists

var i18nText = require('i18next-text');
i18nText.exists('Loading...'); // will return a boolean value

Locates missing translation

var strNotTranslated = '<span class="highlight error">STRING_NOT_TRANSLATED</span>';
i18n._('YouTube has more than one billion users each month.', {
    lng: 'de',
    defaultValue: strNotTranslated
});

It will produce the following output if above string is not available in de translation:

<span class="highlight error">STRING_NOT_TRANSLATED</span>

You can see a demo here.

Providing a default key

You can explicitly specify a default key of a text string by passing a defaultKey option:

i18n._('Loading...', {defaultKey: 'loading'});
i18n._('Loading...', {defaultKey: 'b04ba49f848624bb97ab094a2631d2ad74913498'});

Note. Missing resources can be sent to server by turning on i18next's sendMissing option like below:

i18n.init({sendMissing: true});

Custom hash function

You can customize your own hash function by including the i18next-text.custom.js file, which is only 2KB in size:

<script src="vendor/i18next.js"></script>
<script src="vendor/i18next-text.custom.js"></script>

In your initialization script, change hash on i18nText.init() to apply a custom hash function:

i18nText.init({
    hash: function(str) {
        return customHashFunction(str);
    }
});

Template & Helpers

Handlebars i18n helper

i18next-text provides built-in support for Handlebars helper. You can register the i18n helper for use in templates.

Register helper

Use the Handlebars.registerHelper method to register the i18n helper:

var i18nText = require('i18next-text');
var handlebars = require('handlebars');

handlebars.registerHelper('i18n', i18nText.handlebarsHelper);

By default, Handlebars will escape the returned result by default. If you want to generate HTML, you have to return a new Handlebars.SafeString(result) like so:

var i18nText = require('i18next-text');
var handlebars = require('handlebars');

handlebars.registerHelper('i18n', function() {
    var result = i18nText.handlebarsHelper.apply(this, arguments);
    return new handlebars.SafeString(result);
});

In such a circumstance, you will want to manually escape parameters.

Usage

Here is an example of what our template file might look like:

{{i18n 'Basic Example'}}
{{i18n '__first-name__ __last-name__' first-name=firstname last-name=lastname}}
{{i18n 'English' defaultKey='locale:language.en-US'}}
{{i18n defaultKey='loading'}}
{{#i18n}}Some text{{/i18n}}
{{#i18n this}}Description: {{description}}{{/i18n}}
{{#i18n this last-name=lastname}}{{firstname}} __last-name__{{/i18n}}

You can compile the template string into a Handlebars template function, and then render the template by passing a data object (a.k.a. context) into that function:

var source = fs.readFileSync('./handlebars-helper-i18n.hbs'), 'utf-8');
var template = handlebars.compile(source);
var context = {
    'firstname':'Foo',
    'lastname':'Bar',
    'description': 'Foo Bar Test'
};
console.log(template(context));

You will see console output like so:

Basic Example
Foo Bar
English
Loading...
Some text
Description: Foo Bar Test
Foo Bar

You can see a demo here.

License

Licensed under the MIT License.

I18next-text

Using i18next translations without having the "key" as strings

i18next-text

Demo

Features

Installation

Initialization

Usage

In Node.js

Browser globals

Translation features

Advanced Usage

Gets the hashed key with a given string

Checks if a string exists

Locates missing translation

Providing a default key

Custom hash function

Template & Helpers

Handlebars i18n helper

Register helper

Usage

License