-
Notifications
You must be signed in to change notification settings - Fork 1
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.
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.
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.
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.
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