Rails Configuration

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

Basics

Create a new tml initializer file in config/initializers/tml.rb with the following configuration:

Tml.configure do |config|  
  config.application = {
    key:   YOUR_APPLICATION_KEY
  }
end  
Name Type Required Description
key String True Your Project's Application Key
token String False Your Project's Token. This token is only necessary if your application does not have a user interface where translators can provide translations inline, like in the case of an API service.

Logging

If you would like to see what the SDK is doing behind the scene, you can enable Tml logging.

Tml.configure do |config|  
  config.logger  = {
    :enabled  => true,
    :type     => :rails,
    :level    => 'debug'
  }
end  

This will use the standard Rails logger. Tml also comes with its own logger. You can provide the file path where only TML messages will be logged:

Tml.configure do |config|  
  config.logger  = {
    :enabled  => true,
    :path     => "#{Rails.root}/log/tml.log",
    :level    => 'debug'
  }
end  
Name Type Default Description
enabled Boolean false
path String the path to your log file

If, for any reason, you ever need to disable the library entirely, simply set the enabled flag to false:

Tml.configure do |config|  
  config.enabled = false
end  

This will automatically fallback to your default language, and al features of the SDK will be disabled.

Controller Methods

TML library looks for certain methods in the controller to load information about the current locale and user. If you don't provide those methods, the library will use its default approach.

Current Locale

By default the library will look for locale information in the controller method defined in current_locale method under the Application controller.

def current_locale  
   current_user.locale
end  

If you are exposing the locale using a different method, you can configure it using:

Tml.configure do |config|  
  config.current_locale_method = :my_locale_method
end  

If the method is not provided, TML will use the locale passed in the locale parameter, or use browser preferred locale, or use the locale stored in the cookie.

For more Locale Selection strategy please see our detailed instruction at Local Selection Strategy

Current User

If your application tracks users genders, TML library can use them for accurate gender based translations. The library will look for current_user method under the Application controller.

def current_user  
  @user ||= User.find_by_id(session[:user_id])
end  

If you are exposing the current_user using a different method, you can configure it using:

Tml.configure do |config|  
  config.current_user_method = :my_user_method
end  

Default Data Tokens

Sometimes you may need to use the same data token values across your entire application. For instance, a name of the company is not translatable and can be used in multiple places:

<%= tr('2016 Copyright {company}', company: 'Translation Exchange, Inc.') %>  

Instead of providing the same token value in every place you refer to the company, you can configure it as the default data token:

Tml.configure do |config|  
  config.set_default_token(:company, 'Translation Exchange, Inc.', :data)
end  

Now you can use the data token without having to specify its value:

<%= tr('2016 Copyright {company}') %>  

If you need to overwrite the value for a specific case, you can still do it using the tokens hash:

<%= tr('2016 Copyright {company}', company: 'Google, Inc') %>  

Default Decoration Tokens

Similarly to the data tokens, decoration tokens can also have default implementations. For instance, in the following example, bold has been preconfigured to use the strong HTML tag:

<%= tr('Welcome to [bold: my website]') %>  

where bold has been pre-configured as:

Tml.configure do |config|  
  config.set_default_token(:bold, '<strong>{$0}</strong>', :decoration)
end  

In the above example, the {$0} value will be replace with the translation of 'my website'.

Another example of a more complex decoration token is a link. Consider the following example:

<%= tr('Welcome to [link: my website]', link: {href: 'www.google.com'}) %>  

where link has been pre-configured as:

Tml.configure do |config|  
  config.set_default_token(:link, '<a href='{$href}'>{$0}</a>', :decoration)
end  

If the value of the decoration token is passed as a hash, the hash attributes will be mapped against the named attributes in the token substitution string.

Here is another example of a custom decoration token with pre-configured value:

Tml.configure do |config|  
  config.set_default_token(:colorize, "<span style='color: {$color}'>{$0}</span>", :decoration)
end  
<%= tr('Welcome to [colorize: my website]', colorize: {color: 'red'}) %>  

The following decoration tokens come pre-configured with the SDK, but you can easily change them to your liking.

{
 :strong =>  '<strong>{$0}</strong>',
 :bold   =>  '<strong>{$0}</strong>',
 :b      =>  '<strong>{$0}</strong>',
 :em     =>  '<em>{$0}</em>',
 :italic =>  '<i>{$0}</i>',
 :i      =>  '<i>{$0}</i>',
 :link   =>  "<a href='{$href}'>{$0}</a>",
 :br     =>  '<br>{$0}',
 :strike =>  '<strike>{$0}</strike>',
 :div    =>  "<div id='{$id}' class='{$class}' style='{$style}'>{$0}</div>",
 :span   =>  "<span id='{$id}' class='{$class}' style='{$style}'>{$0}</span>"
}

Decoration tokens can also be specified using the standard HTML notation:

<%= tr('Welcome to <colorize>my website</colorize>', colorize: {color: 'red'}) %>  

If there is no decoration token provided or no token value is specified, the HTML token will be used as is:

<%= tr('Welcome to <strong>my website</strong>') %>  

Context Data Extraction

TML library has a built in rules engine that is used to evaluate language rules and provide optimal translations.

For instance, if you have a user object defined as following:

michael = User.new(name: 'Michael', gender: 'male')  

And if we have a translation of a form:

<%= tr('{user} updated {user | his, her} profile', user: michael) %>  

The rules engine will automatically extract the gender of the user from the gender method and use its value to determine which translation to use.

But how did it know to use the gender method and how did it know to figure out that male value corresponded to male gender?

This information is stored in the configuration as well and can be easily changed for specific projects.

Tml.configure do |config|  
  config.context_rules[:gender][:variables]['@gender'] = 'gender'
end  

The library uses the 'male', 'female' and 'neutral' values by default to indicate the genders.

But what if your system has the following objects:

michael = User.new(name: 'Michael', sex: 1)  

Where instead of gender method you use sex and instead of 'male' and 'female' you use 1 and 0. In this case you can remap the methods to the following:

Tml.configure do |config|  
  config.context_rules[:gender][:variables]['@gender'] = lambda{ |obj|  
     obj.sex == 1 ? 'male' : 'female' 
  }
end  

A similar approach can be used to map values for number, genders, date, time, list and other objects.