i18n 1.0.1 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6abb11703c717406a1a4e5df13e88679656a3bb798cd0141e4ef9961fed64056
-  data.tar.gz: 1e633332f63054b3919c887a853a1bb4348025550531bf3f499a924a1b37acf5
+  metadata.gz: 2b03b84d726d3cafa7ea2ecaa6f258cb911696c338cb32c769f71b6d62ca5fb5
+  data.tar.gz: 7a489bf447e9fedee8fd043cc8ba324c0afc0c34701fbfeff5f15b1c1f4fa6b4
 SHA512:
-  metadata.gz: 6fe991afffcec28225b53932a1977c6c30ee6f8a79a0256380a552f25ca6d0bffd3b21452d8177529d97aac9f880e1296072804942c0b99a379ecfeb6c8ca446
-  data.tar.gz: b8a7625539fe9e5c0c49b0a85a3bce54c1fb46e68ed4910870aee8c6f37afb589888b3ba87a6786e4364021a831619874f796a38eea6d0e6b285f67e232b3926
+  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.rb

@@ -69,6 +69,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.
     #
@@ -169,15 +176,13 @@ module I18n
     # from the argument values passed to #translate. Therefor 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
-
+    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) }
@@ -185,7 +190,12 @@ 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
 
@@ -197,7 +207,9 @@ module I18n
     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)
+      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)
     end
@@ -253,37 +265,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.
@@ -307,7 +322,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
@@ -362,7 +377,18 @@ module I18n
         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

@@ -5,6 +5,7 @@ module I18n
     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,16 +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?
@@ -94,10 +95,19 @@ 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 = EMPTY_HASH)
           raise NotImplementedError
@@ -234,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

@@ -100,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/chain.rb

@@ -17,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
 
@@ -26,10 +28,23 @@ 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 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
@@ -74,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