I18nLazyScope is a tiny library that lets you use lazy lookup and custom scoping in your locale files when localising strings in your Ruby applications. This means quicker translations without sacrificing the structure of your locale files.
The library inserts a customisable namespace in the scope for you, just below the locale. The following table illustrates the difference between I18nLazyLookup and Rails when resolving lazy lookup keys.
I18nLazyLookup | Rails/I18n Lazy Lookup | |
---|---|---|
Controllers | locale.controllers.controller_name.action_name.key |
locale.controller_name.action_name.key |
Mailers | locale.mailers.mailer_name.action_name.key |
locale.mailer_name.action_name.key |
Views | locale.views.template_or_partial_path.key |
locale.template_or_partial_path.key |
Lazy lookup is a feature that ships with Rails and the I18n gem. It allows you to translate strings without explicitly qualifying their entire scope. For example, consider the following code that lives in show.html.erb
inside app/views/users
, and that your application's locale is English.
<%= t('.welcome_message') %>
Rails automatically converts .welcome_message
to en.users.show.welcome_message
. This saves you from having to type users.show
, which is handy if you have lots of translations. But it forces you structure your locale files the way Rails prefers.
en:
users:
show:
welcome_message: "You are such a star!"
The above structure can get messy because en.users
can refer to a view or a controller, and it feels wrong for users
to be floating under the top level namespace. Most developers prefer to keep their translations under a scope.
en:
controllers:
users:
show:
success: "Yay!"
views:
users:
show:
welcome_message: "Yay!"
So applications with lots of translations will find it hard to take advantage of lazy lookup. Wouldn't it be great if you could use lazy lookup and a custom namespace? Well, now you can.
<%= t_scoped('welcome_message') %>
The scoped_t
method will automatically convert welcome_message
to en.views.show.welcome_message
. And you can customise the views
part of the scope to anything you like. Your locale file would contain the views
namespace to keep view translations organised as demonstrated above.
I18nLazyScope provides a wrapper method around the translate
and t
methods in Rails and the Ruby I18n gem.
Add this line to your application's Gemfile:
gem 'i18n_lazy_scope'
And then execute:
$ bundle
Or install it yourself as:
$ gem install i18n_lazy_scope
Call the t_scoped
method instead of t
, or translate
, and make sure you have the corresponding keys in your locale files. Say you are in app/views/users/show.html.erb
.
<%= t_scoped 'greeting' %>
en:
views:
users:
show:
greeting: "Hello!"
The library inserts a top level name in the scope for you. Here are the defaults:
- Controllers:
locale.controllers.controller_name.action_name.key
- Mailers:
locale.mailers.mailer_name.action_name.key
- Views:
locale.views.template_or_partial_path.key
I18nLazyScope accepts a configuration block. This is an example that you might put into a Rails initializer at config/initializers/i18n_lazy_scope.rb
:
I18nLazyScope.configure do |config|
# Resolves lazy lookup to `locale.my.custom.scope.controller_name.action_name.key`
config.action_controller_scope = [:my, :custom, :scope]
# Resolves lazy lookup to `locale.my.custom.scope.mailer_name.action_name.key`
config.action_mailer_scope = [:my, :custom, :scope]
# Resolves lazy lookup to `locale.my.custom.scope.template_or_partial_path.key`
config.action_view_scope = [:my, :custom, :scope]
end
It works exactly as it would if you call t
or translate
.
<%= t_scoped 'greeting', name: @user.name %>
en:
views:
users:
show:
greeting: "Hello, %{name}!"
If you have to customise the scope on individual basis, then you should use t
and translate
that ship with Rails or the I18n gem. Scoping on individual basis defeates the point of this gem. This gem isn't meant to replace the I18n; it's a tiny wrapper that depends on it.
t_scoped(key, **args)
I18nLazyScope requires Ruby 2.0 because it uses the double splat **
operator to capture all keyword arguments.
I18nLazyScope uses semantic versioning.
- Fork it ( https://github.com/abitdodgy/i18n_lazy_scope/fork )
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create a new Pull Request