4. Configuration Instructions

Now you are ready to configure and integrate Tr8n engine plugin into your application. When you run the “rake tr8n:sync” command in one of the steps above, the configuration files were copied into your application config folder under the tr8n folder. Those files contain config.yml, which controls the behavior of the engine, enables and disables various engine features and provides date/time localization features. The tr8n folder also contains subfolders with default languages, language rules, language cases, glossaries, shortcuts, etc… Most of the files are self explanatory and contain comments that describe their use. When you run the “rake tr8n:init” command, the contents from the “defaults” files were imported into the database. If you ever want to clean the tr8n database (while developing), you

The main Tr8n configuration file is located here:

config/tr8n/config.yml

The content of the file is mostly self-explanatory. You can keep most of the defaults. The sections bellow will describe how to change certain aspects of the integration.

Enabling Tr8n Features¶ ↑

The following are the basic features of Tr8n.

enable_tr8n:                true      # enables the engine
enable_key_source_tracking: false     # builds the site map sources
enable_key_caller_tracking: false     # tracks all calls to labels with their traces - for debugging only
enable_glossary_hints:      true      # shows glossary in the translator    
enable_software_keyboard:   true      # shows the soft keyboard icon  
enable_google_suggestions:  true      # uses google for suggestions
enable_keyboard_shortcuts:  true      # adds some keyboard shortcuts like ctrl+shift+s
enable_dictionary_lookup:   true      # shows dictionary words definitions
enable_fallback_languages:  true      # for example: Catalan can fallback onto Spanish
enable_translator_language: true      # translator can translate from non-default language
enable_language_flags:      true      # shows flag icons next to the languages
enable_admin_translations:  true      # registers tr8n admin keys in the system
enable_admin_inline_mode:   true      # allows tr8n engine sections to be inline translated
enable_language_cases:      true      # enables support for language cases
enable_client_sdk:          false     # allows javascript to use tr8nProxy object

enable_key_source_tracking needs to be periodically enabled, especially when new features are added to the site map. If enabled, Tr8n will log the sources for every translation key on the site.

Configuring Site and Site Users¶ ↑

Below are the default values from Tr8n config.yml, which are configured for the Tr8n stand alone mode. You will need to modify some of those values to make Tr8n work with your application.

site_info:  
  title:                    Tr8n                            # site title - provide your site title here
  contact_email:            admin@tr8n.org                  # contact email for questions about translations
  current_locale_method:    current_locale                  # application controller method that sets and returns current locale
  default_url:              /tr8n/home                      # default site url where to redirect the user if Tr8n is disabled            
  default_locale:           en-US                           # locale of the site default language  
  sitemap_path:             /config/tr8n/site/sitemap.json  # location of the sitemap definition file
  splash_screen:            /tr8n/common/splash_screen      # location of the Tr8n splash screen  
  tr8n_layout:              tr8n                            # layout for the tr8n pages
  tr8n_helpers:             []                              # if you need to add extra helpers
  admin_layout:             tr8n_admin                      # layout to be used for the admin user interface
  admin_helpers:            []                              # if you need to add extra helpers
  before_filters:           []                              # filters from application controller
  skip_before_filters:      []                              # filters from application controller
  after_filters:            []                              # filters from application controller
  user_info:
    enabled:                false                           # if disabled, will fallback onto translators
    class_name:             User                            # class name for the User object type
    current_user_method:    current_user                    # provides current user object
    methods:                                                # User object methods mapping
      id:                   id
      name:                 name                            
      gender:               gender
      admin:                admin?
      guest:                guest?
      mugshot:              mugshot
      link:                 link
      locale:               locale

You need to map your User object methods to the methods defined in the config file under the user_info section. Alternatively, you could overload any of the config properties in the Tr8n::Config class. You can do this by creating a new

config/initializers/tr8n.rb

And overloading any of the Tr8n::Config methods, as follows:

Rails.configuration.after_initialize do 
  class Tr8n::Config
    def self.enabled?
      true  
    end

    def self.user_name(user)
      user.name
    end

    def self.user_gender(user)
      user.gender
    end
  ...
end

end

The current_locale method should not only return back the locale, but should also be able to store and preserve the locale. If the method is not defined, then Tr8n will fallback onto the default implementation which stores the selected locale in the session. You can implement your own method of determining and returning the locale of the site. For example, the locale can be configured as a subdomain or a site extension. Below is an example of the current_locale method that sets the locale from a parameter, uses user’s locale or uses browser’s preffered locale:

def current_locale
   if params[:locale]
     session[:locale] = params[:locale]
     session[:save_locale] = true
   elsif !current_user.guest? and !current_user.locale.nil?
     session[:locale] = current_user.locale
   elsif session[:locale] == nil
     session[:locale] = tr8n_user_preffered_locale
     session[:save_locale] = (session[:locale] != Tr8n::Config.default_locale)
   end

   if session[:save_locale] and not current_user.guest?
     current_user.changed_language!(session[:locale])
     session[:save_locale] = nil
   end

   session[:locale]
end

tr8n_user_preffered_locale returns back the first available locale supported by Tr8n that the browser has requested in the order of the browser’s language preferences.

There are a few other settings in config.yml that you may want to review. Those settings will be covered in the later sections.

Enabling Caching¶ ↑

It is best to run Tr8n with some kind of caching support. One of the best solutions is to use Memcached for caching. Tr8n comes with support for any Rails caching methods as well as a mechanism to integrate a custom caching adapter to address your specific needs.

caching:
  enabled:                  true
  adapter:                  ActiveSupport::Cache
  store:                    [mem_cache_store, 'localhost:11211']
  version:                  1 # you can change the version to invalidate the cache

If you choose to use the Rails caching support, then use the ActiveSupport::Cache as the adapter. You can choose any one of the following cache stores:

• memory_store

• file_store

• drb_store

• mem_cache_store, ‘localhost:11211’

If you have a custom cache solution, you can implement a custom adapter class and provide your custom implementation. The class must implement the following methods:

class CustomCacheAdapter
  def self.fetch(key, options = {})
    CACHE.get_or_add(key) do 
      yield
    end
  end

  def self.delete(key, options = nil)
    CACHE.delete(key)
  end
end

Then you can set the caching adapter to your custom class name.

The Tr8n version parameter is used to expire and rotate cached values. For example, if you have removed a lot of old keys from your system, you may want to increment the cache version. This will remove the old values from the cache and replace them with the new values. When a translation key is loaded into cache, Tr8n will aslo update the verified_at timestamp of the key. This way you can keep track of which keys have been accessed and when. So you can periodically delete the old, unused keys.

Enabling Logger¶ ↑

By default, Tr8n will use its own logger. If you set it to false, it will use default Rails logger.

logger:
  enabled:                  true
  log_path:                 log/tr8n.log          # location of the log file
  enable_paranoia_mode:     true                  # logs every translator action