MiniI18n
Minimalistic I18n library for Ruby
MiniI18n
is a simple, flexible and fast Ruby Internationalization library. It supports localization, interpolations, pluralization, fallbacks, nested keys and more.
Translations should be stored in YAML
or JSON
files and they will be loaded in an in-memory Hash
.
en:
hello: 'Hello'
>> MiniI18n.t(:hello)
=> "Hello"
Installation
Add this line to your application's Gemfile:
gem 'mini_i18n'
And then execute:
> bundle install
Or install it yourself as:
> gem install mini_i18n
Usage
You should use the configure
method to setup your environment:
MiniI18n.configure do |config|
# Path to your translation files.
config.load_translations(__dir__ + '/translations/*')
# Default locale.
config.default_locale = :pt
# Available locales in your application.
config.available_locales = [:en, :es, :fr, :pt]
# If given key is empty, defaults to the default_locale.
config.fallbacks = true
# Custom separator for nested keys.
config.separator = '/'
# Custom pluralization rules, by locale.
config.pluralization_rules = {
es: -> (n) { n == 0 ? 'zero' : 'other' },
fr: -> (n) { ... }
}
end
You can also use the following format:
MiniI18n.load_translations(__dir__ + '/translations/*')
MiniI18n.default_locale = :en
Examples usage:
>> MiniI18n.t(:hello)
=> "Hello"
>> MiniI18n.t(:hello, locale: :fr)
=> "Bonjour"
>> MiniI18n.locale = :fr
=> :fr
>> MiniI18n.t(:hello)
=> "Bonjour"
>> MiniI18n.t(:non_existent_key)
=> nil
>> MiniI18n.t([:hello, :bye])
=> ["Hello", "Bye"]
>> MiniI18n.t('app.controllers.not_found')
=> "Not found!"
The t
method can be also used as translate
:
MiniI18n.translate(:hello)
It accepts the following options:
locale
>> MiniI18n.t(:hello, locale: :es)
=> "Hola"
You can also get multiple locales at once by passing an array:
>> MiniI18n.t(:hello, locale: [:en, :fr, :es])
=> ["Hello", "Bonjour", "Hola"]
scope
>> MiniI18n.t('application.views.welcome')
=> "Welcome"
>> MiniI18n.t('welcome', scope: 'application.views')
=> "Welcome"
Read more details about nested keys in this section.
default
>> MiniI18n.t(:non_existent_key, default: 'default value')
=> "default value"
count
>> MiniI18n.t('notifications', count: 0)
=> "no unread notifications"
Read more details in the Pluralization section.
Nested Keys
You can use a custom separator when accessing nested keys (default separator is .
):
en:
app:
controllers:
not_found: "Not found!"
MiniI18n.t('app.controllers.not_found')
MiniI18n.separator = '/'
MiniI18n.t('app/controllers/not_found')
Interpolation
You can also use variables in your translation definitions:
en:
hello_with_name: "Hello %{name}!"
>> MiniI18n.t(:hello_with_name, name: 'John Doe')
=> "Hello John Doe!"
Pluralization
You should define your plurals in the following format (default pluralization rule accepts the keys: zero
, one
and other
):
en:
notifications:
zero: 'good job! no new notifications'
one: '1 unread notification'
other: '%{count} unread notifications'
Then, you should call the method with the count
option:
>> MiniI18n.t('notifications', count: 0)
=> "good job! no new notifications"
>> MiniI18n.t('notifications', count: 1)
=> "1 unread notification"
>> MiniI18n.t('notifications', count: 5)
=> "5 unread notifications"
Custom pluralization rules
You are also able to customize how plurals are handled, by locale, defining custom pluralization rules. Example:
MiniI18n.pluralization_rules = {
es: -> (n) {
if n == 0
'zero'
elsif (1..3).include?(n)
'few'
elsif (4..10).include?(n)
'many'
else
'other'
end
}
}
Now, in your translation files, you should define content for those keys:
es:
notifications:
zero: 'no tienes nuevas notificaciones'
few: 'tienes algunas notificaciones pendientes ...'
many: 'tienes %{count} notificaciones!'
other: 'alerta!! %{count} notificaciones!'
And then, you get:
>> MiniI18n.t('notifications', count: 0)
=> "no tienes nuevas notificaciones"
>> MiniI18n.t('notifications', count: 2)
=> "tienes algunas notificaciones pendientes ..."
>> MiniI18n.t('notifications', count: 5)
=> "tienes 5 notificaciones!"
>> MiniI18n.t('notifications', count: 20)
=> "alerta!! 20 notificaciones!"
Localization
You can also use the MiniI18n.l
(or the long version MiniI18n.localize
) method to localize your dates, time and numbers.
Dates and time
It uses strftime
under the hood. You should provide your localizations using the following format:
en:
date:
formats:
default: "%A %d, %B, %Y"
short: "%d %b %y"
>> MiniI18n.l(Date.new(2018, 8, 15))
=> "Wednesday 15, August, 2018"
>> MiniI18n.l(Date.new(2018, 8, 15), format: :short)
=> "15 Aug 18"
You can check a full example of all necessary and useful keys in this file.
Numbers
To localize your numbers, you can provide the following keys:
en:
number:
format:
delimiter: ','
separator: '.'
as:
currency: '%{number} $'
>> MiniI18n.l(1000.25)
=> "1,000.25"
>> MiniI18n.l(1000, as: :currency)
=> "1,000 $"
>> MiniI18n.l(1000, as: :currency, locale: :es)
=> "1.000 €"
TIP By using the :as
option you can build custom full sentences with formatted numbers, like:
en:
number:
as:
final_price: 'Final price: %{number} $'
percentage: '%{number}%'
>> MiniI18n.l(1000, as: :final_price)
=> "Final price: 1,000 $"
>> MiniI18n.l(70.5, as: :percentage)
=> "70.5%"
Development
Any kind of feedback, bug report, idea or enhancement are much appreciated.
To contribute, just fork the repo, hack on it and send a pull request. Don't forget to add specs for behaviour changes and run the test suite:
> bundle exec rspec
License
Copyright (c) Marc Anguera. MiniI18n is released under the MIT License.