i18n 0.9.5 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '09643c444c40fe98042352f7f3e3e2df08e15ec5bee9f3d658b3e2fdeeb627a7'
-  data.tar.gz: b924468907cca779632052d4ec166c79a9fc10f305a4a4f2c7be6ffeef6a5e47
+  metadata.gz: 2b03b84d726d3cafa7ea2ecaa6f258cb911696c338cb32c769f71b6d62ca5fb5
+  data.tar.gz: 7a489bf447e9fedee8fd043cc8ba324c0afc0c34701fbfeff5f15b1c1f4fa6b4
 SHA512:
-  metadata.gz: 338556073a2c02752c1d3e5e3ba5ed70cb692d814ab05aca5a3d70ef3ee013aa3bb9d5cfc6aecbbd2a93e4732105a4c05c70968ea7f955c169cf69ad97462796
-  data.tar.gz: a0a4eff7b73ac32730dae8b77f609c4cc6fca9b6c2f46d81f42d992e10dd8d1467dbc28985b38769f9cab2f6ac1d67e4309eb8a8df65d9fc38baa39b65343f18
+  metadata.gz: 534659c40a8df9eb3fd9a123b779de0f1b66471ecd3fb35e2083128193f51aeea95df6aad06039b6309932a6efb3426c525a8759e70c1104754fdd921732d6cd
+  data.tar.gz: caddebe447a797be3dde1607e74d826588ee13ee1317c6abfbb08cbd8a22d79a6aa10a84d3fd21fa45ca9348317aa0e0aafe1c408d4e1c989fbee7f09cd87606

data/README.md

@@ -1,12 +1,55 @@
 # Ruby I18n
 
-[![Build Status](https://api.travis-ci.org/svenfuchs/i18n.svg?branch=master)](https://travis-ci.org/svenfuchs/i18n)
+[![Build Status](https://api.travis-ci.org/ruby-i18n/i18n.svg?branch=master)](https://travis-ci.org/ruby-i18n/i18n)
 
 Ruby Internationalization and localization solution.
 
-[See the Rails Guide](http://guides.rubyonrails.org/i18n.html) for an example of its usage. (Note: This library can be used independently from Rails.)
+Currently maintained by @radar.
 
-Features:
+## Usage
+
+### Rails
+
+You will most commonly use this library within a Rails app.
+
+[See the Rails Guide](http://guides.rubyonrails.org/i18n.html) for an example of its usage.
+
+### Ruby (without Rails)
+
+If you want to use this library without Rails, you can simply add `i18n` to your `Gemfile`:
+
+```ruby
+gem 'i18n'
+```
+
+Then configure I18n with some translations, and a default locale:
+
+```ruby
+I18n.load_path << Dir[File.expand_path("config/locales") + "/*.yml"]
+I18n.default_locale = :en # (note that `en` is already the default!)
+```
+
+A simple translation file in your project might live at `config/locales/en.yml` and look like:
+
+```yml
+en:
+  test: "This is a test"
+```
+
+You can then access this translation by doing:
+
+```ruby
+I18n.t(:test)
+```
+
+You can switch locales in your project by setting `I18n.locale` to a different value:
+
+```ruby
+I18n.locale = :de
+I18n.t(:test) # => "Dies ist ein Test"
+```
+
+## Features
 
 * translation and localization
 * interpolation of values to translations (Ruby 1.9 compatible syntax)
@@ -19,27 +62,21 @@ Features:
 * custom exception handlers
 * extensible architecture with a swappable backend
 
-Pluggable features:
+## Pluggable Features
 
 * Cache
 * Pluralization: lambda pluralizers stored as translation data
 * Locale fallbacks, RFC4647 compliant (optionally: RFC4646 locale validation)
-* [Gettext support](https://github.com/svenfuchs/i18n/wiki/Gettext)
+* [Gettext support](https://github.com/ruby-i18n/i18n/wiki/Gettext)
 * Translation metadata
 
-Alternative backends:
+## Alternative Backend
 
 * Chain
 * ActiveRecord (optionally: ActiveRecord::Missing and ActiveRecord::StoreProcs)
 * KeyValue (uses active_support/json and cannot store procs)
 
-For more information and lots of resources see [the 'Resources' page on the wiki](https://github.com/svenfuchs/i18n/wiki/Resources).
-
-## Installation
-
-```
-gem install i18n
-```
+For more information and lots of resources see [the 'Resources' page on the wiki](https://github.com/ruby-i18n/i18n/wiki/Resources).
 
 ## Tests
 
@@ -67,6 +104,10 @@ the API definition test methods in test/api/tests.
 All other test cases (e.g. as defined in test/backend, test/core_ext) etc.
 follow the usual test setup and should be easy to grok.
 
+## More Documentation
+
+Additional documentation can be found here: https://github.com/svenfuchs/i18n/wiki
+
 ## Authors
 
 * [Sven Fuchs](http://www.artweb-design.de)

data/lib/i18n/backend/base.rb

@@ -1,14 +1,17 @@
+# frozen_string_literal: true
+
 require 'yaml'
+require 'json'
 require 'i18n/core_ext/hash'
-require 'i18n/core_ext/kernel/suppress_warnings'
 
 module I18n
   module Backend
     module Base
+      using I18n::HashRefinements
       include I18n::Backend::Transliterator
 
       # Accepts a list of paths to translation files. Loads translations from
-      # plain Ruby (*.rb) or YAML files (*.yml). See #load_rb and #load_yml
+      # plain Ruby (*.rb), YAML files (*.yml), or JSON files (*.json). See #load_rb, #load_yml, and #load_json
       # for details.
       def load_translations(*filenames)
         filenames = I18n.load_path if filenames.empty?
@@ -17,11 +20,11 @@ module I18n
 
       # This method receives a locale, a data hash and options for storing translations.
       # Should be implemented
-      def store_translations(locale, data, options = {})
+      def store_translations(locale, data, options = EMPTY_HASH)
         raise NotImplementedError
       end
 
-      def translate(locale, key, options = {})
+      def translate(locale, key, options = EMPTY_HASH)
         raise I18n::ArgumentError if (key.is_a?(String) || key.is_a?(Symbol)) && key.empty?
         raise InvalidLocale.new(locale) unless locale
         return nil if key.nil? && !options.key?(:default)
@@ -68,7 +71,7 @@ module I18n
       # Acts the same as +strftime+, but uses a localized version of the
       # format string. Takes a key from the date/time formats translations as
       # a format argument (<em>e.g.</em>, <tt>:short</tt> in <tt>:'date.formats'</tt>).
-      def localize(locale, object, format = :default, options = {})
+      def localize(locale, object, format = :default, options = EMPTY_HASH)
         if object.nil? && options.include?(:default)
           return options[:default]
         end
@@ -92,12 +95,21 @@ module I18n
       end
 
       def reload!
+        eager_load! if eager_loaded?
+      end
+
+      def eager_load!
+        @eager_loaded = true
       end
 
       protected
 
+        def eager_loaded?
+          @eager_loaded ||= false
+        end
+
         # The method which actually looks up for the translation in the store.
-        def lookup(locale, key, scope = [], options = {})
+        def lookup(locale, key, scope = [], options = EMPTY_HASH)
           raise NotImplementedError
         end
 
@@ -109,7 +121,7 @@ module I18n
         # If given subject is an Array, it walks the array and returns the
         # first translation that can be resolved. Otherwise it tries to resolve
         # the translation directly.
-        def default(locale, object, subject, options = {})
+        def default(locale, object, subject, options = EMPTY_HASH)
           options = options.dup.reject { |key, value| key == :default }
           case subject
           when Array
@@ -126,7 +138,7 @@ module I18n
         # If the given subject is a Symbol, it will be translated with the
         # given options. If it is a Proc then it will be evaluated. All other
         # subjects will be returned directly.
-        def resolve(locale, object, subject, options = {})
+        def resolve(locale, object, subject, options = EMPTY_HASH)
           return subject if options[:resolve] == false
           result = catch(:exception) do
             case subject
@@ -168,7 +180,7 @@ module I18n
         #   each element of the array is recursively interpolated (until it finds a string)
         #   method interpolates ["yes, %{user}", ["maybe no, %{user}, "no, %{user}"]], :user => "bartuz"
         #   # => "["yes, bartuz",["maybe no, bartuz", "no, bartuz"]]"
-        def interpolate(locale, subject, values = {})
+        def interpolate(locale, subject, values = EMPTY_HASH)
           return subject if values.empty?
 
           case subject
@@ -184,7 +196,7 @@ module I18n
         #   deep_interpolate { people: { ann: "Ann is %{ann}", john: "John is %{john}" } },
         #                    ann: 'good', john: 'big'
         #   #=> { people: { ann: "Ann is good", john: "John is big" } }
-        def deep_interpolate(locale, data, values = {})
+        def deep_interpolate(locale, data, values = EMPTY_HASH)
           return data if values.empty?
 
           case data
@@ -232,18 +244,35 @@ module I18n
             raise InvalidLocaleData.new(filename, e.inspect)
           end
         end
+        alias_method :load_yaml, :load_yml
+
+        # Loads a JSON translations file. The data must have locales as
+        # toplevel keys.
+        def load_json(filename)
+          begin
+            ::JSON.parse(File.read(filename))
+          rescue TypeError, StandardError => e
+            raise InvalidLocaleData.new(filename, e.inspect)
+          end
+        end
 
         def translate_localization_format(locale, object, format, options)
-          format.to_s.gsub(/%[aAbBpP]/) do |match|
+          format.to_s.gsub(/%(|\^)[aAbBpP]/) do |match|
             case match
-            when '%a' then I18n.t(:"date.abbr_day_names",                  :locale => locale, :format => format)[object.wday]
-            when '%A' then I18n.t(:"date.day_names",                       :locale => locale, :format => format)[object.wday]
-            when '%b' then I18n.t(:"date.abbr_month_names",                :locale => locale, :format => format)[object.mon]
-            when '%B' then I18n.t(:"date.month_names",                     :locale => locale, :format => format)[object.mon]
-            when '%p' then I18n.t(:"time.#{object.hour < 12 ? :am : :pm}", :locale => locale, :format => format).upcase if object.respond_to? :hour
-            when '%P' then I18n.t(:"time.#{object.hour < 12 ? :am : :pm}", :locale => locale, :format => format).downcase if object.respond_to? :hour
+            when '%a' then I18n.t!(:"date.abbr_day_names",                  :locale => locale, :format => format)[object.wday]
+            when '%^a' then I18n.t!(:"date.abbr_day_names",                 :locale => locale, :format => format)[object.wday].upcase
+            when '%A' then I18n.t!(:"date.day_names",                       :locale => locale, :format => format)[object.wday]
+            when '%^A' then I18n.t!(:"date.day_names",                      :locale => locale, :format => format)[object.wday].upcase
+            when '%b' then I18n.t!(:"date.abbr_month_names",                :locale => locale, :format => format)[object.mon]
+            when '%^b' then I18n.t!(:"date.abbr_month_names",               :locale => locale, :format => format)[object.mon].upcase
+            when '%B' then I18n.t!(:"date.month_names",                     :locale => locale, :format => format)[object.mon]
+            when '%^B' then I18n.t!(:"date.month_names",                    :locale => locale, :format => format)[object.mon].upcase
+            when '%p' then I18n.t!(:"time.#{object.hour < 12 ? :am : :pm}", :locale => locale, :format => format).upcase if object.respond_to? :hour
+            when '%P' then I18n.t!(:"time.#{object.hour < 12 ? :am : :pm}", :locale => locale, :format => format).downcase if object.respond_to? :hour
             end
           end
+        rescue MissingTranslationData => e
+          e.message
         end
 
         def pluralization_key(entry, count)

data/lib/i18n/backend/cache.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # This module allows you to easily cache all responses from the backend - thus
 # speeding up the I18n aspects of your application quite a bit.
 #
@@ -14,9 +16,9 @@
 # ActiveSupport::Cache (only the methods #fetch and #write are being used).
 #
 # The cache_key implementation by default assumes you pass values that return
-# a valid key from #hash (see 
-# http://www.ruby-doc.org/core/classes/Object.html#M000337). However, you can 
-# configure your own digest method via which responds to #hexdigest (see 
+# a valid key from #hash (see
+# http://www.ruby-doc.org/core/classes/Object.html#M000337). However, you can
+# configure your own digest method via which responds to #hexdigest (see
 # http://ruby-doc.org/stdlib/libdoc/digest/rdoc/index.html):
 #
 #   I18n.cache_key_digest = Digest::MD5.new
@@ -75,7 +77,7 @@ module I18n
   module Backend
     # TODO Should the cache be cleared if new translations are stored?
     module Cache
-      def translate(locale, key, options = {})
+      def translate(locale, key, options = EMPTY_HASH)
         I18n.perform_caching? ? fetch(cache_key(locale, key, options)) { super } : super
       end
 
@@ -98,16 +100,13 @@ module I18n
 
         def cache_key(locale, key, options)
           # This assumes that only simple, native Ruby values are passed to I18n.translate.
-          "i18n/#{I18n.cache_namespace}/#{locale}/#{digest_item(key)}/#{USE_INSPECT_HASH ? digest_item(options.inspect) : digest_item(options)}"
+          "i18n/#{I18n.cache_namespace}/#{locale}/#{digest_item(key)}/#{digest_item(options)}"
         end
 
       private
-        # In Ruby < 1.9 the following is true: { :foo => 1, :bar => 2 }.hash == { :foo => 2, :bar => 1 }.hash
-        # Therefore we must use the hash of the inspect string instead to avoid cache key colisions.
-        USE_INSPECT_HASH = RUBY_VERSION <= "1.9"
 
         def digest_item(key)
-          I18n.cache_key_digest ? I18n.cache_key_digest.hexdigest(key.to_s) : key.hash
+          I18n.cache_key_digest ? I18n.cache_key_digest.hexdigest(key.to_s) : key.to_s.hash
         end
     end
   end

data/lib/i18n/backend/cache_file.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require 'digest/sha2'
+
+module I18n
+  module Backend
+    # Overwrites the Base load_file method to cache loaded file contents.
+    module CacheFile
+      # Optionally provide path_roots array to normalize filename paths,
+      # to make the cached i18n data portable across environments.
+      attr_accessor :path_roots
+
+      protected
+
+      # Track loaded translation files in the `i18n.load_file` scope,
+      # and skip loading the file if its contents are still up-to-date.
+      def load_file(filename)
+        initialized = !respond_to?(:initialized?) || initialized?
+        key = I18n::Backend::Flatten.escape_default_separator(normalized_path(filename))
+        old_mtime, old_digest = initialized && lookup(:i18n, key, :load_file)
+        return if (mtime = File.mtime(filename).to_i) == old_mtime ||
+                  (digest = Digest::SHA2.file(filename).hexdigest) == old_digest
+        super
+        store_translations(:i18n, load_file: { key => [mtime, digest] })
+      end
+
+      # Translate absolute filename to relative path for i18n key.
+      def normalized_path(file)
+        return file unless path_roots
+        path = path_roots.find(&file.method(:start_with?)) ||
+               raise(InvalidLocaleData.new(file, 'outside expected path roots'))
+        file.sub(path, path_roots.index(path).to_s)
+      end
+    end
+  end
+end

data/lib/i18n/backend/cascade.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # The Cascade module adds the ability to do cascading lookups to backends that
 # are compatible to the Simple backend.
 #
@@ -31,7 +33,7 @@
 module I18n
   module Backend
     module Cascade
-      def lookup(locale, key, scope = [], options = {})
+      def lookup(locale, key, scope = [], options = EMPTY_HASH)
         return super unless cascade = options[:cascade]
 
         cascade   = { :step => 1 } unless cascade.is_a?(Hash)

data/lib/i18n/backend/chain.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module I18n
   module Backend
     # Backend that chains multiple other backends and checks each of them when
@@ -15,6 +17,8 @@ module I18n
     # The implementation assumes that all backends added to the Chain implement
     # a lookup method with the same API as Simple backend does.
     class Chain
+      using I18n::HashRefinements
+
       module Implementation
         include Base
 
@@ -24,11 +28,24 @@ module I18n
           self.backends = backends
         end
 
+        def initialized?
+          backends.all? do |backend|
+            backend.instance_eval do
+              return false unless initialized?
+            end
+          end
+          true
+        end
+
         def reload!
           backends.each { |backend| backend.reload! }
         end
 
-        def store_translations(locale, data, options = {})
+        def eager_load!
+          backends.each { |backend| backend.eager_load! }
+        end
+
+        def store_translations(locale, data, options = EMPTY_HASH)
           backends.first.store_translations(locale, data, options)
         end
 
@@ -36,7 +53,7 @@ module I18n
           backends.map { |backend| backend.available_locales }.flatten.uniq
         end
 
-        def translate(locale, key, default_options = {})
+        def translate(locale, key, default_options = EMPTY_HASH)
           namespace = nil
           options = default_options.except(:default)
 
@@ -62,7 +79,7 @@ module I18n
           end
         end
 
-        def localize(locale, object, format = :default, options = {})
+        def localize(locale, object, format = :default, options = EMPTY_HASH)
           backends.each do |backend|
             catch(:exception) do
               result = backend.localize(locale, object, format, options) and return result
@@ -72,6 +89,19 @@ module I18n
         end
 
         protected
+          def init_translations
+            backends.each do |backend|
+              backend.send(:init_translations)
+            end
+          end
+
+          def translations
+            backends.first.instance_eval do
+              init_translations unless initialized?
+              translations
+            end
+          end
+
           def namespace_lookup?(result, options)
             result.is_a?(Hash) && !options.has_key?(:count)
           end

data/lib/i18n/backend/fallbacks.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # I18n locale fallbacks are useful when you want your application to use
 # translations from other locales when translations for the current locale are
 # missing. E.g. you might want to use :en translations when translations in
@@ -34,25 +36,21 @@ module I18n
       # The default option takes precedence over fallback locales only when
       # it's a Symbol. When the default contains a String, Proc or Hash
       # it is evaluated last after all the fallback locales have been tried.
-      def translate(locale, key, options = {})
+      def translate(locale, key, options = EMPTY_HASH)
         return super unless options.fetch(:fallback, true)
         return super if options[:fallback_in_progress]
         default = extract_non_symbol_default!(options) if options[:default]
 
-        begin
-          options[:fallback_in_progress] = true
-          I18n.fallbacks[locale].each do |fallback|
-            begin
-              catch(:exception) do
-                result = super(fallback, key, options)
-                return result unless result.nil?
-              end
-            rescue I18n::InvalidLocale
-              # we do nothing when the locale is invalid, as this is a fallback anyways.
+        fallback_options = options.merge(:fallback_in_progress => true)
+        I18n.fallbacks[locale].each do |fallback|
+          begin
+            catch(:exception) do
+              result = super(fallback, key, fallback_options)
+              return result unless result.nil?
             end
+          rescue I18n::InvalidLocale
+            # we do nothing when the locale is invalid, as this is a fallback anyways.
           end
-        ensure
-          options.delete(:fallback_in_progress)
         end
 
         return if options.key?(:default) && options[:default].nil?

data/lib/i18n/backend/flatten.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module I18n
   module Backend
     # This module contains several helpers to assist flattening translations.

data/lib/i18n/backend/gettext.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'i18n/gettext'
 require 'i18n/gettext/po_parser'
 
@@ -29,6 +31,8 @@ module I18n
     # Without it strings containing periods (".") will not be translated.
 
     module Gettext
+      using I18n::HashRefinements
+
       class PoData < Hash
         def set_comment(msgid_or_sym, comment)
           # ignore

data/lib/i18n/backend/interpolation_compiler.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # The InterpolationCompiler module contains optimizations that can tremendously
 # speed up the interpolation process on the Simple backend.
 #
@@ -104,7 +106,7 @@ module I18n
         end
       end
 
-      def store_translations(locale, data, options = {})
+      def store_translations(locale, data, options = EMPTY_HASH)
         compile_all_strings_in(data)
         super
       end

data/lib/i18n/backend/key_value.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'i18n/backend/base'
 
 module I18n
@@ -65,6 +67,8 @@ module I18n
     #
     # This is useful if you are using a KeyValue backend chained to a Simple backend.
     class KeyValue
+      using I18n::HashRefinements
+
       module Implementation
         attr_accessor :store
 
@@ -74,7 +78,11 @@ module I18n
           @store, @subtrees = store, subtrees
         end
 
-        def store_translations(locale, data, options = {})
+        def initialized?
+          !@store.nil?
+        end
+
+        def store_translations(locale, data, options = EMPTY_HASH)
           escape = options.fetch(:escape, true)
           flatten_translations(locale, data, escape, @subtrees).each do |key, value|
             key = "#{locale}.#{key}"
@@ -103,11 +111,31 @@ module I18n
 
       protected
 
+        # Queries the translations from the key-value store and converts
+        # them into a hash such as the one returned from loading the
+        # haml files
+        def translations
+          @translations = @store.keys.clone.map do |main_key|
+            main_value = JSON.decode(@store[main_key])
+            main_key.to_s.split(".").reverse.inject(main_value) do |value, key|
+              {key.to_sym => value}
+            end
+          end.inject{|hash, elem| hash.deep_merge!(elem)}.deep_symbolize_keys
+        end
+
+        def init_translations
+          # NO OP
+          # This call made also inside Simple Backend and accessed by
+          # other plugins like I18n-js and babilu and
+          # to use it along with the Chain backend we need to
+          # provide a uniform API even for protected methods :S
+        end
+
         def subtrees?
           @subtrees
         end
 
-        def lookup(locale, key, scope = [], options = {})
+        def lookup(locale, key, scope = [], options = EMPTY_HASH)
           key   = normalize_flat_keys(locale, key, scope, options[:separator])
           value = @store["#{locale}.#{key}"]
           value = JSON.decode(value) if value
@@ -125,6 +153,7 @@ module I18n
           if subtrees?
             super
           else
+            return entry unless entry.is_a?(Hash)
             key = pluralization_key(entry, count)
             entry[key]
           end

data/lib/i18n/backend/memoize.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Memoize module simply memoizes the values returned by lookup using
 # a flat hash and can tremendously speed up the lookup process in a backend.
 #
@@ -14,7 +16,7 @@ module I18n
         @memoized_locales ||= super
       end
 
-      def store_translations(locale, data, options = {})
+      def store_translations(locale, data, options = EMPTY_HASH)
         reset_memoizations!(locale)
         super
       end
@@ -24,9 +26,15 @@ module I18n
         super
       end
 
+      def eager_load!
+        memoized_lookup
+        available_locales
+        super
+      end
+
       protected
 
-        def lookup(locale, key, scope = nil, options = {})
+        def lookup(locale, key, scope = nil, options = EMPTY_HASH)
           flat_key  = I18n::Backend::Flatten.normalize_flat_keys(locale,
             key, scope, options[:separator]).to_sym
           flat_hash = memoized_lookup[locale.to_sym]

data/lib/i18n/backend/metadata.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # I18n translation metadata is useful when you want to access information
 # about how a translation was looked up, pluralized or interpolated in
 # your application.
@@ -35,19 +37,19 @@ module I18n
         end
       end
 
-      def translate(locale, key, options = {})
+      def translate(locale, key, options = EMPTY_HASH)
         metadata = {
           :locale    => locale,
           :key       => key,
           :scope     => options[:scope],
           :default   => options[:default],
           :separator => options[:separator],
-          :values    => options.reject { |name, value| RESERVED_KEYS.include?(name) }
+          :values    => options.reject { |name, _value| RESERVED_KEYS.include?(name) }
         }
         with_metadata(metadata) { super }
       end
 
-      def interpolate(locale, entry, values = {})
+      def interpolate(locale, entry, values = EMPTY_HASH)
         metadata = entry.translation_metadata.merge(:original => entry)
         with_metadata(metadata) { super }
       end

data/lib/i18n/backend/pluralization.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # I18n Pluralization are useful when you want your application to
 # customize pluralization rules.
 #