LocalizerRails

Just some handy utilities to manage site localization, generator provided

1. set/retrieve language if none selected
2. build language menu (bootstrap 3+ compatible)
3. [optional] convenience partials and Kaminari pluralization patch (up to v0.16.3)

Rails version: 4+

Gemfile:

gem 'localizer_rails', '0.1.2'

Style:

@import 'localizer_rails/localizer_rails';

OR

require localizer_rails

finds the best-match for I18n.locale through a cascading search:

1. params[:locale]
2. cookies['locale']
3. current_user.locale (if defined)
4. session[:locale]
5. accepted_locales (scans browser's HTTP_ACCEPT_LANGUAGE)
6. I18n.default_locale (if everything else fails)

and sets values accordingly (cookies, link_to, ...)

• use in before_action:

before_action LocalizerRails::SetLoc

• use in routes, too:

scope ":locale", locale: /#{LocalizerRails.active_locales.join("|")}/ do ...
  ...
  match '*path', to: redirect { |p, req|
                   Localizer.set_locale(req)
                   if( ! (Localizer.active_locales.any? { |word| req.path.starts_with? ("/#{word}/") }) )
                     "/#{I18n.locale}#{req.path}"
                   else
                     if( Rails.env.production? || !Rails.application.config.consider_all_requests_local )
                       ## SHOW custom 404
                       Rails.application.routes.url_helpers.error_404_path(:locale => I18n.locale)
                     else
                       ## let Rails handle this with default 404
                       raise ActionController::RoutingError.new('Not Found')
                     end
                   end
                 },
                 via: [ :get, :post, :patch, :delete ],
                 status: '301'

builds an hash of locale key/value pairs useful to build a locale_menu

[optional] override and edit config/localizer_rails/lang_countries.yml

:da:
  :lang_default:    'Danish'
  :lang_local:      'Dansk'
  :country_default: 'Denmark'
  :country_local:   'Danmark'
  :country_code:    'DK'
:fo-FO:
  :lang_default:    'Faroese'
  :lang_local:      'Føroyskt'
  :country_default: 'Faroe Islands'
  :country_local:   'Føroyar'
  :country_code:    'FO'

where

• :lang_default: language name in default language (ex.: english)
• :lang_local: language name in local language/alphabet

xtra country specs, use if locale_menu lists countries instead of languages:

• :country_default: country name in default language (english)
• :country_local: country name in local language/alphabet
• :country_code: country ISO code

NOTE: languages will be listed ONLY if included in i18n.available_locales

[optional] edit LI structure and attributes in

app/views/localizer_rails/_item[.bootstrap].html.erb

[optional] edit LI elements and their display order in

app/views/localizer_rails/_elements.html.erb

CONFIGURATION

[optional] override and edit config/initializers/localizer_rails/localizer_rails_prefs.rb

LocalizerRails::Conf.configure do |conf|
    conf.variable_name = value
    ...

OPTIONS:

• conf.merge_lang_countries_tables (boolean)
  if a copy of the lang_countries.yml file is found in your application you can force the engine to use ONLY your file or the MERGED hash

  • the engine's file will be used if no override lang_countries file is found in your application
  • defaults to true (= merge files if override file is found)

• conf.all_available_locales (boolean)
  

  • set to true if
    • you want to load all locales in I18n.available_locales
    • you have already selected a limited bunch of locale files to be loaded in your config.i18n.available_locales = [:en,'es-CO', :de]
  • set to false if you want to specify the locale files in the custom list below (conf.active_locales)
  • defaults to true

  Hint: install [rails-i18n] (https://github.com/svenfuchs/rails-i18n) to add pluralization rules and a bunch of translated language files.

• conf.active_locales (:sym)
  define which locales your application will use

  • locales not included in I18n.available_locales will be ignored
  • defaults to [I18n.default_locale]

• conf.country_downcase (boolean)
  load locale files depending on your setup:

  • true = use browser's HTTP_ACCEPT_LANGUAGE format (en-us)
  • false = use ISO rules in your [localefile].yml (en-US) as in rails-i18n locale files
  • defaults to false

• conf.display_local_language (boolean)
  display menu language names in their own idiom and alphabet or always in the default site language:

  • true = 'Italiano', 'Español', 'Deutsch', ...
  • false = 'Italian', 'Spanish', 'German', ... (or whatever language your config.i18n.default_locale defaults to)
  • defaults to false

• conf.use_bootstrap (boolean)
  use bootstrap-style in locale_menu (you need to include bootstrap-sass (or similar) in your gemfile and import it in your stylesheet), as opposed to this engine's provided style

  • defaults to false (= use engine's style)

• conf.cookie_expires (Date | nil)
  set a custom expiration date for the :cookies[:locale]

  • Date can be in the format 20.year.from_now.utc (same as cookies.permanent)
  • defaults to nil (session length)

• conf.store_in_session (boolean)
  store I18n.locale also in session?

  • defaults to false

[Kaminari] (https://github.com/amatsuda/kaminari) (up to current v0.16.3) handles pluralization through pluralize.
In case of localization with foreign languages (eventually with multiple plural forms, such as cyrillic) this method often outputs incorrect results.
The generator installs an override for Kaminari's ActionViewExtension#page_entries_info, following a bright hint by Linuus found on GitHub (see 'Credits' below).
The patch uses model_name and AR's count.

Note: You need to install the [kaminari ~> 0.16] (https://github.com/amatsuda/kaminari) and [kaminari-i18n] (https://github.com/tigrish/kaminari-i18n) gems.

The generator installs a raw partial with the code for a Bootstrap 3+ NAVBAR featuring the language menu, modify it to suit your needs.

Note: You need to install [bootstrap-sass] (https://github.com/twbs/bootstrap-sass) or a similar gem.

Type the following lines in your Terminal application to see a working example:

$ cd path-to-your-dir
$ git clone https://github.com/gbellono/localizer_rails.git
$ cd path-to-your-dir/localizer_rails
$ bundle install
$ rails s

Check out comments included in the code.

Note: to simulate the 'production' error handling remember to set config.consider_all_requests_local in config/environments/development.rb to false.

Thanks to Linuus for suggesting a viable way to patch Kaminari's handling of pluralization issues.

Copyright (c) 2015 by Giovanni Bellono

See LICENSE for details.