i18n 0.2.1 → 0.3.0

data/README.textile

@@ -1,20 +1,55 @@
-h1. Ruby I18n gem
+h1. Ruby I18n
 
-I18n and localization solution for Ruby.
+Ruby Internationalization and localization solution.
 
-For information please refer to http://rails-i18n.org
+Features:
+
+* translation and localization
+* interpolation of values to translations (Ruby 1.9 compatible syntax)
+* pluralization (CLDR compatible)
+* flexible defaults
+* bulk lookup
+* lambdas as translation data
+* custom key/scope separator
+* custom exception handlers
+* extensible architecture with a swappable backend
+
+Experimental, pluggable features:
+
+* lambda pluralizers stored as translation data
+* RFC4647 compliant locale fallbacks (with optional RFC4646 locale validation)
+* backend cache
+
+For more information and lots of resources see: "http://rails-i18n.org/wiki":http://rails-i18n.org/wiki
+
+h2. Install
+
+gem install i18n
+
+h3. Install on Rails 2.3.4 (deprecated)
+
+Rails 2.3.4 will not accept i18n gems > 0.1.3. There is an unpacked gem inside of active_support/lib/vendor which gets loaded unless gem 'i18n', '~> 0.1.3'. This requirement is relaxed in http://github.com/rails/rails/commit/6da036538334fd459156ab2789c9fae5512be5d2
+
+The following is needed to get the new i18n gem inside vendor/plugins loaded properly.
+
+      def reload_i18n!
+        raise "Move to i18n version 0.2.0 or greater" if Rails.version > "2.3.4"
+
+        $:.grep(/i18n/).each { |path| $:.delete(path) }
+        I18n::Backend.send :remove_const, "Simple"
+        $: << Rails.root.join('vendor', 'plugins', 'i18n', 'lib').to_s
+      end
+
+Then you can `reload_i18n!` inside an i18n initializer. 
 
 h2. Authors
 
-* "Matt Aimonetti":http://railsontherun.com
 * "Sven Fuchs":http://www.artweb-design.de
 * "Joshua Harvey":http://www.workingwithrails.com/person/759-joshua-harvey
-* "Saimon Moore":http://saimonmoore.net
 * "Stephan Soller":http://www.arkanis-development.de
+* "Saimon Moore":http://saimonmoore.net
+* "Matt Aimonetti":http://railsontherun.com
 
 h2. License
 
-MIT License. See the included MIT-LICENCE file.
-
-
-
+MIT License. See the included MIT-LICENCE file.

data/Rakefile

@@ -8,6 +8,7 @@ begin
   require 'jeweler'
   Jeweler::Tasks.new do |s|
     s.name = "i18n"
+    s.rubyforge_project = "i18n"
     s.summary = "New wave Internationalization support for Ruby"
     s.email = "rails-i18n@googlegroups.com"
     s.homepage = "http://rails-i18n.org"
@@ -17,4 +18,4 @@ begin
   end
 rescue LoadError
   puts "Jeweler, or one of its dependencies, is not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
-end
+end

data/VERSION

@@ -1 +1 @@
-0.2.1
+0.3.0

data/lib/i18n.rb

@@ -1,18 +1,23 @@
-# Authors::   Matt Aimonetti (http://railsontherun.com/),
-#             Sven Fuchs (http://www.artweb-design.de),
+# encoding: utf-8
+
+# Authors::   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),
-#             Stephan Soller (http://www.arkanis-development.de/)
+#             Matt Aimonetti (http://railsontherun.com/)
 # Copyright:: Copyright (c) 2008 The Ruby i18n Team
 # License::   MIT
-require 'i18n/backend/simple'
 require 'i18n/exceptions'
-require 'i18n/string'
+require 'i18n/core_ext/string/interpolate'
 
 module I18n
+  autoload :Backend, 'i18n/backend'
+  autoload :Helpers, 'i18n/helpers'
+  autoload :Locale,  'i18n/locale'
+
   @@backend = nil
   @@load_path = nil
-  @@default_locale = :'en'
+  @@default_locale = :en
   @@default_separator = '.'
   @@exception_handler = :default_exception_handler
 
@@ -34,7 +39,7 @@ module I18n
 
     # Sets the current default locale. Used to set a custom default locale.
     def default_locale=(locale)
-      @@default_locale = locale
+      @@default_locale = locale.to_sym rescue nil
     end
 
     # Returns the current locale. Defaults to I18n.default_locale.
@@ -44,12 +49,19 @@ module I18n
 
     # Sets the current locale pseudo-globally, i.e. in the Thread.current hash.
     def locale=(locale)
-      Thread.current[:locale] = locale
+      Thread.current[:locale] = locale.to_sym rescue nil
     end
 
-    # Returns an array of locales for which translations are available
+    # Returns an array of locales for which translations are available.
+    # Unless you explicitely set the these through I18n.available_locales=
+    # the call will be delegated to the backend and memoized on the I18n module.
     def available_locales
-      backend.available_locales
+      @@available_locales ||= backend.available_locales
+    end
+
+    # Sets the available locales.
+    def available_locales=(locales)
+      @@available_locales = locales
     end
 
     # Returns the current default scope separator. Defaults to '.'
@@ -176,13 +188,13 @@ module I18n
     # *LAMBDAS*
     #
     # Both translations and defaults can be given as Ruby lambdas. Lambdas will be
-    # called and passed the key and options. 
+    # called and passed the key and options.
     #
     # E.g. assuming the key <tt>:salutation</tt> resolves to:
     #   lambda { |key, options| options[:gender] == 'm' ? "Mr. {{options[:name]}}" : "Mrs. {{options[:name]}}" }
     #
     # Then <tt>I18n.t(:salutation, :gender => 'w', :name => 'Smith') will result in "Mrs. Smith".
-    # 
+    #
     # 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
@@ -192,13 +204,19 @@ module I18n
       options = args.last.is_a?(Hash) ? args.pop : {}
       key     = args.shift
       locale  = options.delete(:locale) || I18n.locale
+      raises  = options.delete(:raise)
       backend.translate(locale, key, options)
-    rescue I18n::ArgumentError => e
-      raise e if options[:raise]
-      send(@@exception_handler, e, locale, key, options)
+    rescue I18n::ArgumentError => exception
+      raise exception if raises
+      handle_exception(exception, locale, key, options)
     end
     alias :t :translate
 
+    def translate!(key, options = {})
+      translate(key, options.merge( :raise => true ))
+    end
+    alias :t! :translate!
+
     # Localizes certain objects, such as dates and numbers to local formatting.
     def localize(object, options = {})
       locale = options[:locale] || I18n.locale
@@ -208,6 +226,7 @@ module I18n
     alias :l :localize
 
   protected
+
     # Handles exceptions raised in the backend. All exceptions except for
     # MissingTranslationData exceptions are re-raised. When a MissingTranslationData
     # was caught and the option :raise is not set the handler returns an error
@@ -217,6 +236,32 @@ module I18n
       raise exception
     end
 
+    # Any exceptions thrown in translate will be sent to the @@exception_handler
+    # which can be a Symbol, a Proc or any other Object.
+    #
+    # If exception_handler is a Symbol then it will simply be sent to I18n as
+    # a method call. A Proc will simply be called. In any other case the
+    # method #call will be called on the exception_handler object.
+    #
+    # Examples:
+    #
+    #   I18n.exception_handler = :default_exception_handler             # this is the default
+    #   I18n.default_exception_handler(exception, locale, key, options) # will be called like this
+    #
+    #   I18n.exception_handler = lambda { |*args| ... }                 # a lambda
+    #   I18n.exception_handler.call(exception, locale, key, options)    # will be called like this
+    #
+    #  I18n.exception_handler = I18nExceptionHandler.new                # an object
+    #  I18n.exception_handler.call(exception, locale, key, options)     # will be called like this
+    def handle_exception(exception, locale, key, options)
+      case @@exception_handler
+      when Symbol
+        send(@@exception_handler, exception, locale, key, options)
+      else
+        @@exception_handler.call(exception, locale, key, options)
+      end
+    end
+
     # Merges the given locale, key and scope into a single array of keys.
     # Splits keys that contain dots into multiple keys. Makes sure all
     # keys are Symbols.

data/lib/i18n/backend.rb

@@ -0,0 +1,14 @@
+module I18n
+  module Backend
+    autoload :ActiveRecord,  'i18n/backend/active_record'
+    autoload :Base,          'i18n/backend/base'
+    autoload :Cache,         'i18n/backend/cache'
+    autoload :Chain,         'i18n/backend/chain'
+    autoload :Fallbacks,     'i18n/backend/fallbacks'
+    autoload :Gettext,       'i18n/backend/gettext'
+    autoload :Helpers,       'i18n/backend/helpers'
+    autoload :Metadata,      'i18n/backend/metadata'
+    autoload :Pluralization, 'i18n/backend/pluralization'
+    autoload :Simple,        'i18n/backend/simple'
+  end
+end

data/lib/i18n/backend/active_record.rb

@@ -0,0 +1,69 @@
+require 'i18n/backend/base'
+require 'i18n/backend/active_record/translation'
+
+#
+#  This backend reads translations from a Translations table in environment database. Note that the database
+#  will not automatically be prepopulated with missing keys. You can achieve this effect with the ActiveRecordMissing backend, 
+#  as the following example shows:
+#
+#     I18n.backend = I18n::Backend::Chain.new(I18n::Backend::ActiveRecord.new, I18.backend, I18n::Backend::ActiveRecordMissing.new)
+#  
+module I18n
+  module Backend
+    class ActiveRecord
+      autoload :StoreProcs,  'i18n/backend/active_record/store_procs'
+      autoload :Translation, 'i18n/backend/active_record/translation'
+
+      include Base
+
+      def reload!
+      end
+
+      def store_translations(locale, data)
+        separator = I18n.default_separator # TODO allow to pass as an option?
+        wind_keys(data).each do |key, v|
+          Translation.locale(locale).lookup(expand_keys(key, separator), separator).delete_all
+          Translation.create(:locale => locale.to_s, :key => key, :value => v)
+        end
+      end
+
+      def available_locales
+        begin
+          Translation.available_locales
+        rescue ::ActiveRecord::StatementInvalid
+          []
+        end
+      end
+
+      protected
+
+        def lookup(locale, key, scope = [], separator = nil)
+          return unless key
+
+          separator ||= I18n.default_separator
+          key = (Array(scope) + Array(key)).join(separator)
+
+          result = Translation.locale(locale).lookup(key, separator).all
+          if result.empty?
+            return nil
+          elsif result.first.key == key
+            return result.first.value
+          else
+            chop_range = (key.size + separator.size)..-1
+            result = result.inject({}) do |hash, r|
+              hash[r.key.slice(chop_range)] = r.value
+              hash
+            end
+            deep_symbolize_keys(unwind_keys(result))
+          end
+        end
+
+        # For a key :'foo.bar.baz' return ['foo', 'foo.bar', 'foo.bar.baz']
+        def expand_keys(key, separator = I18n.default_separator)
+          key.to_s.split(separator).inject([]) do |keys, key|
+            keys << [keys.last, key].compact.join(separator)
+          end
+        end
+    end
+  end
+end

data/lib/i18n/backend/active_record/store_procs.rb

@@ -0,0 +1,37 @@
+# This module is intended to be mixed into the ActiveRecord backend to allow
+# storing Ruby Procs as translation values in the database.
+#
+#   I18n.backend = I18n::Backend::ActiveRecord.new
+#   I18n::Backend::ActiveRecord::Translation.send(:include, I18n::Backend::ActiveRecord::StoreProcs)
+#
+# The StoreProcs module requires the ParseTree and ruby2ruby gems and therefor
+# was extracted from the original backend.
+#
+# ParseTree is not compatible with Ruby 1.9.
+module I18n
+  module Backend
+    class ActiveRecord
+      module StoreProcs
+        unless RUBY_VERSION >= '1.9'
+          class << self
+            def included(target)
+              require 'ruby2ruby'
+              require 'parse_tree'
+              require 'parse_tree_extensions'
+            end
+          end
+
+          def value=(v)
+            case v
+              when Proc
+                write_attribute(:value, v.to_ruby)
+                write_attribute(:is_proc, true)
+              else
+                write_attribute(:value, v)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/i18n/backend/active_record/translation.rb

@@ -0,0 +1,82 @@
+require 'active_record'
+
+module I18n
+  module Backend
+    # ActiveRecord model used to store actual translations to the database.
+    #
+    # This model expects a table like the following to be already set up in
+    # your the database:
+    #
+    #   create_table :translations do |t|
+    #     t.string :locale
+    #     t.string :key
+    #     t.string :value
+    #     t.boolean :is_proc, :default => false
+    #   end
+    #
+    # This model supports to named scopes :locale and :lookup. The :locale
+    # scope simply adds a condition for a given locale:
+    #
+    #   I18n::Backend::ActiveRecord::Translation.locale(:en).all
+    #   # => all translation records that belong to the :en locale
+    #
+    # The :lookup scope adds a condition for looking up all translations
+    # that either start with the given keys (joined by an optionally given
+    # separator or I18n.default_separator) or that exactly have this key.
+    #
+    #   # with translations present for :"foo.bar" and :"foo.baz"
+    #   I18n::Backend::ActiveRecord::Translation.lookup(:foo)
+    #   # => an array with both translation records :"foo.bar" and :"foo.baz"
+    #
+    #   I18n::Backend::ActiveRecord::Translation.lookup([:foo, :bar])
+    #   I18n::Backend::ActiveRecord::Translation.lookup(:"foo.bar")
+    #   # => an array with the translation record :"foo.bar"
+    #
+    # When the StoreProcs module was mixed into this model then Procs will
+    # be stored to the database as Ruby code and evaluated when :value is
+    # called.
+    #
+    #   Translation = I18n::Backend::ActiveRecord::Translation
+    #   Translation.create \
+    #     :locale => 'en'
+    #     :key    => 'foo'
+    #     :value  => lambda { |key, options| 'FOO' }
+    #   Translation.find_by_locale_and_key('en', 'foo').value
+    #   # => 'FOO'
+    class ActiveRecord
+      class Translation < ::ActiveRecord::Base
+        set_table_name 'translations'
+        attr_protected :is_proc, :interpolations
+        
+        serialize :value
+        serialize :interpolations, Array
+
+        named_scope :locale, lambda { |locale|
+          { :conditions => { :locale => locale.to_s } }
+        }
+
+        named_scope :lookup, lambda { |keys, *separator|
+          keys = Array(keys).map! { |key| key.to_s }
+          separator ||= I18n.default_separator
+          { :conditions => ["`key` IN (?) OR `key` LIKE '#{keys.last}#{separator}%'", keys] }
+        }
+
+        def self.available_locales
+          Translation.find(:all, :select => 'DISTINCT locale').map { |t| t.locale }
+        end
+        
+        def interpolates?(key)
+          self.interpolations.include?(key) if self.interpolations
+        end
+
+        def value
+          if is_proc
+            Kernel.eval read_attribute(:value)
+          else
+            read_attribute(:value)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/i18n/backend/active_record_missing.rb

@@ -0,0 +1,55 @@
+#
+#  This extension stores untranslated keys as translation stubs in the database. This is useful if you have a web based
+#  translation tool. It will populate with untranslated keys as the application is being used. A translator can then go
+#  through these. Example usage:
+#
+#     I18n::Backend::Chain.send(:include, I18n::Backend::ActiveRecordMissing)
+#     I18n.backend = I18nChainBackend.new(I18n::Backend::ActiveRecord.new, I18n::Backend::Simple.new)
+#
+#  Stubs for pluralizations will also be created for each key defined in i18n.plural_keys. Eg:
+#
+#     en:
+#       i18n:
+#         plural_keys: [:zero, :one, :other]
+#
+#     pl:
+#       i18n:
+#         plural_keys: [:zero, :one, :few, :other]
+#
+#  This extension can also persist interpolation keys in Translation#interpolations. This is useful for translators
+#  who cannot infer possible interpolations from the keys, as they can with other solutions such as gettext or globalize.
+#
+module I18n
+  module Backend
+    module ActiveRecordMissing
+
+      def store_default_translations(locale, key, options = {})
+        count, scope, default, separator = options.values_at(:count, *Base::RESERVED_KEYS)
+        separator ||= I18n.default_separator
+        keys = I18n.send(:normalize_translation_keys, locale, key, scope, separator)[1..-1]
+        key = keys.join(separator || I18n.default_separator)
+
+        unless ActiveRecord::Translation.locale(locale).lookup(key, separator).exists?
+          interpolations = options.reject { |name, value| Base::RESERVED_KEYS.include?(name) }.keys
+          keys = count ? I18n.t('i18n.plural_keys', :locale => locale).map { |k| [key, k].join(separator) } : [key]
+          keys.each { |key| store_default_translation(locale, key, interpolations) } 
+        end
+      end
+
+      def store_default_translation(locale, key, interpolations)
+        translation = ActiveRecord::Translation.new :locale => locale.to_s, :key => key
+        translation.interpolations = interpolations
+        translation.save
+      end
+      
+      def translate(locale, key, options = {})
+        super
+
+        rescue I18n::MissingTranslationData => e
+          self.store_default_translations(locale, key, options)
+
+          raise e
+      end
+    end
+  end
+end