Part One: Discussion

[Update] (2010-09-16): "Entries to assist translators":#update_1

Part Two: Quick Reference

You're building a Rails 3 app.
It needs to support internationalization (I18n).
No problem. Rails 3 supports internationalization.

You can use translate(key) or t(key).

%h2= t('hello')

It looks up the key in config/locales/en.yml:

    Hey y'all


Hey y'all

(Aside: I will be using en.yml throughout this post, any language file could be used.)

But, we're using Rails. We expect conventions. And smart defaults.
I shouldn't need to use t(key) wherever I need translations.

h2. My expectations

1. Items that can be internationalized should have smart defaults. I should not have to make an entry like:

pre. labels:
name: Name

p(update). Update 2010-09-16: My co-worker, Chris Cahoon, shares a great point. We probably want to make entries like name: Name, to assist translators. Allowing them to just go down the line translating each entry in the file. Otherwise, many items will not be translated. This makes tools like "Tolk": especially helpful.

2. Similarly, there should be fallback/common/generic entries. If an error message doesn't exist for this validation, on this specific model, use the generic message for this validation. If a generic message doesn't exist in the localization file, fall back to the smart default.
The generic:

pre. create_success: "%{model} created"
create_fail: "The %{model} could not be created:"

The specific:

pre. tour_versions:
success: Your tour was successfully published.

3. Where possible, libraries should follow the rails conventions instead of inventing their own. This allows me to switch (or simply remove) libraries and I18n still works.

h2. What I Found

Platformatec has a "nice listing of Rails I18n conventions":

On our project, we use simple_form, inherited_resources, and cancan.
Each one has a convention for I18n.
Each one different.

Luckily, the functionality doesn't overlap... much.

Rails covers error message defaults, attributes, submit buttons, and labels.
InheritedResources covers flash (using Responders).
SimpleForm deals with label, hint, and error.
cancan presents a 'not authorized' message.

So... expectations #1 & 2 are generally covered. But, sadly, #3 is not.

A Quick Reference for each library will be provided after this commercial break...