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;
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(): ```javascript` // 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:
```javascript
i18n._ = i18nText._;
Initializes i18next with options:
i18n; // lateri18n;i18n;
or initializes i18next with both options and callback:
i18n;
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
English resource file (i18n/en/resource.json):
German resource file (i18n/de/resource.json):
All SHA-1 keys are automatically generated using i18next-scanner. You do not need to maintain resource files.
In Node.js
var i18n = ;var 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 _() methodi18n_ = i18nText_; i18n;
Browser globals
{ var i18n = rooti18n; var i18nText = rooti18nText; 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;}this;
Translation features
i18next-text supports most i18next features, for example:
-
Access value in different language:
i18n; // will get value in de instead of en -
Replacing variables:
i18n;
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 = ;i18nText; // will return a hash string
Checks if a string exists
var i18nText = ;i18nText; // will return a boolean value
Locates missing translation
var strNotTranslated = '<span class="highlight error">STRING_NOT_TRANSLATED</span>';i18n;
It will produce the following output if above string is not available in de
translation:
STRING_NOT_TRANSLATED
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;i18n;
Note. Missing resources can be sent to server by turning on i18next's sendMissing option like below:
i18n;
Custom hash function
You can customize your own hash function by including the i18next-text.custom.js file, which is only 2KB in size:
In your initialization script, change hash
on i18nText.init() to apply a custom hash function:
i18nText;
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 = ;var handlebars = ; handlebars;
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 = ;var handlebars = ; handlebars;
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 'utf-8');var template = handlebars;var context = 'firstname':'Foo' 'lastname':'Bar' 'description': 'Foo Bar Test';console;
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
Copyright (c) 2015 Cheton Wu
Licensed under the MIT License.