ruby script/plugin install git://github.com/iain/i19n.git

Basic usage
=================

You can use I19n just as I18n. So simple translations will be done as:

  I19n.t(:foo)

Notice that translate and t are aliases. In the next few sections I’ll tell you about all the extras you can add to I19n and how to turn them on or off, or change their behaviour.

Multiple arguments
------------------------

You can scope a bit easier than normal. These two calls are the same:

  I19n.t(:foo, :bar)
  I19n.t(:bar, :scope => :foo)

You can also easily specify a default for the translation, by making the last argument a string. The following calls are the same:

  I19n.t(:foo, "bar")
  I19n.t(:foo, :default => "bar")

If you specify a default option yourself, it won’t do this. Which makes these two methods the same:

  I19n.t(:foo, "bar", :default => "baz")
  I19n.t(:foo, "bar", "baz")
  I19n.t(:foo, :bar,  :default => "baz")

Why? It’s shorter and in future versions of I18n, the dotted scope separator will probably be changable. I18n.t("foo.bar") might not be equal to I18n.t(:foo, :scope => :bar) anymore. And since scoping is so widely used, I don’t like using a hash option.

You can disable this function like this:

  I19n::Settings.configure do |config|
    config.multiple_arguments = false
  end

Views and helpers
=======================

Automatic scopes are added when you call translate in views or helpers. After doing a few projects with i18n I found that too tightly scoped keys are a nightmare to maintain, so I19n will scope on a "controller" level.

This means that all calls from views are scoped accoriding to their controller’s name. It doesn’t matter if you’re in index, in edit, show or some partial. Even rendering a view or partial from another controller won’t matter.

For helpers this means that keys are scoped according to their name, no matter from where the helper method is being called. We don’t want to duplicate translations from say application_helper to every view it’s called from, now do we?

These translations also "fall back" to a more global scope. You might have some common words that may appear all over the place. ("cancel" is probably not controller-specific, for instance).

By default all translations from views and helpers are wrapped in a "views" scope. To put it into code, these two are equal (when called from views for the people-controller):

  I19n.t(:foo)
  I18n.t("people.foo", :scope => :views, :default => :foo)

It will take your own specified scope and default into account:

  I19n.t(:foo, :scope => :bar, :default => "Foo!")
  I19n.t("people.foo", :scope => [:views, :bar], :default => [:foo, "Foo!"])

To summorize, this is what your locale file might look like. The numbers are in the order they will be tried. If that translation is not found, it will try the next (that is wat we call fallback):

  en:
    views:
      foo: "" # 2
      people:
        foo: "" # 1

You can turn off fallbacks and change the scope in the configuration. To turn off the scope, set it to false. The defaults are:

  I19n::Settings.configure do |config|
    config.view_scope = :views
    config.view_fallback = true
  end

Raising errors
=======================

Set this to a lambda. It defines when I19n should raise. I think you might want to do this in test and development mode, which is the default, but I’ll let you have the final word. This is the default:

  I19n::Settings.configure do |config|
    config.raise_when = lambda { Rails.env.development? or Rails.env.test? }
  end

Writing missing translations
-----------------------------------

When a translation is missing, it can write it to a yaml file, so you can collect all missing keys after running some tests. If your code is properly tested, it should have at least seen all translation calls.

By default this is turned on and writes the file in RAILS_ROOT/tmp/missing_en.yml

To change this behaviour, you can set a boolean to the write_missing option and a lambda to the missing_file option. So the defaults are:

  I19n::Settings.configure do |config|
    config.write_missing = true
    config.missing_file = lambda { File.join(RAILS_ROOT, "tmp", "missing_#{I18n.locale}.yml") }
  end

When a missing translations file is written, it fills in the interpolation arguments used.

  I19n.t(:hello, :name => user.name)

Results in this locale file:

  en:
    hello: "{{name}}"

Caching
================

"Cache is king!" - dkln (github.com/dkln)

Every translation can be cached. This is on by default, but can be turned off by setting the "perform_caching" option to false. It uses the default Rails cache so configure your cache in there.

Here you can see it in action:

  Loading production environment (Rails 2.3.2)
  >> I19n.translate(:hello)
  Cache miss: translate/[:hello, {:raise=>true, :scope=>[]}] ({})
  Cache write (will save 1.90ms): translate/[:hello, {:raise=>true, :scope=>[]}]
  => "Hello world"
  >> I19n.translate(:hello)
  Cache hit: translate/[:hello, {:raise=>true, :scope=>[]}] ({})
  => "Hello world"

There is currently no advanced documentation for this plugin.