i18n 0.9.5 → 1.8.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '09643c444c40fe98042352f7f3e3e2df08e15ec5bee9f3d658b3e2fdeeb627a7'
-  data.tar.gz: b924468907cca779632052d4ec166c79a9fc10f305a4a4f2c7be6ffeef6a5e47
+  metadata.gz: d85e42515b239906cad750dc259b33896b1af0f323bb0dfa76e00e25fffc4745
+  data.tar.gz: 9f7b02056b8d9efe5e753fa21c4d7e40abc1ac7ff5bb219b350d7424a9d8abc8
 SHA512:
-  metadata.gz: 338556073a2c02752c1d3e5e3ba5ed70cb692d814ab05aca5a3d70ef3ee013aa3bb9d5cfc6aecbbd2a93e4732105a4c05c70968ea7f955c169cf69ad97462796
-  data.tar.gz: a0a4eff7b73ac32730dae8b77f609c4cc6fca9b6c2f46d81f42d992e10dd8d1467dbc28985b38769f9cab2f6ac1d67e4309eb8a8df65d9fc38baa39b65343f18
+  metadata.gz: 20ec433c6d838fcbb62815541827634e38740ceb02c9e8c2f020a72da6d41316016ff89399fc4baaea23150ae6be020a77c8dc7855d1d1da7a5d72f7a3834b30
+  data.tar.gz: 27300973f400a0804fed69ab7e522bf2f3e60718a541245f8d6874c244b9a5aff67dbebfc5c503dc82336b962349e23e4d046ee688e2af03840bd9d7528e2a8b

data/README.md

@@ -1,45 +1,82 @@
 # Ruby I18n
 
-[![Build Status](https://api.travis-ci.org/svenfuchs/i18n.svg?branch=master)](https://travis-ci.org/svenfuchs/i18n)
+[![Build Status](https://github.com/ruby-i18n/i18n/workflows/Ruby/badge.svg)](https://github.com/ruby-i18n/i18n/actions?query=workflow%3ARuby)
 
-Ruby Internationalization and localization solution.
+Ruby internationalization and localization (i18n) 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
 
-* translation and localization
-* interpolation of values to translations (Ruby 1.9 compatible syntax)
-* pluralization (CLDR compatible)
-* customizable transliteration to ASCII
-* flexible defaults
-* bulk lookup
-* lambdas as translation data
-* custom key/scope separator
-* custom exception handlers
-* extensible architecture with a swappable backend
+### Rails
 
-Pluggable features:
+You will most commonly use this library within a Rails app.
+
+[See the Rails Guide](https://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
+* Pluralization (CLDR compatible)
+* Customizable transliteration to ASCII
+* Flexible defaults
+* Bulk lookup
+* Lambdas as translation data
+* Custom key/scope separator
+* Custom exception handlers
+* Extensible architecture with a swappable backend
+
+## 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
 
@@ -58,7 +95,7 @@ particular tests in different test cases.
 The reason for this is that we need to enforce the I18n API across various
 combinations of extensions. E.g. the Simple backend alone needs to support
 the same API as any combination of feature and/or optimization modules included
-to the Simple backend. We test this by reusing the same API defition (implemented
+to the Simple backend. We test this by reusing the same API definition (implemented
 as test methods) in test cases with different setups.
 
 You can find the test cases that enforce the API in test/api. And you can find
@@ -67,17 +104,18 @@ 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.
 
-## Authors
+## More Documentation
 
-* [Sven Fuchs](http://www.artweb-design.de)
-* [Joshua Harvey](http://www.workingwithrails.com/person/759-joshua-harvey)
-* [Stephan Soller](http://www.arkanis-development.de)
-* [Saimon Moore](http://saimonmoore.net)
-* [Matt Aimonetti](https://matt.aimonetti.net/)
+Additional documentation can be found here: https://github.com/ruby-i18n/i18n/wiki
 
 ## Contributors
 
-https://github.com/svenfuchs/i18n/graphs/contributors
+* @radar
+* @carlosantoniodasilva
+* @josevalim
+* @knapo
+* @tigrish
+* [and many more](https://github.com/ruby-i18n/i18n/graphs/contributors)
 
 ## License
 

data/lib/i18n.rb

@@ -1,4 +1,7 @@
+# frozen_string_literal: true
+
 require 'concurrent/map'
+require 'concurrent/hash'
 
 require 'i18n/version'
 require 'i18n/exceptions'
@@ -12,12 +15,26 @@ module I18n
   autoload :Tests,   'i18n/tests'
   autoload :Middleware,   'i18n/middleware'
 
-  RESERVED_KEYS = [:scope, :default, :separator, :resolve, :object, :fallback, :fallback_in_progress, :format, :cascade, :throw, :raise, :deep_interpolation]
+  RESERVED_KEYS = %i[
+    cascade
+    deep_interpolation
+    default
+    exception_handler
+    fallback
+    fallback_in_progress
+    format
+    object
+    raise
+    resolve
+    scope
+    separator
+    throw
+  ].freeze
   RESERVED_KEYS_PATTERN = /%\{(#{RESERVED_KEYS.join("|")})\}/
-
+  EMPTY_HASH = {}.freeze
 
   def self.new_double_nested_cache # :nodoc:
-    Concurrent::Map.new { |h,k| h[k] = Concurrent::Map.new }
+    Concurrent::Map.new { |h, k| h[k] = Concurrent::Map.new }
   end
 
   module Base
@@ -53,6 +70,13 @@ module I18n
       config.backend.reload!
     end
 
+    # Tells the backend to load translations now. Used in situations like the
+    # Rails production environment. Backends can implement whatever strategy
+    # is useful.
+    def eager_load!
+      config.backend.eager_load!
+    end
+
     # Translates, pluralizes and interpolates a given key using a given locale,
     # scope, and default, as well as interpolation values.
     #
@@ -92,7 +116,7 @@ module I18n
     # *PLURALIZATION*
     #
     # Translation data can contain pluralized translations. Pluralized translations
-    # are arrays of singluar/plural versions of translations like <tt>['Foo', 'Foos']</tt>.
+    # are arrays of singular/plural versions of translations like <tt>['Foo', 'Foos']</tt>.
     #
     # Note that <tt>I18n::Backend::Simple</tt> only supports an algorithm for English
     # pluralization rules. Other algorithms can be supported by custom backends.
@@ -150,18 +174,32 @@ module I18n
     #
     # It is recommended to use/implement lambdas in an "idempotent" way. E.g. when
     # a cache layer is put in front of I18n.translate it will generate a cache key
-    # from the argument values passed to #translate. Therefor your lambdas should
+    # from the argument values passed to #translate. Therefore your lambdas should
     # always return the same translations/values per unique combination of argument
     # values.
-    def translate(*args)
-      options  = args.last.is_a?(Hash) ? args.pop.dup : {}
-      key      = args.shift
-      backend  = config.backend
-      locale   = options.delete(:locale) || config.locale
-      handling = options.delete(:throw) && :throw || options.delete(:raise) && :raise # TODO deprecate :raise
-
+    #
+    # *Ruby 2.7+ keyword arguments warning*
+    #
+    # This method uses keyword arguments.
+    # There is a breaking change in ruby that produces warning with ruby 2.7 and won't work as expected with ruby 3.0
+    # The "hash" parameter must be passed as keyword argument.
+    #
+    # Good:
+    #  I18n.t(:salutation, :gender => 'w', :name => 'Smith')
+    #  I18n.t(:salutation, **{ :gender => 'w', :name => 'Smith' })
+    #  I18n.t(:salutation, **any_hash)
+    #
+    # Bad:
+    #  I18n.t(:salutation, { :gender => 'w', :name => 'Smith' })
+    #  I18n.t(:salutation, any_hash)
+    #
+    def translate(key = nil, throw: false, raise: false, locale: nil, **options) # TODO deprecate :raise
+      locale ||= config.locale
+      raise Disabled.new('t') if locale == false
       enforce_available_locales!(locale)
 
+      backend = config.backend
+
       result = catch(:exception) do
         if key.is_a?(Array)
           key.map { |k| backend.translate(locale, k, options) }
@@ -169,21 +207,28 @@ module I18n
           backend.translate(locale, key, options)
         end
       end
-      result.is_a?(MissingTranslation) ? handle_exception(handling, result, locale, key, options) : result
+
+      if result.is_a?(MissingTranslation)
+        handle_exception((throw && :throw || raise && :raise), result, locale, key, options)
+      else
+        result
+      end
     end
     alias :t :translate
 
     # Wrapper for <tt>translate</tt> that adds <tt>:raise => true</tt>. With
     # this option, if no translation is found, it will raise <tt>I18n::MissingTranslationData</tt>
-    def translate!(key, options={})
-      translate(key, options.merge(:raise => true))
+    def translate!(key, **options)
+      translate(key, **options, raise: true)
     end
     alias :t! :translate!
 
     # Returns true if a translation exists for a given key, otherwise returns false.
-    def exists?(key, locale = config.locale)
+    def exists?(key, _locale = nil, locale: _locale, **options)
+      locale ||= config.locale
+      raise Disabled.new('exists?') if locale == false
       raise I18n::ArgumentError if key.is_a?(String) && key.empty?
-      config.backend.exists?(locale, key)
+      config.backend.exists?(locale, key, options)
     end
 
     # Transliterates UTF-8 characters to ASCII. By default this method will
@@ -237,37 +282,40 @@ module I18n
     #     I18n.transliterate("Jürgen") # => "Juergen"
     #     I18n.transliterate("Jürgen", :locale => :en) # => "Jurgen"
     #     I18n.transliterate("Jürgen", :locale => :de) # => "Juergen"
-    def transliterate(*args)
-      options      = args.pop.dup if args.last.is_a?(Hash)
-      key          = args.shift
-      locale       = options && options.delete(:locale) || config.locale
-      handling     = options && (options.delete(:throw) && :throw || options.delete(:raise) && :raise)
-      replacement  = options && options.delete(:replacement)
+    def transliterate(key, throw: false, raise: false, locale: nil, replacement: nil, **options)
+      locale ||= config.locale
+      raise Disabled.new('transliterate') if locale == false
       enforce_available_locales!(locale)
+
       config.backend.transliterate(locale, key, replacement)
     rescue I18n::ArgumentError => exception
-      handle_exception(handling, exception, locale, key, options || {})
+      handle_exception((throw && :throw || raise && :raise), exception, locale, key, options)
     end
 
     # Localizes certain objects, such as dates and numbers to local formatting.
-    def localize(object, options = nil)
-      options = options ? options.dup : {}
-      locale = options.delete(:locale) || config.locale
-      format = options.delete(:format) || :default
+    def localize(object, locale: nil, format: nil, **options)
+      locale ||= config.locale
+      raise Disabled.new('l') if locale == false
       enforce_available_locales!(locale)
+
+      format ||= :default
       config.backend.localize(locale, object, format, options)
     end
     alias :l :localize
 
     # Executes block with given I18n.locale set.
     def with_locale(tmp_locale = nil)
-      if tmp_locale
+      if tmp_locale == nil
+        yield
+      else
         current_locale = self.locale
-        self.locale    = tmp_locale
+        self.locale = tmp_locale
+        begin
+          yield
+        ensure
+          self.locale = current_locale
+        end
       end
-      yield
-    ensure
-      self.locale = current_locale if tmp_locale
     end
 
     # Merges the given locale, key and scope into a single array of keys.
@@ -291,7 +339,7 @@ module I18n
 
     # Raises an InvalidLocale exception when the passed locale is not available.
     def enforce_available_locales!(locale)
-      if config.enforce_available_locales
+      if locale != false && config.enforce_available_locales
         raise I18n::InvalidLocale.new(locale) if !locale_available?(locale)
       end
     end
@@ -342,11 +390,22 @@ module I18n
       @@normalized_key_cache[separator][key] ||=
         case key
         when Array
-          key.map { |k| normalize_key(k, separator) }.flatten
+          key.flat_map { |k| normalize_key(k, separator) }
         else
           keys = key.to_s.split(separator)
           keys.delete('')
-          keys.map! { |k| k.to_sym }
+          keys.map! do |k|
+            case k
+            when /\A[-+]?[1-9]\d*\z/ # integer
+              k.to_i
+            when 'true'
+              true
+            when 'false'
+              false
+            else
+              k.to_sym
+            end
+          end
           keys
         end
     end

data/lib/i18n/backend.rb

@@ -1,8 +1,11 @@
+# frozen_string_literal: true
+
 module I18n
   module Backend
     autoload :Base,                  'i18n/backend/base'
     autoload :InterpolationCompiler, 'i18n/backend/interpolation_compiler'
     autoload :Cache,                 'i18n/backend/cache'
+    autoload :CacheFile,             'i18n/backend/cache_file'
     autoload :Cascade,               'i18n/backend/cascade'
     autoload :Chain,                 'i18n/backend/chain'
     autoload :Fallbacks,             'i18n/backend/fallbacks'

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)
@@ -61,14 +64,14 @@ module I18n
         entry
       end
 
-      def exists?(locale, key)
+      def exists?(locale, key, options = EMPTY_HASH)
         lookup(locale, key) != nil
       end
 
       # 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
@@ -78,7 +81,7 @@ module I18n
           key  = format
           type = object.respond_to?(:sec) ? 'time' : 'date'
           options = options.merge(:raise => true, :object => object, :locale => locale)
-          format  = I18n.t(:"#{type}.formats.#{key}", options)
+          format  = I18n.t(:"#{type}.formats.#{key}", **options)
         end
 
         format = translate_localization_format(locale, object, format, options)
@@ -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,8 +121,8 @@ 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 = {})
-          options = options.dup.reject { |key, value| key == :default }
+        def default(locale, object, subject, options = EMPTY_HASH)
+          options = options.reject { |key, value| key == :default }
           case subject
           when Array
             subject.each do |item|
@@ -126,15 +138,15 @@ 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
             when Symbol
-              I18n.translate(subject, options.merge(:locale => locale, :throw => true))
+              I18n.translate(subject, **options.merge(:locale => locale, :throw => true))
             when Proc
               date_or_time = options.delete(:object) || object
-              resolve(locale, object, subject.call(date_or_time, options))
+              resolve(locale, object, subject.call(date_or_time, **options))
             else
               subject
             end
@@ -151,7 +163,8 @@ module I18n
         #   not standard with regards to the CLDR pluralization rules.
         # Other backends can implement more flexible or complex pluralization rules.
         def pluralize(locale, entry, count)
-          return entry unless entry.is_a?(Hash) && count
+          entry = entry.reject { |k, _v| k == :attributes } if entry.is_a?(Hash)
+          return entry unless entry.is_a?(Hash) && count && entry.values.none? { |v| v.is_a?(Hash) }
 
           key = pluralization_key(entry, count)
           raise InvalidPluralizationData.new(entry, count, key) unless entry.has_key?(key)
@@ -168,7 +181,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 +197,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 +245,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)