Rails Integration

Rails SDK offers many methods and helper functions that can be used in the Controllers, Views and Models. The following sections will provide a detailed description for every method and its options.

Common Methods (available in controllers and views)

View Tags (available only in views)

View Helpers (available only in views)

String Extensions (available throughout the application)

Array Extensions (available throughout the application)

Common Methods

tr

Translation helper available in controllers and views.

tr(label, description, tokens, options)

# The description parameter can be omitted
tr(label, tokens, options)  

Some examples of how the method can be used:

<%= tr("Hello World") %>  
Name Type Required Description
label String true The label to translate
description String false Description of the label that acts as a hint to the translator as well as contextualizes the key to be unique for the description
tokens Hash false If label uses data or decoration tokens, the token values will be provided using this parameter
options Hash false Additional attributes

Options:

  • source - sets source of strings in your dashboard, source is artificial separation of strings
  • locale - locale of the string it can be sometimes different from default locale
  • target_locale - used to set string to specific local which will not depend on default local, can be used for some text that you always want to see in specific locale
  • skip_decorations - if set to true, content will not be decorated

There are a number of ways the tokens can be passed to the tr method.

The token value can be a simple string:

<%= tr("Hello {user}", user: "Michael") %>  

It can also be an object, in which case the object will be evaluated for the context rules and the result of to_s method will be used for display:

<%= tr("Hello {user}", user: current_user) %>  

If you would like to change the way the object is displayed, you can use an array where the first element is the object and the second element is the representation of the value:

<%= tr("Hello {user}", user: [current_user, current_user.name]) %>  

You can simply pass the name of the attribute as a symbol:

<%= tr("Hello {user}", user: [current_user, :name]) %>  

Or you may use other function to act on the value:

<%= tr("Hello {user}", user: [current_user, link_to(current_user)]) %>  

You could even define a custom lambda for extracting the content and pass it in the second element:

user_with_link = lambda{|user| link_to(user.name)}

<%= tr("Hello {user}", user: [current_user, user_with_link]) %>  

You can also be more explicit and use hashes instead of arrays:

<%= tr("Hello {user}", user: {object: current_user, attribute: :name}) %>  


trl

Translating labels, can be used in views, controllers, and models. trl is the same as tr function but sets the option to never use inline translation for the elements:

trl(label, description, tokens, options)

# The description parameter can be omitted
trl(label, tokens, options)  

Example:

<img alt="<%= trl('Hello World') %>" src="...">  

trl will not output decorators, only the translated string. All parameters from tr will work with trl.


trfn

Used to translate flash notifications. trfn is the same as tr function but the result of the function is set in the flash object under the trfn keyword.

Example:

class HomeController < ApplicationController

  def index
    trfn('Your account has been activated')
  end

end

# in the view, use:

<%= flash[:trfn] %>  


trfe

Used to translate flash error messages. trfe is the same as tr function but the result of the function is set in the flash object under the trfe keyword.

Example:

class HomeController < ApplicationController

  def index
    trfe('You have an error')
  end

end

# in the view, use:

<%= flash[:trfe] %>


trfw

Used to translate flash warning messages. trfw is the same as tr function but the result of the function is set in the flash object under the trfw keyword.

Example:

class HomeController < ApplicationController

  def index
    trfw('This is your last warning')
  end

end

# in the view, use:

<%= flash[:trfw] %>


tml_session

Object containing information about the current TML session.

tml_session  

Properties:

  • application - The current application
  • block_options - Stack of block options being processed
  • current_user - Current user
  • current_locale - Current locale
  • current_language - Current language
  • current_translator - Current translator
  • current_source - Current source


tml_application

Object containing information about the current application.

tml_application  

Properties:

  • key - The application key
  • name - The project name
  • default_locale - The source language locale code (e.g. "en")
  • languages - List of all application languages


tml_current_user

The viewing user of the application. Any translations that are based on the viewing user gender will use this user for the language gender context rules.

tml_current_user  

To read more about how to configure and set the current_user, please see:

http://docs.translationexchange.com/rails-configuration/#controllermethods


tml_current_translator

If application is being used in the translation mode and there is a translator present who is logged in and is using the application, the translator information will be available in this method.

tml_current_translator  

Properties:

  • id - Translator id
  • name - Translator name
  • email - Translator email
  • mugshot - Translator mugshot URL
  • features - Translator feature
  • rank - Translator rank
  • voting_power - Voting power of the translator


tml_current_locale

A string of the current selected language locale.

tml_current_locale  
# "ru" 


tml_current_language

Object containing information about the current selected language.

tml_current_language  

Properties:

  • english_name - The english name of the language (e.g. "Russian")
  • native_name - The native name of the language (e.g. "Русский")
  • locale - The language locale code (e.g. "ru")
  • flag_url - flag icon image url
  • dir - The direction of the language, "ltr" or "rtl" (right-to-left)


tml_current_source

String of the current source name.

tml_current_source  
# "company/careers"


tml_language_dir

A string of the current language direction, "ltr" (left-to-right) or "rtl" (right-to-left)

tml_language_dir  
# "ltr"


tml_subdomain_locale_url

If your application uses subdomains for locales, this method will use the locale parameter to create the appropriate subdomain url.

tml_subdomain_locale_url('ru')  
# "ru.mydomain.com"

View Tags

tml_scripts_tag

Generates the script for including the Translate Exchange Tools. This is required for enabling translation mode and using the in-context translation tools.

<%= tml_scripts_tag %>  

The tml_scripts_tag should always be added in the head section of your layout files.


tml_language_selector_tag

Generates a Translation Exchange Language Selector. It has several options for you to try and select the best fit for your web site.

tml_language_selector_tag(type, options)  

Example:

<%= tml_language_selector_tag(:default) %>  
Name Type Required Description
type Symbol false The name of the language selector. Defaults to `:default`
options Hash false Additional options specific chosen language selector

For a list of all available language selectors go the Language Selectors section of the docs.


Adds a stylesheet based on the language direction.

tml_stylesheet_link_tag(ltr, rtl, attrs)  

Example:

<%= tml_stylesheet_link_tag('default_ltr.css', 'default_rtl.css') %>  


tml_language_name_tag

Returns the language name of the language passed in the params.

tml_language_name_tag(lang, options)  

Example:

<%= tml_language_name_tag %>  


tml_language_flag_tag


tml_when_string_tag


tml_style_attribute_tag


tml_style_directional_attribute_tag


tml_html_attributes_tag


tml_dir_attribute_tag


tml_lang_attribute_tag

View Helpers

trh

Translate HTML Block helper

trh(tokens, options, &block)  

Example:

<%= trh do %>  
  <p>your html block goes here</p>
<% end %>  
Name Type Required Description
tokens Hash false token values will be provided using this parameter
options Hash false Additional attributes can be passed using the parameter. Attributes include inline decoration flag, source locale and others.


tml_source

Defines a source block. All translations within the source block will automatically be grouped and cached as a single source.

tml_source(name)  

Example:

<%= tml_source('navigation') do %>  
  <ul class="nav navbar-nav">
    <li><%= link_to(tr('Home'), '#') %></li>
    <li><%= link_to(tr('About Us'), '#') %></li>
    <li><%= link_to(tr('Search'), '#') %></li>
  </ul>
<% end %>  
Name Type Required Description
name String true The name of the source


tml_block

Define a section of your site to be available in one locale and not be translated to any other language.

tml_block(options, &block)  

Example:

<%= tml_block({source: "my source 2", locale: 'ru', target_locale: 'fr'}) do %>  
   <div>
     <%= "Hello world"%>
   </div>
<% end %>  

Available Options:

Name Type Required Description
source String false An optional source name for the block
locale String false locale of the block, it can be sometimes different from default locale
target_locale String false used to set the block to a specific local which will not depend on the default locale


tml_options_for_select


tml_select_month

String Extensions


String translate

Allows to translate any string from within Models, Views and Controllers.

We don't offer the tr method here, since it is already implemented in the string. Instead we spell it out as translate.

string.translate(description = '', tokens = {}, options = {})

# or simply
string.translate(tokens = {}, options = {})  

Example:

<%= 'Hello World'.translate %>  
<%= 'Invite'.translate('An invitation') %>  
<%= 'Hello {user}'.translate(user: 'Michael') %>  


String trl

This method is similar to String translate, but it disables inline translation mode.

string.trl(description = '', tokens = {}, options = {})

# or simply
string.trl(tokens = {}, options = {})  

Example:

<%= 'Hello World'.trl %>  
<%= 'Invite'.trl('An invitation') %>  
<%= 'Hello {user}'.trl(user: 'Michael') %>  

Array Extensions


Array translate

Translates the elements of the array.

array.translate(description = '', options = {})  

Example:

['Apples', 'Oranges'].translate

# ['Яблоки', 'Апельсины']


Array translate_and_join

Translates the elements of the array and joins them together.

array.translate_and_join(separator = ', ', description = '', options = {})  

Example:

['Apples', 'Oranges'].translate_and_join

# Яблоки, Апельсины


Array translate_sentence

Translates the elements of the array and joins them together.

array.translate_sentence(description = '', options = {})  

Example:

['Apples', 'Oranges', 'Bananas'].translate_sentence

# Яблоки, Апельсины и Бананы


Array translate_options

This method is mostly used for translating options_for_select. It translates the elements of the array and sub-arrays based on the data type.

array.translate_options(description = '', options = {})  

Example:

['Apples', 'Oranges', 'Bananas'].translate_options

# [["Яблоки", "Apples"], ["Апельсины", "Oranges"], ["Бананы", "Bananas"]]