# i18next-text
**Repository Path**: mirrors_cheton/i18next-text
## Basic Information
- **Project Name**: i18next-text
- **Description**: Using i18next translations without the need to maintain i18n keys.
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2020-08-08
- **Last Updated**: 2026-06-06
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# i18next-text [](https://travis-ci.org/cheton/i18next-text) [](https://coveralls.io/github/cheton/i18next-text?branch=master)
[](https://nodei.co/npm/i18next-text/)
Using [i18next](http://i18next.com/) translations without the need to maintain i18n keys.
It's recommended to use [i18next-scanner](https://github.com/cheton/i18next-scanner#usage-with-i18next-text) as a Gulp or Grunt plugin to scan your code, extract translation keys/values, and merge them into i18n resource files.
```javascript
i18n._('Save your time and work more efficiently.');
```
## Demo
**[Check out our demo](http://jsfiddle.net/cheton/fo8Lgact/)** on JSFiddle.
## Features
* Supports most [i18next features](http://i18next.com/pages/doc_features.html).
* Provides built-in support for [Handlebars i18n helper](https://github.com/cheton/i18next-text/tree/master#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](https://raw.githubusercontent.com/cheton/i18next-text/master/dist/i18next-text.custom.js) file with only 2KB in size.
## Installation
With [bower](http://bower.io/):
```
bower install i18next-text
```
With [npm](https://npmjs.org/):
```
npm install i18next-text
```
## Initialization
Normally [i18next-text](https://github.com/cheton/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:
```javascript
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:
```javascript
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
```html
```
English resource file (i18n/en/resource.json):
```json
{
"loading": "Loading...",
"b04ba49f848624bb97ab094a2631d2ad74913498": "Loading..."
}
```
German resource file (i18n/de/resource.json):
```json
{
"loading": "Wird geladen...",
"b04ba49f848624bb97ab094a2631d2ad74913498": "Wird geladen..."
}
```
All SHA-1 keys are automatically generated using [i18next-scanner](https://github.com/cheton/i18next-scanner). You do not need to maintain resource files.
### In Node.js
```javascript
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
```javascript
(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](https://github.com/cheton/i18next-text/) supports most [i18next features](http://i18next.com/pages/doc_features.html), for example:
* Access value in different language:
```javascript
i18n._('Loading...', {lng: 'de'}); // will get value in de instead of en
```
* Replacing variables:
```javascript
i18n._('YouTube has more than __count__ billion users.', {count: 1});
```
Visit [http://i18next.com/pages/doc_features.html](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:
```javascript
var i18nText = require('i18next-text');
i18nText.key('Loading...'); // will return a hash string
```
### Checks if a string exists
```javascript
var i18nText = require('i18next-text');
i18nText.exists('Loading...'); // will return a boolean value
```
### Locates missing translation
```javascript
var strNotTranslated = 'STRING_NOT_TRANSLATED';
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:
```html
STRING_NOT_TRANSLATED
```
You can see a demo [here](http://jsfiddle.net/cheton/fo8Lgact/).
### Providing a default key
You can explicitly specify a default key of a text string by passing a `defaultKey` option:
```javascript
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:
```javascript
i18n.init({sendMissing: true});
```
### Custom hash function
You can customize your own hash function by including the [i18next-text.custom.js](https://raw.githubusercontent.com/cheton/i18next-text/master/dist/i18next-text.custom.js) file, which is only 2KB in size:
```html
```
In your initialization script, change `hash` on i18nText.init() to apply a custom hash function:
```javascript
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:
```javascript
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:
```javascript
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:
```html
{{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:
```javascript
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](http://jsfiddle.net/cheton/fo8Lgact/).
## License
Copyright (c) 2015 Cheton Wu
Licensed under the [MIT License](https://github.com/cheton/i18next-text/blob/master/LICENSE).