The best i18n middleware for Node.js
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


Join the chat at

Build Status Dependency Status License Status Downloads Version


  • Updated to Koa v2.0.0-alpha.3
  • Dropped support for Node.js < 4.0 (Sorry, but most servers are moving beyond 4. In theory, gengojs should still work below 4.0)
  • Writing docs.

Help wanted:

I am looking for maintainers! This project isn't very big and shouldn't be difficult to understand on how it works, so if you are interested, feel free to DM me through Gitter or Twitter (@iwatakeshi). :)


gengo.js is a server agnostic i18n/l10n library that is powered by its very small core. Along with the core, it is also managed by six plugins. The combinations of the these create a powerful and a unique library that enables developers to take over the core and extend its capabilities. The core is essentialy an empty shell that provides the basics such as a way of accessing a plugin's options or the plugin itself. As a starter, begin hacking the core and the plugins to find out how you can develop your own plugins and create the ultimate combination to create the best i18n library for Node.js.


gengo.js supports Sails through the use of hooks. Check out the repo of sails-hook-gengojs for documentation.

For an example use of the hook, run npm i && sails lift under examples/sails/app/.


// Modules used in example
var path = require('path');

// Options used in example
var options = {
  parser: {
    type: '*'
  backend: {
    directory: path.join(__dirname, '/config/locales/')
  header: {
    supported: ['en-US', 'ja']

// Express
var gengo = require('gengojs');
var app = require('express')();
// Use gengo

// Koa
var gengo = require('gengojs/koa');
var app = new require('koa')();
// Use gengo

// Hapi
var server = new require('hapi').Server();
var gengo = require('../../hapi/');
// Register gengo
server.register(gengo(options), function(error) {
  if (error) console.log('an error occurred: ' + error);


These are the complete and default options for the official plugins. Assigning options is quite simple in gengo.js.

# Options For Default Plugins
# ===========================

# API Options
# See for documentation.
  # 'global' refers to the api use for i18n your phrases. 
  #          ( e.g. __("Hello") )
  global = "__"
  # 'localize' refers to the api use for i18n your date, time, and number. 
  #            ( e.g. __l("ja").date().now() )
  localize = "__l"

# Backend Options
# See for documentation.
  # 'cache' refers to caching and enables gengo to store the dictionary 
  #         without changes until the server has been restarted.
  cache = true
  # 'directory' refers to the path to your dictionary
  directory = "./locales"
  # 'extension' refers to the file extension of your dictionary.
  extension = "json"
  # 'prefix' refers to the prefix in your file's name.
  prefix = ""
# Header Options
# See for documentation.
  # 'default' refers to the default locale of your app.
  default = "en-US"
  # 'supported' refers to the locales supported in your app.
  supported = ["en-US"]
  # 'headder.detect' refers to the detection type. 
  #                  Notes: 
  #                   * It is best to use one type of detection.
  #                   * Any PRs will be accepted that may help 
  #                     gengojs-accept detect multiple types.
    # 'cookie' enables cookie parsing for the locale.
    cookie = false
    # 'header' enables header parsing for the locale.
    #          ( e.g. Accept-Language )
    header = true
    # 'query' enables query parsing for any key that refers to the locale.
    #         ( e.g. )
    query = false
    # 'subdomain' enables subdomain parsing for the locale.
    #             ( e.g. )
    subdomain = false
    # url' enables url parsing for the locale.
    #      ( e.g. )
    url = false
# 'header.keys' refers to the key used in cookie and query parsing.
  cookie = "locale"
  query = "locale"
# Parser Options
# See for documentation.
  # 'type' refers to the type of parser used.
  #        ( e.g. 'default' = template/interpolation and sprintf, 'format' = message format, '*' = all/auto )
  type = "default"
  # 'keywords' refers to the keywords used in your dictionary.
    # 'default' refers to the default phrase 
    #           in your dictionary (in your native language).
    default = "default"
    # 'global' refers to the globally used dictionary 
    #          when router is enabled (router independent).
    global = "global"
    # 'translated' refers to the translated phrase 
    #              in your dictionary (in another language).
    translated = "translated"
  # 'parser.markdown' refers to options for markdown-it.
  #                   See for documentation.
    breaks = false
    enabled = false
    html = false
    langPrefix = "language-"
    linkify = false
    quotes = "“”‘’"
    typographer = false
    xhtmlOut = false
  # 'parser.sprintf' refers to sprintf
    # 'enabled' refers to enabling sprintf.
    enabled = true
  # 'parser.template' refers to interpolation.
  #                   ( e.g. __('{{greet}}', 'hello') -> 'hello'
    # 'enabled' refers to enabling interpolation.
    enabled = true
    # 'open' refers to opening expression.
    open = "{{"
    # 'close' refers to opening expression.
    close = "}}"

# Router Options
# See for documentation.
  # 'enabled' refers to enabling the special data structure in your dictionary.
  #           ( e.g. URL path = '/greet/', Dictionary = { 'index': {'greet': { /* ... */ } } } )
  enabled = false

There are three file extensions supported:

  • JSON
  • YAML
  • TOML
  • JS

Each plugin have their own defaults (if applicable) but to override them simply use one of the following ways:

  • Use a path to the options:
gengo('path to options');
  • Directly override the options:
  "parser": {/* ... */}


# make sure to install the node modules
npm install

# run test
gulp test