https://github.com/aspectron/iris-i18n
https://github.com/aspectron/iris-i18n
Last synced: about 1 year ago
JSON representation
- Host: GitHub
- URL: https://github.com/aspectron/iris-i18n
- Owner: aspectron
- Created: 2015-02-07T06:57:31.000Z (over 11 years ago)
- Default Branch: master
- Last Pushed: 2018-08-22T09:57:09.000Z (almost 8 years ago)
- Last Synced: 2025-05-19T01:17:28.320Z (about 1 year ago)
- Language: JavaScript
- Size: 590 KB
- Stars: 1
- Watchers: 9
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# iris-i18n
IRIS - Site Localisation Module
-----
iris-i18n module is integrated within iris applications and provides tools for web site translation. This module does not currently integrate with Transifex or any other translation services. It provides it's own translation backend, which function in real-time - any entry translated is immediately visible on the web site.
iris-i18n requires EJS rendering engine.
## Configuration
`your-app/config/` folder contains 3 files:
* `i18n.conf` - configration settings
* `i18n.users` - configuration for user accounts
* `i18n.data` - data file containing all translation entries
#### i18n.conf
`i18n.conf` mainly contains list of supported languages and is automatically saved each time options are changed in the translation backend (enabling/disabling active languages).
#### i18n.users
`i18n.users` should be created locally when your application is deployed. It must not be present in git (unless your project is a private repository)
User configuration is done as follows:
```
{
"" : {
"locales" : "en fr", // or "*" for all (controls access to specific languages, space separated locale codes)
"pass" : "" // hex sha256 of pass
}
}
```
User login to the i18n backend uses geometric back-off algorithm, which means that each time incorrect login is made from a specific IP, the amount of seconds user has to wait doubles.
To generate a password, you can use simple hex output of sha256. This can be easily done here: http://www.xorbin.com/tools/sha256-hash-calculator or in NodeJs: `console.log(require("crypto").createHash("sha256").update("").digest("hex"))`
#### i18n.data
`i18n.data` is a custom data format that is kept in git and lives together with your project. The file format is custom in order to allow easier merging when encountering git merge conflicts.
## Translation Entries
Translation entries are generated using two phases. During the first phase, iris-i18n module scans `html` and `ejs` files located in your project and extracts all visible entries. Second phase is when translation entries are actually displayed on the web site.
All translation entries are kept in memory and when entries are translated, the database is delay-flushed to `i18n.data` file.
To check if any translation has been done, you can simply do `git diff` in your project to see if any modifications have been done to `i18n.data` file.
## Usage
`iris-i18n` provides a variable `_T` globally available within the EJS rendering context. `_T` is a function and a variable container (object) at the same time. Following fields are available under `_T`:
* `_T.locale` - current locale code
* `_T.languages` - list of active/enabled languages
* `_T.availableLanguages` - list of available languages (including languages that have not been activated/enabled)
* `_T.source` - source language of the site (typically "en")
To add a text entry to the translation database, user must pass it through a `_T()` function during EJS rendering phase (by embedding it into EJS view) as follows:
```
<%= _T("Hello World") %>
<%- _T("Hello World") %>
```
**NOTE:** Using EJS escaping for HTML entities `<%= %>` tag is recommended as non-escaping output tag `<%- %>` allows HTML injection into the web page. However, in some cases, especially when it comes to RTL languages and text envelopping links, it is desirable to re-position text around the link. In this case, unescaped text is fine. Just make sure to review translated entries or make sure you trust people who are translating your content.
For security sensitive sites and applications, you can deploy your NodeJs server in an alternate location (or on an alternate port), have people do the translation and then validate it by reviewing `i18n.data` file. Once done, commit the changes and pull them on the primary server.
Note on escaping - when allowing for unescaped HTML entities, you must make sure that HTML entities in the original HTML are preserved, as otherwise this may break your HTML content. (i.e. `` is preserved in original form - ommission of quotes will produce HTML with invalid syntax)
**IMPORTANT:** When pulling `i18n.data` changes from git, you must restart your process, preferably stop, pull and start. If site content is actively being translated, there is a risk of the running process to overwrite `i18n.data` file if someone translates an entry after the updated file has been pulled. We may change this behavior in the future.
If you have text located in client-side JS objects, best way to handle this is to relocate these objects into the EJS space, transform them via the `_T()` function and re-publish them back to client JS objects. Example:
```
<%
var obj = [
{ title : "first" },
{ title : "second"}
];
_.each(obj, function(o) {
o.title = _T(o.title);
})
%>
var obj = <%= JSON.stringify(obj) %>
```
## Translation backend
Translation backend can be accessed via `/i18n/` path in your iris application. (for example: `http://your-site.com/i18n/`)
Description of the user interface is available here: https://github.com/aspectron/iris-i18n/blob/master/doc/iris-i18n-user-interface.pdf