In this post we will create a simple web site using Ruby on Rails and translate it to a few languages using Translation Markup Language and Translation Exchange service.

In this demo, we will create a simple one page site, called “Welp”. On the site we will have a few restaurant reviews and a search form.

Once you follow this guide, you will see how you can use Translation Exchange tools to quickly and easily translate the app to any number of languages.

You can activate translation mode by clicking on “Help Us Translate” link.

All of the source code for this post can be found at:

https://github.com/translationexchange/blog/tree/master/getting-started-with-rails-and-tml/welp

Let’s create a RoR application by executing the following commands:

[shell]
$ rails new welp
$ cd welp
[/shell]

Let’s create our main controller called “home” with a “index” action:

[shell]
$ bundle exec rails g controller home index
[/shell]

We need to make sure our home controller and action are available in the routes. Edit config/routes.rb file and add the following:

[ruby title=”config/routes.rb” class=”lang:ruby”]
Rails.application.routes.draw do
get ‘home/index’
root ‘home#index’
end
[/ruby]

Let’s start our server and make sure the index view can be loaded:

[shell]
$ bundle exec rails s
$ open “http://localhost:3000”
[/shell]

Now let’s add the TML gem to our Gemfile. We will be using tml-rails gem that comes with extensions for Rails applications. We will also add a Dalli gem so we can use Memcache as our cache adapter:

[shell title=”Gemfile” class=”lang:bash”]
gem ‘tml-rails’
gem ‘dalli’
[/shell]

Install the gem by running:

[shell]
$ bundle
[/shell]

To properly instantiate our library, we need to add an initializer file. All our settings and configurations will be kept there. Create a new file called config/initializers/tml.rb and add the following information:

[ruby title=”config/initializers/tml.rb” class=”lang:ruby”]
Tml.configure do |config|
config.application = {
key: ‘YOUR_APPLICATION_KEY’
}

config.cache = {
enabled: true,
adapter: ‘memcache’,
namespace: ‘translations’,
host: ‘localhost:11211’
}

config.logger = {
enabled: true,
path: “#{Rails.root}/log/tml.log”,
level: ‘debug’
}
end
[/ruby]

We will cache all our translations using Memcache server and log debug information in log/tml.log file. There are many other options for caching translations data. For instance to cache translations using Redis, use:

[ruby title=”config/initializers/tml.rb” class=”lang:ruby”]
config.cache = {
enabled: true,
adapter: ‘redis’,
namespace: ‘translations’,
host: ‘localhost:6379’
}
[/ruby]

If you prefer keeping all translations in memory of each process and load them from file system, you can use the release snapshot and point your cache to local files:

[ruby title=”config/initializers/tml.rb” class=”lang:ruby”]
config.cache = {
enabled: true,
adapter: ‘file’,
path: ‘config/tml’,
version: ‘current’
}
[/ruby]

We will come back to file caching and releases in a separate post.

Keep in mind, if you disable cache, translations will be loaded directly from the API. This approach works great while you are in development or translation modes, but you should always cache translations in your production environment.

Our next step is to create our layout. Let’s update the application layout with the following:

[ruby title=”app/views/layouts/application.html.erb” class=”lang:ruby” mark=”2,14″]

>
Welp

<%= stylesheet_link_tag “application”, media: “all”, “data-turbolinks-track” => true %>
<%= javascript_include_tag “application”, “data-turbolinks-track” => true %>

<%= csrf_meta_tags %>

<%= tml_scripts_tag %>
<%= render ‘/layouts/navigation’ %>

<%= yield %>

[/ruby]

Notice that on line 2 we use tml_html_attributes_tag which automatically adds lang and directional attributes to the HTML tag. On line 14 we add tml scripts that offer in-context translations and globalization metrics.

Let’s add the navigation include file.

[ruby title=”app/views/layouts/_navigation.html.erb” class=”lang:ruby” mark=”1,42″]
<%= tml_source(‘navigation’) do %>

<% end %>
[/ruby]

On lines 1 and 42 we open and close a source block. All translation keys within the block will automatically be grouped and cached as a single source. If you have multiple pages using the same navigation include – it will automatically be used from the cache and used across all pages. We then use tr method to mark all content we want to translate.

Now we can update our main view.

[ruby title=”app/views/home/index.html.erb” class=”lang:ruby”]

[/ruby]

You can see the source code for this post here:
https://github.com/translationexchange/blog/tree/master/getting-started-with-rails-and-tml/welp

You can also see various versions of Rails and different cache adapters used with this app here:
https://github.com/translationexchange/tml-rails-samples-welp

Now that the SDK is integrated into the application, let’s translate it. To put the application into translation mode, press Ctrl+Shift+I. When translation mode is activated, the application will send all your strings to our platform, register them and will start looking for translations from our UTM. The mode also allows you to review suggested translations, vote on them and let your translator team provide new suggestions. Proofreaders can review suggested translations and lock them into your application’s translation memory.

To deactivate translation, press Ctrl+Shift+I again.

To learn more about TML, visit the following url:
http://welcome.translationexchange.com/docs/tml/basics