i18n 1.9.1 → 1.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 73eb29528a85ee9bb80e81091573b181a768e7eca83afba1222884afbdc81928
-  data.tar.gz: a807e1a214d3195204fa37b7bc0ac57d7ac8125889405f943c07901b4e2b3972
+  metadata.gz: b92d195deaeca5e93f73cc62be2d2fb4c93d8a9787449e168b493773e5072458
+  data.tar.gz: f1172c9fac93f493c8a5b16cff4b27154ff917aed48cbc46a4a702363863111d
 SHA512:
-  metadata.gz: 4d7d1ac263e739f2b8a66fe50f0e5947150a9401e5e9a8d74a41d4f1ea0ac49b814a1474ab3b1e0e2c37f2e37692c76ab010cf962486709584580fc9ae72f15a
-  data.tar.gz: 3a87c0bb4b17b09af88afb9b8223df8f75251b9c073073200ed69ab343f8962ef230b63f93ad214243d1262c014ca6f735b1ef25f7c605c02249d66060fb3640
+  metadata.gz: 0174d10f7bac17e29cf7622d3ce69850e51755d53fd3d17d2f672bc9ca3c75823b851f6d04cbd367fea8ff5830c8c755fb9c80433bac9ec3c46590cbe9a874d0
+  data.tar.gz: ef22ed98cb7f223753a65b9d63d0f40e4b6821c93a41b1b41627e4c7b4e3de6b7bd411d8a6ed3d46dc6554432a776535c0461248e8d1fbfeee05dcda2ab89235

data/README.md

@@ -1,5 +1,6 @@
 # Ruby 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 (i18n) solution.

data/lib/i18n/backend/base.rb

@@ -13,7 +13,10 @@ module I18n
       # 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.
@@ -32,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]
@@ -151,6 +154,7 @@ module I18n
           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 :
@@ -226,6 +230,8 @@ module I18n
             raise InvalidLocaleData.new(filename, 'expects it to return a hash, but does not')
           end
           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

data/lib/i18n/backend/fallbacks.rb

@@ -64,13 +64,20 @@ module I18n
         throw(:exception, I18n::MissingTranslation.new(locale, key, options))
       end
 
-      def resolve(locale, object, subject, options = EMPTY_HASH)
+      def resolve_entry(locale, object, subject, options = EMPTY_HASH)
         return subject if options[:resolve] == false
-        return super unless subject.is_a?(Symbol)
-
         result = catch(:exception) do
-          options.delete(:fallback_in_progress)
-          I18n.translate(subject, **options.merge(locale: options[:fallback_original_locale], throw: true))
+          options.delete(:fallback_in_progress) if options.key?(:fallback_in_progress)
+
+          case subject
+          when Symbol
+            I18n.translate(subject, **options.merge(:locale => options[:fallback_original_locale], :throw => true))
+          when Proc
+            date_or_time = options.delete(:object) || object
+            resolve_entry(options[:fallback_original_locale], object, subject.call(date_or_time, **options))
+          else
+            subject
+          end
         end
         result unless result.is_a?(MissingTranslation)
       end
@@ -100,7 +107,7 @@ module I18n
       private
 
         # Overwrite on_fallback to add specified logic when the fallback succeeds.
-        def on_fallback(_original_locale, _fallback_locale, _key, _optoins)
+        def on_fallback(_original_locale, _fallback_locale, _key, _options)
           nil
         end
     end

data/lib/i18n/backend/lazy_loadable.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+module I18n
+  module Backend
+    # Backend that lazy loads translations based on the current locale. This
+    # implementation avoids loading all translations up front. Instead, it only
+    # loads the translations that belong to the current locale. This offers a
+    # performance incentive in local development and test environments for
+    # applications with many translations for many different locales. It's
+    # particularly useful when the application only refers to a single locales'
+    # translations at a time (ex. A Rails workload).  The implementation
+    # identifies which translation files from the load path belong to the
+    # current locale by pattern matching against their path name.
+    #
+    # Specifically, a translation file is considered to belong to a locale if:
+    # a) the filename is in the I18n load path
+    # b) the filename ends in a supported extension (ie. .yml, .json, .po, .rb)
+    # c) the filename starts with the locale identifier
+    # d) the locale identifier and optional proceeding text is separated by an underscore, ie. "_".
+    #
+    # Examples:
+    # Valid files that will be selected by this backend:
+    #
+    # "files/locales/en_translation.yml" (Selected for locale "en")
+    # "files/locales/fr.po"  (Selected for locale "fr")
+    #
+    # Invalid files that won't be selected by this backend:
+    #
+    # "files/locales/translation-file"
+    # "files/locales/en-translation.unsupported"
+    # "files/locales/french/translation.yml"
+    # "files/locales/fr/translation.yml"
+    #
+    # The implementation uses this assumption to defer the loading of
+    # translation files until the current locale actually requires them.
+    #
+    # The backend has two working modes: lazy_load and eager_load.
+    #
+    # Note: This backend should only be enabled in test environments!
+    # When the mode is set to false, the backend behaves exactly like the
+    # Simple backend, with an additional check that the paths being loaded
+    # abide by the format. If paths can't be matched to the format, an error is raised.
+    #
+    # You can configure lazy loaded backends through the initializer or backends
+    # accessor:
+    #
+    #   # In test environments
+    #
+    #   I18n.backend = I18n::Backend::LazyLoadable.new(lazy_load: true)
+    #
+    #   # In other environments, such as production and CI
+    #
+    #   I18n.backend = I18n::Backend::LazyLoadable.new(lazy_load: false) # default
+    #
+    class LocaleExtractor
+      class << self
+        def locale_from_path(path)
+          name = File.basename(path, ".*")
+          locale = name.split("_").first
+          locale.to_sym unless locale.nil?
+        end
+      end
+    end
+
+    class LazyLoadable < Simple
+      def initialize(lazy_load: false)
+        @lazy_load = lazy_load
+      end
+
+      # Returns whether the current locale is initialized.
+      def initialized?
+        if lazy_load?
+          initialized_locales[I18n.locale]
+        else
+          super
+        end
+      end
+
+      # Clean up translations and uninitialize all locales.
+      def reload!
+        if lazy_load?
+          @initialized_locales = nil
+          @translations = nil
+        else
+          super
+        end
+      end
+
+      # Eager loading is not supported in the lazy context.
+      def eager_load!
+        if lazy_load?
+          raise UnsupportedMethod.new(__method__, self.class, "Cannot eager load translations because backend was configured with lazy_load: true.")
+        else
+          super
+        end
+      end
+
+      # Parse the load path and extract all locales.
+      def available_locales
+        if lazy_load?
+          I18n.load_path.map { |path| LocaleExtractor.locale_from_path(path) }
+        else
+          super
+        end
+      end
+
+      def lookup(locale, key, scope = [], options = EMPTY_HASH)
+        if lazy_load?
+          I18n.with_locale(locale) do
+            super
+          end
+        else
+          super
+        end
+      end
+
+      protected
+
+
+      # Load translations from files that belong to the current locale.
+      def init_translations
+        file_errors = if lazy_load?
+          initialized_locales[I18n.locale] = true
+          load_translations_and_collect_file_errors(filenames_for_current_locale)
+        else
+          @initialized = true
+          load_translations_and_collect_file_errors(I18n.load_path)
+        end
+
+        raise InvalidFilenames.new(file_errors) unless file_errors.empty?
+      end
+
+      def initialized_locales
+        @initialized_locales ||= Hash.new(false)
+      end
+
+      private
+
+      def lazy_load?
+        @lazy_load
+      end
+
+      class FilenameIncorrect < StandardError
+        def initialize(file, expected_locale, unexpected_locales)
+          super "#{file} can only load translations for \"#{expected_locale}\". Found translations for: #{unexpected_locales}."
+        end
+      end
+
+      # Loads each file supplied and asserts that the file only loads
+      # translations as expected by the name. The method returns a list of
+      # errors corresponding to offending files.
+      def load_translations_and_collect_file_errors(files)
+        errors = []
+
+        load_translations(files) do |file, loaded_translations|
+          assert_file_named_correctly!(file, loaded_translations)
+        rescue FilenameIncorrect => e
+          errors << e
+        end
+
+        errors
+      end
+
+      # Select all files from I18n load path that belong to current locale.
+      # These files must start with the locale identifier (ie. "en", "pt-BR"),
+      # followed by an "_" demarcation to separate proceeding text.
+      def filenames_for_current_locale
+        I18n.load_path.flatten.select do |path|
+          LocaleExtractor.locale_from_path(path) == I18n.locale
+        end
+      end
+
+      # Checks if a filename is named in correspondence to the translations it loaded.
+      # The locale extracted from the path must be the single locale loaded in the translations.
+      def assert_file_named_correctly!(file, translations)
+        loaded_locales = translations.keys.map(&:to_sym)
+        expected_locale = LocaleExtractor.locale_from_path(file)
+        unexpected_locales = loaded_locales.reject { |locale| locale == expected_locale }
+
+        raise FilenameIncorrect.new(file, expected_locale, unexpected_locales) unless unexpected_locales.empty?
+      end
+    end
+  end
+end

data/lib/i18n/backend/simple.rb

@@ -94,7 +94,7 @@ module I18n
               return nil unless result.has_key?(_key)
             end
             result = result[_key]
-            result = resolve(locale, _key, result, options.merge(:scope => nil)) if result.is_a?(Symbol)
+            result = resolve_entry(locale, _key, result, options.merge(:scope => nil)) if result.is_a?(Symbol)
             result
           end
         end

data/lib/i18n/backend.rb

@@ -3,7 +3,6 @@
 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'
@@ -11,7 +10,9 @@ module I18n
     autoload :Fallbacks,             'i18n/backend/fallbacks'
     autoload :Flatten,               'i18n/backend/flatten'
     autoload :Gettext,               'i18n/backend/gettext'
+    autoload :InterpolationCompiler, 'i18n/backend/interpolation_compiler'
     autoload :KeyValue,              'i18n/backend/key_value'
+    autoload :LazyLoadable,          'i18n/backend/lazy_loadable'
     autoload :Memoize,               'i18n/backend/memoize'
     autoload :Metadata,              'i18n/backend/metadata'
     autoload :Pluralization,         'i18n/backend/pluralization'

data/lib/i18n/config.rb

@@ -38,7 +38,7 @@ module I18n
     end
 
     # Returns an array of locales for which translations are available.
-    # Unless you explicitely set these through I18n.available_locales=
+    # Unless you explicitly set these through I18n.available_locales=
     # the call will be delegated to the backend.
     def available_locales
       @@available_locales ||= nil
@@ -106,7 +106,7 @@ module I18n
     # if you don't care about arity.
     #
     # == Example:
-    # You can supress raising an exception and return string instead:
+    # You can suppress raising an exception and return string instead:
     #
     #   I18n.config.missing_interpolation_argument_handler = Proc.new do |key|
     #     "#{key} is missing"

data/lib/i18n/exceptions.rb

@@ -24,7 +24,7 @@ module I18n
         been set is likely to display text from the wrong locale to some users.
 
         If you have a legitimate reason to access i18n data outside of the user flow, you can do so by passing
-        the desired locale explictly with the `locale` argument, e.g. `I18n.#{method}(..., locale: :en)`
+        the desired locale explicitly with the `locale` argument, e.g. `I18n.#{method}(..., locale: :en)`
       MESSAGE
     end
   end
@@ -110,4 +110,38 @@ module I18n
       super "can not load translations from #{filename}, the file type #{type} is not known"
     end
   end
+
+  class UnsupportedMethod < ArgumentError
+    attr_reader :method, :backend_klass, :msg
+    def initialize(method, backend_klass, msg)
+      @method = method
+      @backend_klass = backend_klass
+      @msg = msg
+      super "#{backend_klass} does not support the ##{method} method. #{msg}"
+    end
+  end
+
+  class InvalidFilenames < ArgumentError
+    NUMBER_OF_ERRORS_SHOWN = 20
+    def initialize(file_errors)
+      super <<~MSG
+        Found #{file_errors.count} error(s).
+        The first #{[file_errors.count, NUMBER_OF_ERRORS_SHOWN].min} error(s):
+        #{file_errors.map(&:message).first(NUMBER_OF_ERRORS_SHOWN).join("\n")}
+
+        To use the LazyLoadable backend:
+        1. Filenames must start with the locale.
+        2. An underscore must separate the locale with any optional text that follows.
+        3. The file must only contain translation data for the single locale.
+
+        Example:
+        "/config/locales/fr.yml" which contains:
+        ```yml
+          fr:
+            dog:
+              chien
+        ```
+      MSG
+    end
+  end
 end

data/lib/i18n/locale/tag/simple.rb

@@ -1,5 +1,5 @@
 # Simple Locale tag implementation that computes subtags by simply splitting
-# the locale tag at '-' occurences.
+# the locale tag at '-' occurrences.
 module I18n
   module Locale
     module Tag

data/lib/i18n/tests/basics.rb

@@ -5,12 +5,11 @@ module I18n
         I18n.available_locales = nil
       end
 
-      test "available_locales returns the locales stored to the backend by default" do
+      test "available_locales returns the available_locales produced by the backend, by default" do
         I18n.backend.store_translations('de', :foo => 'bar')
         I18n.backend.store_translations('en', :foo => 'foo')
 
-        assert I18n.available_locales.include?(:de)
-        assert I18n.available_locales.include?(:en)
+        assert_equal I18n.available_locales, I18n.backend.available_locales
       end
 
       test "available_locales can be set to something else independently from the actual locale data" do
@@ -24,11 +23,10 @@ module I18n
         assert_equal [:foo, :bar], I18n.available_locales
 
         I18n.available_locales = nil
-        assert I18n.available_locales.include?(:de)
-        assert I18n.available_locales.include?(:en)
+        assert_equal I18n.available_locales, I18n.backend.available_locales
       end
 
-      test "available_locales memoizes when set explicitely" do
+      test "available_locales memoizes when set explicitly" do
         I18n.backend.expects(:available_locales).never
         I18n.available_locales = [:foo]
         I18n.backend.store_translations('de', :bar => 'baz')
@@ -36,7 +34,7 @@ module I18n
         assert_equal [:foo], I18n.available_locales
       end
 
-      test "available_locales delegates to the backend when not set explicitely" do
+      test "available_locales delegates to the backend when not set explicitly" do
         original_available_locales_value = I18n.backend.available_locales
         I18n.backend.expects(:available_locales).returns(original_available_locales_value).twice
         assert_equal I18n.backend.available_locales, I18n.available_locales

data/lib/i18n/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module I18n
-  VERSION = "1.9.1"
+  VERSION = "1.12.0"
 end

data/lib/i18n.rb

@@ -214,18 +214,12 @@ module I18n
 
       backend = config.backend
 
-      result = catch(:exception) do
-        if key.is_a?(Array)
-          key.map { |k| backend.translate(locale, k, options) }
-        else
-          backend.translate(locale, key, options)
+      if key.is_a?(Array)
+        key.map do |k|
+          translate_key(k, throw, raise, locale, backend, options)
         end
-      end
-
-      if result.is_a?(MissingTranslation)
-        handle_exception((throw && :throw || raise && :raise), result, locale, key, options)
       else
-        result
+        translate_key(key, throw, raise, locale, backend, options)
       end
     end
     alias :t :translate
@@ -338,11 +332,11 @@ module I18n
     def normalize_keys(locale, key, scope, separator = nil)
       separator ||= I18n.default_separator
 
-      keys = []
-      keys.concat normalize_key(locale, separator)
-      keys.concat normalize_key(scope, separator)
-      keys.concat normalize_key(key, separator)
-      keys
+      [
+        *normalize_key(locale, separator),
+        *normalize_key(scope, separator),
+        *normalize_key(key, separator)
+      ]
     end
 
     # Returns true when the passed locale, which can be either a String or a
@@ -364,6 +358,18 @@ module I18n
 
   private
 
+    def translate_key(key, throw, raise, locale, backend, options)
+      result = catch(:exception) do
+        backend.translate(locale, key, options)
+      end
+
+      if result.is_a?(MissingTranslation)
+        handle_exception((throw && :throw || raise && :raise), result, locale, key, options)
+      else
+        result
+      end
+    end
+
     # Any exceptions thrown in translate will be sent to the @@exception_handler
     # which can be a Symbol, a Proc or any other Object unless they're forced to
     # be raised or thrown (MissingTranslation).

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: i18n
 version: !ruby/object:Gem::Version
-  version: 1.9.1
+  version: 1.12.0
 platform: ruby
 authors:
 - Sven Fuchs
@@ -10,10 +10,10 @@ authors:
 - Stephan Soller
 - Saimon Moore
 - Ryan Bigg
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-01-27 00:00:00.000000000 Z
+date: 2022-07-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -49,6 +49,7 @@ files:
 - lib/i18n/backend/gettext.rb
 - lib/i18n/backend/interpolation_compiler.rb
 - lib/i18n/backend/key_value.rb
+- lib/i18n/backend/lazy_loadable.rb
 - lib/i18n/backend/memoize.rb
 - lib/i18n/backend/metadata.rb
 - lib/i18n/backend/pluralization.rb
@@ -90,7 +91,7 @@ metadata:
   changelog_uri: https://github.com/ruby-i18n/i18n/releases
   documentation_uri: https://guides.rubyonrails.org/i18n.html
   source_code_uri: https://github.com/ruby-i18n/i18n
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -105,8 +106,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: 1.3.5
 requirements: []
-rubygems_version: 3.1.6
-signing_key: 
+rubygems_version: 3.3.16
+signing_key:
 specification_version: 4
 summary: New wave Internationalization support for Ruby
 test_files: []