README.md

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.