Express Configuration

TML Express library comes with many customization options that can be adjusted based on your application needs.

Basics

Add the following TML configuration to your app.js file:

var express       = require('express');  
var cookieParser  = require('cookie-parser');  
var tml           = require('tml-express');

var app = express();  
app.use(cookieParser());

app.use(tml.init({  
  key: "YOUR-PROJECT-KEY",
  cache: {
    adapter: "redis",
    host: "localhost",
    port: 6379
  }
});

SDK Default Options

Name Default Description
key Required. The key of your project.
version_check_interval 3600 seconds Number of seconds for the SDK to check the CDN for the new releases
debug false Will print out debug messages
current_locale param strategy Allows you so specify a locale you to translate the page to. The locale can be specified as a string, as a function or as a hash. See below for more details.
current_source URL path There are a number of ways to configure page sources. See below for more details.

Current Locale

TML SDK provides a few ways of how the locale can be specified using a string, function and hash.

Locale as String

Sometimes you want to force the page to be rendered in a specific locale. You can do that by setting the locale property in the init hash.

tml.init({  
    ...
    current_locale: 'ru'
    ...
});

The above code will force the page to be rendered in Russian. User will not be able to change the locale using a language selector.

Locale as Function

If your page contains a function that returns the page current locale, you can pass it in the parameter:

tml.init({  
    ...
    current_locale: function() {
       // get locale from the application
       return your_locale;
    }
    ...
});

Locale as Hash

If you need the locale extraction to be based on a parameter, pre-path or domain option, you can specify using a hash. We offer 4 locale strategies.

Param Strategy

This is our default strategy, if you don't specify anything else

tml.init({  
    ...
    current_locale: {
      strategy:   'param',
      default:    'en',
      param:      'locale',
      cookie:     true,
      redirect:   false
    }
    ...
});
Name Description
default Default locale of the site
param Name of the parameter to be passed, like "locale=ru"
cookie Once the locale is selected, it can be stored in a cookie and will be used on all other pages.
redirect If locale is not stored in a cookie, redirect will change the url and pass in the locale based on the browser preferred locale
Pre-Path Strategy

The param approach with a cookie is the older and most common way to pass the locale around. But it is not SEO friendly. Pre-path allows you to specify locale as the first element in your pass. For example,

https://www.sample.com/ru
https://www.sample.com/fr

You may need to configure your server or router for that. Once you have it setup on the routing side, use the following settings:

tml.init({  
    ...
    current_locale: {
      strategy:  'pre-path',
      prefix:    '/wordpress'
    }
    ...
});
Name Description
prefix Optional. Some sites, especially WordPress bases sites, may not be hosted directly under your root path "/". So prefix can be used to specify the first path element and the URLs will be constructed as: https://www.sample.com/{prefix}/ru
Pre-Domain Strategy

This strategy is similar to pre-path but it uses the first sub-domain element for locales.

https://ru.sample.com
https://fr.sample.com

You may need to configure your server or router for this strategy. And it would be a good idea to enable cookie sharing across all your subdomains. Once you have it setup on the routing side, use the following settings:

tml.init({  
    ...
    current_locale: {
      strategy:  'pre-domain'
    }
    ...
});
Custom Mapping

You can make your URLs look like anythin you want using this strategy. Here you would explicitly specify which locale is server by which URL.

tml.init({  
    ...
    current_locale: {
      strategy:   'custom-domain',
      mapping: {
         'en': 'my-en.lvh.me',
         'ru': 'my-ru.lvh.me',
         'ko': 'my-ko.lvh.me'
      }
    }
    ...
});

Current Source

By default, the SDK will use a full URL path to group all the strings into individual sources. So as you visit different pages, the stings would be grouped together for management and caching. For example:

http://docs.translationexchange.com/javascript-configuration

All strings from the above page will be grouped into "javascript-configuration" source.

The SDK offers other options of how you can name the sources yourself using string, function or a hash.

Source as String

If you want all of the site strings to be grouped under a single source, you can set it in the SDK like so:

tml.init({  
    ...
    current_source: "my-strings"
    ...
});

It may be the best and simplest option if your site is very small and you just want to collect all strings into a single source.

Source as Function

Your website can provide a function for extracting a source name. It may be useful if you have URLs with dynamic variable in them. You can use that method to parse the URL and remove the dynamic parts so you don't register too many sources.

tml.init({  
    ...
    current_source: function() {
      // do some figuring out of the source
      return your_source;
    }
    ...
});

Source as Hash

Function method above gives you the most power for determining your sources, but if you can use regular expressions for the dynamic URLs, you can define the source like so:

tml.init({  
    ...
    current_source: {
      "/profiles\/\d+/": "profiles/show",
      "/items\/\d+/": "items/show",
      ...
    }
    ...
});

It means that all the urls like:
https://sample.com/profiles/1
https://sample.com/profiles/2
https://sample.com/profiles/3

will be mapped to the "/profiles/show" source.