Tr8n Client SDK for Ruby on Rails
This Client SDK provides extensions necessary for translating Rails based application using the Tr8nHub service.
Tr8n Client SDK Sample
The best way to start using Tr8nHub is to run the sample application that comes bundled with this SDK.
$ git clone https://github.com/tr8n/tr8n_rails_clientsdk.git
$ cd tr8n_rails_clientsdk/spec/dummy
$ bundle
$ script/rails s
This will start the dummy application in development mode. The development mode uses Tr8nHub sandbox server for translations.
Alternatively, you can use the same sample application as a stand alone app:
https://github.com/tr8n/tr8n_rails_clientsdk_sample
This application is running at:
Integration Instructions
To integrate Tr8n SDK into your app, all you need to do is:
Add the following gems to your Gemfile:
gem 'tr8n_client_sdk'
Install the gems:
$ bundle
Add the following configuration to your Application.rb (or to the various environment files):
Tr8n.configure do |config|
config.application = {
:key => YOUR_APP_KEY,
:secret => YOUR_APP_SECRET
}
end
In the HEAD section of your layout, add:
<%= tr8n_scripts_tag %>
You are done, tr8n is now running in your app.
Now you can simply add the default language selector anywhere on your page using:
<%= tr8n_language_selector_tag %>
And use TML (Translation Markup Language) to translate your strings, using:
<%= tr("Hello World") %>
<%= tr("You have {count||message}", :count => 5) %>
<%= tr("{actor} sent {target} [bold: {count||gift}]", :actor => actor_user, :target => target_user, :count => 5) %>
...
Learn more about TML at: http://wiki.tr8nhub.com
Caching
You should enable caching for your application. Without caching you will be querying the service for new translations on every page load. If you do it too much, you will be throttled. The translation service is designed to service the up-to-date translations only if you your translators are in translation mode. For all other users you should serve translations from your cache.
To enable cache, simply add the following configuration to Tr8n config:
Tr8n.configure do |config|
config.cache = {
:enabled => true,
:adapter => 'memcache',
:host => 'localhost:11211',
:version => 2,
:timeout => 3600
}
end
The following Cache adapters are supported:
Memcache, Redis, CDB, File
It is easy to add any other custom cache adapter as well.
Memcache and Redis adapters can do a realtime cache warmup - by loading the translations from the service and storing them in the cache.
To reset/upgrade your cache, you can simply call
Tr8n.cache.upgrade_version
All the keys stored in memory based cache are versioned. By upgrading the version you will effectively invalidate the old keys and the new keys will be loaded from the translation service.
CDB and File adapters require pre-generation. You can pre-generate your cache by running:
$ rake tr8n:generate_cache:file
or
$ rake tr8n:generate_cache:cdb
You can also do a combination of file-based adapters (for persistent cache) and memory-based adapters for serving the translations.
Logging
Tr8n comes with its own logger. If you would like to see what the SDK is doing behind the scene, enable the logger and provide the file path for the log file:
Tr8n.configure do |config|
config.logger = {
:enabled => true,
:path => "#{Rails.root}/log/tr8n.log",
:level => 'debug'
}
end
Rules Engine Customizations
Tr8n comes with default settings for the rules engine. For example, it assumes that you have the following methods in your ApplicationController:
def current_user
end
def current_locale
end
Tr8n only needs the current_user method if your site needs to use gender based rules for the viewing user.
Similarly, if you prefer to use your own mechanism for storing and retrieving user's preferred and selected locales, you can provide the current_locale method.
If you need to adjust those method names, you can set them in the config:
Tr8n.configure do |config|
config.current_user_method = :my_user
config.current_locale_method = :my_locale
end
To read more about what you can do with Tr8n, visit the wiki site: