@transifex/express

Transifex Native is a full end-to-end, cloud-based localization stack for moderns apps.

Transifex Native SDK: Express i18n middleware

Express middleware for server side localization using Transifex Native.

Related packages:

• @transifex/native
• @transifex/cli

Learn more about Transifex Native in the Transifex Developer Hub.

Quick start

Install the necessary express packages:

npm install --save express cookie-parser body-parser ...

And the Transifex Native integration:

npm install --save @transifex/native @transifex/express

Create an express app and attach the necessary middleware:

const express = require('express');
const cookieParser = require('cookie-parser');
const bodyParser = require('body-parser');

const app = express();
app.use(cookieParser());
app.use(bodyParser.urlencoded({ extended: false }));

Import the Transifex Native libraries and set up:

const { TxExpress } = require('@transifex/express');

const txExpress = new TxExpress({ token: '...' });
app.use(txExpress.middleware());
app.post('/i18n', txExpress.setLocale());

All options passed to the TxExpress's constructor that are not handled by it will be passed on to tx.init internally. If you have already initialized the tx object, you do not have to supply these options.

const txExpress = new TxExpress({
  // TxExpress options
  daemon: true,
  ttl: 2 * 60,

  // tx options
  token: '...',
  filterTags: 'mytags',
});

// is equivalent to

const { tx } from '@transifex/native';
tx.init({ token: '...', filterTags: 'mytags' })
const txExpress = new TxExpress({ daemon: true, ttl: 2 * 60 });

Finally, fetch available languages and translations and start the server:

txExpress.fetch().then(() => {
  app.listen(3000, () => {
    console.log('App listening on port 3000');
  });
});

txExpress.middleware() middleware

app.use(txExpress.middleware());

The middleware will make sure that you have a req.t function to translate the argument to the user's selected language.

app.get('/', (req, res) => {
  res.send(req.t('Hello world!'));
});

The t-function has the same interface as @transifex/native's t-function. So, you can pass all extra arguments, like this:

app.get('/', (req, res) => {
  res.send(req.t('Hello world!', { _context: 'foo', _tags: 'bar' }));
});

The middleware will also make sure that any templates that are rendered by Express will have a t-function and a tx object in their context. The t-function will take care of translation (in the same way as req.t does) and the tx object holds a list of available languages and the currently selected language code (tx.languages and tx.currentLocale respectively). Using this, you can do:

// index.js
app.set('views', './views');
app.set('view engine', 'pug');

app.get('/', (req, res) => {
  res.render('index.pug');
});

// views/index.pug
html
  body
    form(method='POST' action='/i18n')
      select(name='locale')
        each locale in tx.languages
          option(
            value=locale.code
            selected=locale.code === tx.currentLocale
          )= locale.name
      input(type='submit' value="Change language")
    p= t('Hello World!')

This will render a language-select dropdown (with the list of languages dynamically fetched by Transifex Native) and a translated string.

This (having t and tx available in the template's context) works regardless of which template engine is being used.

Escaping strings

Normally, interpolating strings in HTML that is to be rendered by a browser can make your application vulnerable to XSS attacks. For this purpose, the t-function in the express integration (both req.t and the t-function that is available to the template's context) return the escaped version of the rendered string. If you are confident that your string is safe to use inside HTML or that your template engine takes care of escaping for you, then you must use ut (available both as req.ut and as the ut function in your templates). Also, be careful of double escaping:

// index.js

app.get('/', (req, res) => {
  // This will send 'hello &lt;world&gt;' and it will appear as 'hello <world>'
  // in the browser
  res.send(req.t('hello <world>'));

  // This will send 'hello <world>' and it is dangerous to show in the browser
  res.send(req.ut('hello <world>'));
})

// views/index.pug

// These will send 'hello <world>' and they will appear as
// 'hello <world>' in the browser
p #{t('hello <world>')}
p= t('hello <world>')

// These will send 'hello &lt;world&gt;' and they will appear as
// 'hello <world>' in the browser
p #{ut('hello <world>')}
p= ut('hello <world>')

// These will send 'hello &lt;world&gt;' and they will appear as
// 'hello <world>' in the browser
p !{t('hello <world>')}
p!= t('hello <world>')

// These will send 'hello <world>' and they are dangerous to show in the
// browser
p !{ut('hello <world>')}
p!= ut('hello <world>')

txExpress.setLocale() handler

app.post('/i18n', txExpress.setLocale());

The txExpress.setLocale() endpoint handler (mapped to /i18n in the example) is used by the user to change their selected language. The form to make this happen could look like this:

<form method="POST" action="/i18n">
  <input type="hidden" name="next" value="/current_url" />
  <select name="locale">
    <option value="en">English</option>
    <option value="el">Greek</option>
    <option value="fr">French</option>
  </select>
  <input type="submit" value="change language" />
</form>

The value of next will determine where the user will be redirected to after the form is submitted. If next is missing, then the user will be redirected to the value of req.headers.referer which is the page where the form originated from.

If you make an AJAX POST request with a JSON Content-Type to this endpoint with a locale field, the server will respond with a {"status": "success"} reply, after having changed the user's selected language (it will be up to you to reload the page if you want to).

Modes

The user's selected language can be saved and retrieved with a number of available modes:

Cookie (default)

This saves the selected language on a cookie named after the value of 'options.name'.

const { TxExpress, CookieMode } = require('@transifex/express');
const txExpress = new TxExpress({
  mode: CookieMode({ name: 'my-tx-cookie' }),
});

It must be used alongside cookie-parser:

const express = require('express');
const bodyParser = require('body-parser');
const app = express();
app.use(bodyParser.urlencoded({ extended: false }));

const cookieParser = require('cookie-parser');
app.use(cookieParser());

const { TxExpress, CookieMode } = require('@transifex/express');
const txExpress = new TxExpress({
  token: '...',
  mode: CookieMode({ name: 'my-tx-cookie' }),
});

app.use(txExpress.middleware());
app.post('/i18n', txExpress.setLocale());
app.get('/', (req, res) => { res.send(req.t('Hello world!')); });

Also accepts the cookieOptions option which will be forwarded to req.cookie().

Signed cookie

This saves the selected language on a signed cookie named after the value of 'options.name'.

const { TxExpress, SignedCookieMode } = require('@transifex/express');
const txExpress = new TxExpress({
  mode: SignedCookieMode({ name: 'my-tx-cookie' }),
});

It must be used alongside cookie-parser which needs to be supplied with a secret:

const express = require('express');
const bodyParser = require('body-parser');
const app = express();
app.use(bodyParser.urlencoded({ extended: false }));

const cookieParser = require('cookie-parser');
app.use(cookieParser('mysecret'));

const { TxExpress, SignedCookieMode } = require('@transifex/express');
const txExpress = new TxExpress({
  token: '...',
  mode: SignedCookieMode({ name: 'my-tx-cookie' }),
});

app.use(txExpress.middleware());
app.post('/i18n', txExpress.setLocale());
app.get('/', (req, res) => { res.send(req.t('Hello world!')); });

Also accepts the cookieOptions option which will be forwarded to req.cookie().

Session

This saves the selected language on a session variable named after the value of 'options.name'.

const { TxExpress, SessionMode } = require('@transifex/express');
const txExpress = new TxExpress({
  mode: SessionMode({ name: 'my-tx-cookie' }),
});

It must be used alongside express-session or cookie-session:

const express = require('express');
const bodyParser = require('body-parser');
const app = express();
app.use(bodyParser.urlencoded({ extended: false }));

const session = require('express-session');
// or
const cookieSession = require('cookie-session');

app.use(session({ secret: 'mysecret', ... }));
// or
app.use(cookieSession({ keys: ['mysecret'], ... }));

const { TxExpress, SessionMode } = require('@transifex/express');

const txExpress = new TxExpress({
  token: '...',
  mode: SessionMode({ name: 'my-tx-cookie' }),
});

app.use(txExpress.middleware());
app.post('/i18n', txExpress.setLocale());
app.get('/', (req, res) => { res.send(req.t('Hello world!')); });

Custom modes

The values for the mode options are objects that implement the setLocale(req, res, locale) and getLocale(req, res) functions. You can easily implement your own. A sample implementation could look like this:

const myMode = {
  userLocales: {}, // User ID to selected locale map
  setLocale(req, res, locale) {
    this.userLocales[req.cookies.userId] = locale;
  },
  getLocale(req, res) {
    return this.userLocales[req.cookies.userId];
  },
};

const txExpress = new TxExpress({ mode: myMode });

Extracting strings with txjs-cli

The txjs-cli program from the @transifex/cli package will manage to extract invocations of the req.t function in your source code, as well as invocations of the t function in '.pug' and '.ejs' templates.

➜  npm install @transifex/cli

➜  npx txjs-cli push views -v

    Parsing all files to detect translatable content...
    ✓ Processed 2 file(s) and found 2 translatable phrases.
    ✓ Content detected in 2 file(s).
    /views/index.ejs
      └─ This string originated from a EJS file
        └─ occurrences: ["/views/index.ejs"]
    /views/index.pug
      └─ This string originated from a PUG file
        └─ occurrences: ["/views/index.pug"]

    Uploading content to Transifex... Success
    ✓ Successfully pushed strings to Transifex:
      Created strings: 2

It is easy to enhance support for express template engines in txjs-cli, especially if the template engine in question works by converting a template to javascript code that can be then fed to the normal extraction process. In fact, this in the only piece of code that was needed in order to extend support to .pug and .ejs templates:

// transifex-javascript/packages/cli/src/api/extract.js

function extractPhrases(file, relativeFile, options = {}) {

  // ...

  let source = fs.readFileSync(file, 'utf8');

  if (path.extname(file) === '.pug') {
    source = pug.compileClient(source);
  } else if (path.extname(file) === '.ejs') {
    const template = new ejs.Template(source);
    template.generateSource();
    source = template.source;
  }

  // ...
}

So, if your template engine of choice is not supported by txjs-cli yet, please consider contributing a pull request 😉.

API

TxExpress

new TxExpress({

  // How to save the selected language. Must implement the `setLocale(req, res,
  // locale)` and `getLocale(req, res)` methods. Builtin modes: `CookieMode`,
  // `SignedCookieMode`, `SessionMode`.
  mode: Object,

  // Whether to fall back to the request's 'Accept-Language' header (set by the
  // browser) if the selected language isn't set, default: true
  fallBackToAcceptLanguage: Boolean

  // The locale to fall back to if both the mode and the 'Accept-Language'
  // header fail to produce a result, default: 'en'
  sourceLocale: String,

  // If the server should periodically refetch translations from Transifex,
  // default: true
  daemon: Boolean,

  // If daemon is true, how often to refetch translations in seconds, default:
  // 10 minutes
  ttl: Integer,

  // How to display log messages; a straightforward option would be
  // `console.log`, default: noop
  logging: Function
})

CookieMode

CookieMode({
  // The name of the cookie to be used
  name: String,

  // Extra options passed to the `req.cookie()` function
  cookieOptions: Object,
});

SignedCookieMode

SignedCookieMode({
  // The name of the cookie to be used
  name: String,

  // Extra options passed to the `req.cookie()` function; the `signed: true`
  // option will always be set
  cookieOptions: Object,
});

SessionMode

SessionMode({
  // The name of the session field to be used
  name: String,
});