fdl_translator

= Translator - i18n tooling for Rails

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 Problem

The (very!) helpful I18n[http://api.rubyonrails.org/classes/I18n.html] 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!"

== Installation

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"

== RDocs

{The RDocs are online}[http://graysky.github.com/translator/rdoc/index.html] or can be generated via rake rdoc in the translator plugin directory.

== Problems or Suggestions

Please {file an issue in the Github bug tracker}[http://github.com/graysky/translator/issues/] or contact me.

== Simple +translate+ Everywhere

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"

=== Key Lookup

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")).

== Graceful Locale Fallback

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')

== Testing Help

• 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.

== Changelog

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

Bug reports welcome. {Patches very welcome}[http://github.com/graysky/translator].

Copyright (c) 2009 {Mike Champion}[http://graysky.org], released under the MIT license.