i18n 0.9.5 → 1.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '09643c444c40fe98042352f7f3e3e2df08e15ec5bee9f3d658b3e2fdeeb627a7'
-  data.tar.gz: b924468907cca779632052d4ec166c79a9fc10f305a4a4f2c7be6ffeef6a5e47
+  metadata.gz: bcce939890b82f2f78ef93aa98b2be5995f172f6c37b95c53800c155f2036eec
+  data.tar.gz: ae4d72446e698fc7c0666f0e9dad6f11fa669d768fe9272d0c89e14aba8d2274
 SHA512:
-  metadata.gz: 338556073a2c02752c1d3e5e3ba5ed70cb692d814ab05aca5a3d70ef3ee013aa3bb9d5cfc6aecbbd2a93e4732105a4c05c70968ea7f955c169cf69ad97462796
-  data.tar.gz: a0a4eff7b73ac32730dae8b77f609c4cc6fca9b6c2f46d81f42d992e10dd8d1467dbc28985b38769f9cab2f6ac1d67e4309eb8a8df65d9fc38baa39b65343f18
+  metadata.gz: bf36e9389526d5a48bbfc4043bc2c4587ddbfbfab41a2ccaafa801570c3a838530a001c6c3df1669d5e0beb14b63b394253cef6d6fdd12aa936ae8c07ecdbf72
+  data.tar.gz: 82b972e13f2342ca864e4ead724008aa75ad24bbf6d4f14603330e2999501cfb5c05ee6a9e5cd2cffbf48f07f6da868fccc33b4771f7b4b085989c4def36a7b9

data/README.md

@@ -1,45 +1,83 @@
 # Ruby I18n
 
-[![Build Status](https://api.travis-ci.org/svenfuchs/i18n.svg?branch=master)](https://travis-ci.org/svenfuchs/i18n)
+[![Gem Version](https://badge.fury.io/rb/i18n.svg)](https://badge.fury.io/rb/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 +96,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 +105,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/backend/base.rb

@@ -1,6 +1,7 @@
+# frozen_string_literal: true
+
 require 'yaml'
-require 'i18n/core_ext/hash'
-require 'i18n/core_ext/kernel/suppress_warnings'
+require 'json'
 
 module I18n
   module Backend
@@ -8,20 +9,23 @@ module I18n
       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?
-        filenames.flatten.each { |filename| load_file(filename) }
+        filenames.flatten.each do |filename|
+          loaded_translations = load_file(filename)
+          yield filename, loaded_translations if block_given?
+        end
       end
 
       # 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)
@@ -31,7 +35,7 @@ module I18n
         if entry.nil? && options.key?(:default)
           entry = default(locale, key, options[:default], options)
         else
-          entry = resolve(locale, key, entry, options)
+          entry = resolve_entry(locale, key, entry, options)
         end
 
         count = options[:count]
@@ -50,7 +54,7 @@ module I18n
         end
 
         deep_interpolation = options[:deep_interpolation]
-        values = options.except(*RESERVED_KEYS)
+        values = Utils.except(options, *RESERVED_KEYS)
         if values
           entry = if deep_interpolation
             deep_interpolate(locale, entry, values)
@@ -61,14 +65,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 +82,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 +96,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 +122,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,21 +139,22 @@ 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
           end
           result unless result.is_a?(MissingTranslation)
         end
+        alias_method :resolve_entry, :resolve
 
         # Picks a translation from a pluralized mnemonic subkey according to English
         # pluralization rules :
@@ -151,7 +165,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 +183,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 +199,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
@@ -210,40 +225,69 @@ module I18n
         def load_file(filename)
           type = File.extname(filename).tr('.', '').downcase
           raise UnknownFileType.new(type, filename) unless respond_to?(:"load_#{type}", true)
-          data = send(:"load_#{type}", filename)
+          data, keys_symbolized = send(:"load_#{type}", filename)
           unless data.is_a?(Hash)
             raise InvalidLocaleData.new(filename, 'expects it to return a hash, but does not')
           end
-          data.each { |locale, d| store_translations(locale, d || {}) }
+          data.each { |locale, d| store_translations(locale, d || {}, skip_symbolize_keys: keys_symbolized) }
+
+          data
         end
 
         # Loads a plain Ruby translations file. eval'ing the file must yield
         # a Hash containing translation data with locales as toplevel keys.
         def load_rb(filename)
-          eval(IO.read(filename), binding, filename)
+          translations = eval(IO.read(filename), binding, filename)
+          [translations, false]
         end
 
         # Loads a YAML translations file. The data must have locales as
         # toplevel keys.
         def load_yml(filename)
           begin
-            YAML.load_file(filename)
+            if YAML.respond_to?(:unsafe_load_file) # Psych 4.0 way
+              [YAML.unsafe_load_file(filename, symbolize_names: true, freeze: true), true]
+            else
+              [YAML.load_file(filename), false]
+            end
           rescue TypeError, ScriptError, StandardError => e
             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
+            # Use #load_file as a proxy for a version of JSON where symbolize_names and freeze are supported.
+            if ::JSON.respond_to?(:load_file)
+              [::JSON.load_file(filename, symbolize_names: true, freeze: true), true]
+            else
+              [::JSON.parse(File.read(filename)), false]
+            end
+          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,12 +16,12 @@
 # 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 
-# http://ruby-doc.org/stdlib/libdoc/digest/rdoc/index.html):
+# a valid key from #hash (see
+# https://www.ruby-doc.org/core/classes/Object.html#M000337). However, you can
+# configure your own digest method via which responds to #hexdigest (see
+# https://ruby-doc.org/stdlib/libdoc/openssl/rdoc/OpenSSL/Digest.html):
 #
-#   I18n.cache_key_digest = Digest::MD5.new
+#   I18n.cache_key_digest = OpenSSL::Digest::SHA256.new
 #
 # If you use a lambda as a default value in your translation like this:
 #
@@ -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 'openssl'
+
+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 = OpenSSL::Digest::SHA256.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
@@ -24,11 +26,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,9 +51,9 @@ 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)
+          options = Utils.except(default_options, :default)
 
           backends.each do |backend|
             catch(:exception) do
@@ -56,13 +71,13 @@ module I18n
           throw(:exception, I18n::MissingTranslation.new(locale, key, options))
         end
 
-        def exists?(locale, key)
+        def exists?(locale, key, options = EMPTY_HASH)
           backends.any? do |backend|
-            backend.exists?(locale, key)
+            backend.exists?(locale, key, options)
           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 +87,22 @@ module I18n
         end
 
         protected
+          def init_translations
+            backends.each do |backend|
+              backend.send(:init_translations)
+            end
+          end
+
+          def translations
+            backends.reverse.each_with_object({}) do |backend, memo|
+              partial_translations = backend.instance_eval do
+                init_translations unless initialized?
+                translations
+              end
+              Utils.deep_merge!(memo, partial_translations) { |_, a, b| b || a }
+            end
+          end
+
           def namespace_lookup?(result, options)
             result.is_a?(Hash) && !options.has_key?(:count)
           end