Javascript Configuration

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

Basics

Add the following code to the head section of your web page to activate the SDK.

<script src="https://cdn.translationexchange.com/tools/tml/stable/tml.min.js"></script>  
<script>  
tml.init({  
    key: "YOUR-PROJECT-KEY",
    translateBody: true,
    translateTitle: true
});
</script>  

SDK Default Options

Name Default Description
key Required. The key of your project.
translate_body
(or translateBody)
false If enabled, automatically translates the document body.
translate_title
(or translateTitle)
false If enabled, automatically translates the document title.
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
language_selector false If set to true, a default "floating flags" language selector will be injected into the page.
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.
source URL path There are a number of ways to configure page sources. See below for more details.
translator_options defaults DOM element extractor can be customized using various parameters. See below for more details
onLoad none Provide a callback function that will be called when tml is initialized.

onLoad: function(app) { }
onLanguageChange none Provide a callback function that will be called when language is changed.

onLanguageChange: function(language) { }

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.

<script>  
tml.init({  
    ...
    current_locale: 'ru'
    ...
});
</script>  

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:

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

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

<script>  
tml.init({  
    ...
    current_locale: {
      strategy:   'param',
      default:    'en',
      param:      'locale',
      cookie:     true,
      redirect:   false
    }
    ...
});
</script>  
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:

<script>  
tml.init({  
    ...
    current_locale: {
      strategy:  'pre-path',
      prefix:    '/wordpress'
    }
    ...
});
</script>  
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:

<script>  
tml.init({  
    ...
    current_locale: {
      strategy:  'pre-domain'
    }
    ...
});
</script>  
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.

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

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:

<script>  
tml.init({  
    ...
    current_source: "my-strings"
    ...
});
</script>  

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.

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

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:

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

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.

Nested Sources

By default, all strings of a specific page are included in the page source. But what if your application contains the same header, navigation bar and footer on each page - by default, all the strings of those sections will be registered on every source, creating unnecessary duplication. You can easily avoid that by grouping the various page sections into their own sources.

You can make any page element into its own source by adding "data-tml-source" attribute to the tag.

<div class="navbar" data-tml-source="navigation">  
    ...
</div>  

Any strings that would be found within the div tag will automatically be added to the "navigation" source in the dashboard.

Translator Options

Translator options allow you to customize the DOM extractor, including ignoring certain elements or only translating certain elements.

Translator options are specified as a hash under the main settings.

<script>  
tml.init({  
    ...
    translator_options: {
      ignore_elements: [".notranslate"],
      translatable_elements: [".section"],
      split_sentences: true,
      ...
    },
    ...
});
</script>  
Name Description
ignore_elements Specifies which elements on the page should be ignored.
translatable_elements Specifies which elements on the page should be translated.
split_sentences Defaults to true. If set to true, will split sentences and translate each sentence separately.

Skipping Translations

If you prefer not to translate certain elements, then you can add the notranslate attribute on the element.

<div notranslate>This section will not be translated</div>