Translator makes using the internationalization (i18n) facility introduced in Rails 2.2 simpler through:

• keeping your code DRY using simple conventions

• make testing easier to catch missing keys

• supplying a graceful “fallback” mode when a translation is missing in a user’s locale

The (very!) helpful I18n library finds keys in locale bundles (and more), but doesn’t know anything about Rails applications. Applications that have a lot of strings need a system of keeping them organized. Translator adds smarts to controllers, views, models & mailers to follow a simple convention when finding keys. Having a convention for the hierarchy of keys within locale bundles that makes it easier to code and maintain, while still using the capabilities of the underlying I18n library. (Note: Translator does not depend on how the actual YAML/Ruby files are stored in the filesystem.)

Quick example - if you follow the key convention of structuring your locale bundle like:

blog_posts: # controller
  show: # action
    title: "My Awesome Blog Post"
    byline: "Written by {{author}}"

Then when writing the BlogPostsController.show action you can just use t('title') to fetch the string (equivalent to I18n.translate('blog_posts.show.title')). Similarly, in the show.erb template you can get use t('byline', :author => "Mike"). This extends to models and mailers as well. As they say, “Look at all the things I’m not doing!”

To install this plugin into your Rails app (2.2 or 2.3+):

./script/plugin install git://github.com/graysky/translator.git

To install as a gem add the following to config/environment.rb:

config.gem "graysky-translator", :lib => "translator", :source => "http://gems.github.com"

The RDocs are online or can be generated via rake rdoc in the translator plugin directory.

Please file an issue in the Github bug tracker or contact me.

Translator adds an enhanced translate (or shorter t) method to:

• ActionController

• ActionView

• ActiveRecord

• ActionMailer

In the spirit of Rails, the convention for a hierarchy of keys borrows the same layout as the typical “views” directory. A sample Blog application is used as an example.

For controllers/views/mailers it is:

en: # locale
  # the controller name
  blog_posts:
    # the action name
    index:
      key: "Hello World"

    # partials w/o underscore (template "_footer.erb")      
    footer: 
      key: "My Copyright"

  # "layouts" is fixed
  layouts:
    # the layout name (template "main.erb")
    main:
      key: "My App Name"

  # for shared partials called like: render :template => "shared/user"
  # where "shared" is the directory name
  shared:
    # partial name w/o underscore (template "_user.erb")
    user:
      key: "Foo"

  # the full mailer name
  blog_comment_mailer:
    # the method name (does not include "deliver")
    comment_notification:
      subject: "New Comment"

For models it is:

en:
  # The model name
  blog_post:
    key: "Custom validation error"

When a key is looked up, Translator adds extra scoping to the lookup based on where it is called from. For:

• Controllers & views the scope includes [:controller_name, :action_name]. (For shared partials it is [:template_path, :partial_name])

• Mailers the scope includes [:mailer_name, :method_name]

• Models the scope includes [:model_name]

But what happens if you want to share strings across a controller? Let’s say you have error messages that are set in flash notices and then are shared between actions in a controller defined in the locale bundle like:

blog_posts:
  errors:
    permission_denied: "Permission denied to read this blog post"

If Translator doesn’t find the original key, it will remove a layer of scoping and try again. So if in our Blogs controller show action we want to set a flash[:error] to a permission denied message it can find the string by calling t('errors.permission_denied'). Translator will first look for “blog_posts.show.errors.permission_denied”, which doesn’t exist. So it will then try to find “blog_posts.errors.permission_denied” and return the correct string. This can be used to create greater levels of scoping, or to force finding global strings (e.g. t("global.app_name")).

Let’s say you’ve extracted all your English strings, and even had them translated to Spanish to make your Spanish-speaking users extra happy. Then you have a brilliant idea for a new feature that needs to go live before the new pages are translated into Spanish. You still want your Spanish-speaking users to keep seeing the site in Spanish, but for these new pages to fallback to English. (While not exactly ideal, it is better than having “translation missing” messages or not externalizing strings.) To enable this fallback behavior:

# In the configuration
I18n.default_locale = :en

# Enable the fallback mode to try :es first, then :en
Translator.fallback(true)

# Set in the code based on user's preference, their IP address, etc.
I18n.locale = :es

# Everything else stays the same, but after Translator tries the normal scoping rules
# in Spanish (:es), it will apply the same rules for the default locale (:en)
t('page_title')

• Translator.strict_mode will cause an exception to be raised for any missing translations. Enabled by default during testing to help find mistyped or accidently forgotten keys. It can be disabled by calling Translator.strict_mode(false) (in test_helper for example).

• assert_translated takes a block and asserts that all lookups within that block have real translations. It is a more targeted version of strict_mode. Example:

  assert_translated do
    # Will assert that all keys find valid translations inside the block
    get :show
  end
  

• If you’re trying to avoid hard-coding strings in tests, you can still use the lookup that is added to models and controllers:

  # Inside a test exercising a BlogPostController (@controller created in setup method)
  get :show, :id => 123
  # the byline should be in the body - uses @controller to make lookup easy (automatically knows controller name and action)
  assert_match @controller.t('byline', :name => "Mike"), @response.body
  

• Pseudo-translation mode. Pseudo-translation wraps all extracted strings with leading and trailing text so that you can spot if you forgot any. It can be enabled by Translator.pseudo_translate (in an environment file or locale.rb for example). It does not change the lookup process (e.g. t('blog_title')) but will transform the returned string from “My Blog” to “[[ My Blog ]]”. The text that is prepended / appended can be set by calling Translator.pseudo_prepend = "@@" (or append). Pro Tip: This can also be used to see how a layout will display in a localized language that is longer than the default. or example, German words tend to be significantly longer than their English equivalents. By padding all strings you can test how a layout will adapt and make changes.

• Rake task to validate that YAML files are, in fact, valid YAML. Useful when getting back translations from a 3rd party service, this can be a quick way to catch a missing quote. Run like rake i18n:validate_yml and it will check all .yml files below RAILS_ROOT/config/locales.

1.0.0 - 4/17/2009 - Declaring 1.0 after successfully using Translator in production.

Bug reports welcome. Patches very welcome.

Copyright © 2009 Mike Champion, released under the MIT license.