svenfuchs-i18n 0.1.3 → 0.2.0

data/CHANGELOG.textile

@@ -0,0 +1,57 @@
+h1. Changelog
+
+h2. master
+
+* (no changes)
+
+h2. 0.2.0 (2009-07-12, "fb9819c7efd3713c178c47b0722d0b39fff14131":http://github.com/svenfuchs/i18n/commit/fb9819c7efd3713c178c47b0722d0b39fff14131)
+
+* "Allow using Ruby 1.9 syntax for string interpolation (API addition)":http://github.com/svenfuchs/i18n/commit/c6e0b06d512f2af57199a843a1d8a40241b32861
+* "Allow configuring the default scope separator, allow to pass a custom scope separator (e.g. I18n.t(:'foo|bar', :separator => '|') (API addition)":http://github.com/svenfuchs/i18n/commit/5b75bfbc348061adc11e3790187a187275bfd471
+* "Pass :format option to #translate for #localize more useful lambda support":http://github.com/svenfuchs/i18n/commit/e277711b3c844fe7589b8d3f9af0f7d1b969a273
+* "Refactor Simple backend #resolve to #default and #resolve for more consistency. Now allows to pass lambdas as defaults and re-resolve Symbols":http://github.com/svenfuchs/i18n/commit/8c4ce3d923ce5fa73e973fe28217e18165549aba
+* "Add lambda support to #translate (API addition)":http://github.com/svenfuchs/i18n/commit/c90e62d8f7d3d5b78f34cfe328d871b58884f115
+* "Add lambda support to #localize (API addition)":http://github.com/svenfuchs/i18n/commit/9d390afcf33f3f469bb95e6888147152f6cc7442
+
+h2. 0.1.3 (2009-02-27)
+
+* "Remove unnecessary string encoding handling in the i18n simple backend which made the backend break on Ruby 1.9":http://github.com/svenfuchs/i18n/commit/4c3a970783861a94f2e89f46714fb3434e4f4f8d
+
+h2. 0.1.2 (2009-01-09)
+
+* "added #available_locales (returns an array of locales for which translations are available)":http://github.com/svenfuchs/i18n/commit/411f8fe7c8f3f89e9b6b921fa62ed66cb92f3af4
+* "flatten load_path before using it so that a nested array of paths won't throw up":http://github.com/svenfuchs/i18n/commit/d473a068a2b90aba98135deb225d6eb6d8104d70
+
+h2. 0.1.1 (2008-11-20)
+
+* "Use :'en' as a default locale (in favor of :'en-US')":http://github.com/svenfuchs/i18n/commit/c4b10b246aecf7da78cb2568dd0d2ab7e6b8a230
+* "Add #reload! to Simple backend":http://github.com/svenfuchs/i18n/commit/36dd2bd9973b9e1559728749a9daafa44693e964
+
+h2. 0.1.0 (2008-10-25)
+
+* "Fix Simple backend to distinguish false from nil values":http://github.com/svenfuchs/i18n/commit/39d9a47da14b5f3ba126af48923af8c30e135166
+* "Add #load_path to public api, add initialize to simple backend and remove #load_translations from public api":http://github.com/svenfuchs/i18n/commit/c4c5649e6bc8f020f1aaf5a5470bde048e22c82d
+* "Speed up Backend::Simple#interpolate":http://github.com/svenfuchs/i18n/commit/9e1ac6bf8833304e036323ec9932b9f33c468a35
+* "Remove #populate and #store_translations from public API":http://github.com/svenfuchs/i18n/commit/f4e514a80be7feb509f66824ee311905e2940900
+* "Use :other instead of :many as a plural key":http://github.com/svenfuchs/i18n/commit/0f8f20a2552bf6a2aa758d8fdd62a7154e4a1bf6
+* "Use a class instead of a module for Simple backend":http://github.com/svenfuchs/i18n/commit/08f051aa61320c17debde24a83268bc74e33b995
+* "Make Simple backend #interpolate deal with non-ASCII string encodings":http://github.com/svenfuchs/i18n/commit/d84a3f3f55543c084d5dc5d1fed613b8df148789
+* "Fix default arrays of non-existant keys returning the default array":http://github.com/svenfuchs/i18n/commit/6c04ca86c87f97dc78f07c2a4023644e5ba8b839
+
+h2. Initial implementation (June/July 2008)
+
+Initial implementation by "Sven Fuchs":http://www.workingwithrails.com/person/9963-sven-fuchs based on previous discussion/consensus of the rails-i18n team (alphabetical order) and many others:
+
+* "Matt Aimonetti":http://railsontherun.com
+* "Sven Fuchs":http://www.workingwithrails.com/person/9963-sven-fuchs
+* "Joshua Harvey":http://www.workingwithrails.com/person/759-joshua-harvey
+* "Saimon Moore":http://saimonmoore.net
+* "Stephan Soller":http://www.arkanis-development.de
+
+h2. More information
+
+* "Homepage":http://rails-i18n.org
+* "Wiki":http://rails-i18n.org/wiki
+* "Mailinglist":http://groups.google.com/group/rails-i18n
+* "About the project/history":http://www.artweb-design.de/2008/7/18/finally-ruby-on-rails-gets-internationalized
+* "Initial API Intro":http://www.artweb-design.de/2008/7/18/the-ruby-on-rails-i18n-core-api

data/Rakefile

@@ -0,0 +1,20 @@
+task :default => [:test]
+
+task :test do
+  ruby "test/all.rb"
+end
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |s|
+    s.name = "i18n"
+    s.summary = "New wave Internationalization support for Ruby"
+    s.email = "rails-i18n@googlegroups.com"
+    s.homepage = "http://rails-i18n.org"
+    s.description = "Add Internationalization support to your Ruby application."
+    s.authors = ['Sven Fuchs', 'Joshua Harvey', 'Matt Aimonetti', 'Stephan Soller', 'Saimon Moore']
+    s.files =  FileList["[A-Z]*", "{lib,test}/**/*"]
+  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

data/VERSION

@@ -0,0 +1 @@
+0.2.0

data/lib/i18n.rb

@@ -7,11 +7,13 @@
 # License::   MIT
 require 'i18n/backend/simple'
 require 'i18n/exceptions'
+require 'i18n/string'
 
 module I18n
   @@backend = nil
   @@load_path = nil
   @@default_locale = :'en'
+  @@default_separator = '.'
   @@exception_handler = :default_exception_handler
 
   class << self
@@ -50,6 +52,16 @@ module I18n
       backend.available_locales
     end
 
+    # Returns the current default scope separator. Defaults to '.'
+    def default_separator
+      @@default_separator
+    end
+
+    # Sets the current default scope separator.
+    def default_separator=(separator)
+      @@default_separator = separator
+    end
+
     # Sets the exception handler.
     def exception_handler=(exception_handler)
       @@exception_handler = exception_handler
@@ -150,7 +162,7 @@ module I18n
     # or <tt>default</tt> if no translations for <tt>:foo</tt> and <tt>:bar</tt> were found.
     #   I18n.t :foo, :default => [:bar, 'default']
     #
-    # <b>BULK LOOKUP</b>
+    # *BULK LOOKUP*
     #
     # This returns an array with the translations for <tt>:foo</tt> and <tt>:bar</tt>.
     #   I18n.t [:foo, :bar]
@@ -160,8 +172,26 @@ module I18n
     #
     # Which is the same as using a scope option:
     #   I18n.t [:foo, :bar], :scope => :baz
-    def translate(key, options = {})
-      locale = options.delete(:locale) || I18n.locale
+    #
+    # *LAMBDAS*
+    #
+    # Both translations and defaults can be given as Ruby lambdas. Lambdas will be
+    # 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
+    # always return the same translations/values per unique combination of argument
+    # values.
+    def translate(*args)
+      options = args.last.is_a?(Hash) ? args.pop : {}
+      key     = args.shift
+      locale  = options.delete(:locale) || I18n.locale
       backend.translate(locale, key, options)
     rescue I18n::ArgumentError => e
       raise e if options[:raise]
@@ -190,9 +220,9 @@ module I18n
     # 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.
-    def normalize_translation_keys(locale, key, scope)
-      keys = [locale] + Array(scope) + [key]
-      keys = keys.map { |k| k.to_s.split(/\./) }
+    def normalize_translation_keys(locale, key, scope, separator = nil)
+      keys = [locale] + Array(scope) + Array(key)
+      keys = keys.map { |k| k.to_s.split(separator || I18n.default_separator) }
       keys.flatten.map { |k| k.to_sym }
     end
   end

data/lib/i18n/backend/simple.rb

@@ -3,8 +3,8 @@ require 'yaml'
 module I18n
   module Backend
     class Simple
-      INTERPOLATION_RESERVED_KEYS = %w(scope default)
-      MATCH = /(\\\\)?\{\{([^\}]+)\}\}/
+      RESERVED_KEYS = [:scope, :default, :separator]
+      INTERPOLATION_SYNTAX_PATTERN = /(\\\\)?\{\{([^\}]+)\}\}/
 
       # Accepts a list of paths to translation files. Loads translations from
       # plain Ruby (*.rb) or YAML files (*.yml). See #load_rb and #load_yml
@@ -23,20 +23,15 @@ module I18n
 
       def translate(locale, key, options = {})
         raise InvalidLocale.new(locale) if locale.nil?
-        return key.map { |k| translate(locale, k, options) } if key.is_a? Array
-
-        reserved = :scope, :default
-        count, scope, default = options.values_at(:count, *reserved)
-        options.delete(:default)
-        values = options.reject { |name, value| reserved.include?(name) }
-
-        entry = lookup(locale, key, scope)
-        if entry.nil?
-          entry = default(locale, default, options)
-          if entry.nil?
-            raise(I18n::MissingTranslationData.new(locale, key, options))
-          end
-        end
+        return key.map { |k| translate(locale, k, options) } if key.is_a?(Array)
+
+        count, scope, default, separator = options.values_at(:count, *RESERVED_KEYS)
+        values = options.reject { |name, value| RESERVED_KEYS.include?(name) }
+
+        entry = lookup(locale, key, scope, separator)
+        entry = entry.nil? ? default(locale, key, default, options) : resolve(locale, key, entry, options)
+
+        raise(I18n::MissingTranslationData.new(locale, key, options)) if entry.nil?
         entry = pluralize(locale, entry, count)
         entry = interpolate(locale, entry, values)
         entry
@@ -45,23 +40,23 @@ module I18n
       # Acts the same as +strftime+, but returns a localized version of the
       # formatted date 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)
+      def localize(locale, object, format = :default, options={})
         raise ArgumentError, "Object must be a Date, DateTime or Time object. #{object.inspect} given." unless object.respond_to?(:strftime)
 
-        type = object.respond_to?(:sec) ? 'time' : 'date'
-        # TODO only translate these if format is a String?
-        formats = translate(locale, :"#{type}.formats")
-        format = formats[format.to_sym] if formats && formats[format.to_sym]
-        # TODO raise exception unless format found?
-        format = format.to_s.dup
-
-        # TODO only translate these if the format string is actually present
-        # TODO check which format strings are present, then bulk translate then, then replace them
-        format.gsub!(/%a/, translate(locale, :"date.abbr_day_names")[object.wday])
-        format.gsub!(/%A/, translate(locale, :"date.day_names")[object.wday])
-        format.gsub!(/%b/, translate(locale, :"date.abbr_month_names")[object.mon])
-        format.gsub!(/%B/, translate(locale, :"date.month_names")[object.mon])
-        format.gsub!(/%p/, translate(locale, :"time.#{object.hour < 12 ? :am : :pm}")) if object.respond_to? :hour
+        if Symbol === format
+          type = object.respond_to?(:sec) ? 'time' : 'date'
+          format = lookup(locale, :"#{type}.formats.#{format}")
+        end
+
+        format = resolve(locale, object, format, options.merge(:raise => true))
+
+        # TODO check which format strings are present, then bulk translate them, then replace them
+        format.gsub!(/%a/, translate(locale, :"date.abbr_day_names",   :format => format)[object.wday])   if format.include?('%a')
+        format.gsub!(/%A/, translate(locale, :"date.day_names",        :format => format)[object.wday])   if format.include?('%A')
+        format.gsub!(/%b/, translate(locale, :"date.abbr_month_names", :format => format)[object.mon])    if format.include?('%b')
+        format.gsub!(/%B/, translate(locale, :"date.month_names",      :format => format)[object.mon])    if format.include?('%B')
+        format.gsub!(/%p/, translate(locale, :"time.#{object.hour < 12 ? :am : :pm}", :format => format)) if format.include?('%p') && object.respond_to?(:hour)
+
         object.strftime(format)
       end
 
@@ -95,10 +90,10 @@ module I18n
         # nested translations hash. Splits keys or scopes containing dots
         # into multiple keys, i.e. <tt>currency.format</tt> is regarded the same as
         # <tt>%w(currency format)</tt>.
-        def lookup(locale, key, scope = [])
+        def lookup(locale, key, scope = [], separator = nil)
           return unless key
           init_translations unless initialized?
-          keys = I18n.send(:normalize_translation_keys, locale, key, scope)
+          keys = I18n.send(:normalize_translation_keys, locale, key, scope, separator)
           keys.inject(translations) do |result, k|
             if (x = result[k.to_sym]).nil?
               return nil
@@ -108,20 +103,34 @@ module I18n
           end
         end
 
-        # Evaluates a default translation.
-        # If the given default is a String it is used literally. If it is a Symbol
-        # it will be translated with the given options. If it is an Array the first
-        # translation yielded will be returned.
-        #
-        # <em>I.e.</em>, <tt>default(locale, [:foo, 'default'])</tt> will return +default+ if
-        # <tt>translate(locale, :foo)</tt> does not yield a result.
-        def default(locale, default, options = {})
-          case default
-            when String then default
-            when Symbol then translate locale, default, options
-            when Array  then default.each do |obj|
-              result = default(locale, obj, options.dup) and return result
+        # Evaluates defaults.
+        # 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 }
+          case subject
+          when Array
+            subject.each do |subject|
+              result = resolve(locale, object, subject, options) and return result
             end and nil
+          else
+            resolve(locale, object, subject, options)
+          end
+        end
+
+        # Resolves a translation.
+        # 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 = {})
+          case subject
+          when Symbol
+            translate(locale, subject, options)
+          when Proc
+            resolve(locale, object, subject.call(object, options), options = {})
+          else
+            subject
           end
         rescue MissingTranslationData
           nil
@@ -133,7 +142,7 @@ module I18n
         # implement more flexible or complex pluralization rules.
         def pluralize(locale, entry, count)
           return entry unless entry.is_a?(Hash) and count
-          # raise InvalidPluralizationData.new(entry, count) unless entry.is_a?(Hash)
+
           key = :zero if count == 0 && entry.has_key?(:zero)
           key ||= count == 1 ? :one : :other
           raise InvalidPluralizationData.new(entry, count) unless entry.has_key?(key)
@@ -149,21 +158,22 @@ module I18n
         # the <tt>{{...}}</tt> key in a string (once for the string and once for the
         # interpolation).
         def interpolate(locale, string, values = {})
-          return string unless string.is_a?(String)
+          return string unless string.is_a?(String) && !values.empty?
 
-          string.gsub(MATCH) do
-            escaped, pattern, key = $1, $2, $2.to_sym
+          string.gsub(INTERPOLATION_SYNTAX_PATTERN) do
+            escaped, key = $1, $2.to_sym
 
             if escaped
-              pattern
-            elsif INTERPOLATION_RESERVED_KEYS.include?(pattern)
-              raise ReservedInterpolationKey.new(pattern, string)
-            elsif !values.include?(key)
-              raise MissingInterpolationArgument.new(pattern, string)
+              key
+            elsif RESERVED_KEYS.include?(key)
+              raise ReservedInterpolationKey.new(key, string)
             else
-              values[key].to_s
+              "%{#{key}}"
             end
-          end
+          end % values
+
+        rescue KeyError => e
+          raise MissingInterpolationArgument.new(values, string)
         end
 
         # Loads a single translations file by delegating to #load_rb or
@@ -204,11 +214,20 @@ module I18n
         # Return a new hash with all keys and nested keys converted to symbols.
         def deep_symbolize_keys(hash)
           hash.inject({}) { |result, (key, value)|
-            value = deep_symbolize_keys(value) if value.is_a? Hash
+            value = deep_symbolize_keys(value) if value.is_a?(Hash)
             result[(key.to_sym rescue key) || key] = value
             result
           }
         end
+
+        # Flatten the given array once
+        def flatten_once(array)
+          result = []
+          for element in array # a little faster than each
+            result.push(*element)
+          end
+          result
+        end
     end
   end
 end

data/lib/i18n/exceptions.rb

@@ -1,3 +1,9 @@
+class KeyError < IndexError
+  def initialize(message = nil)
+    super(message || "key not found")
+  end
+end unless defined?(KeyError)
+
 module I18n
   class ArgumentError < ::ArgumentError; end
 
@@ -28,10 +34,10 @@ module I18n
   end
 
   class MissingInterpolationArgument < ArgumentError
-    attr_reader :key, :string
-    def initialize(key, string)
-      @key, @string = key, string
-      super "interpolation argument #{key} missing in #{string.inspect}"
+    attr_reader :values, :string
+    def initialize(values, string)
+      @values, @string = values, string
+      super "missing interpolation argument in #{string.inspect} (#{values.inspect} given)"
     end
   end
 

data/lib/i18n/string.rb

@@ -0,0 +1,93 @@
+=begin
+  heavily based on Masao Mutoh's gettext String interpolation extension
+  http://github.com/mutoh/gettext/blob/f6566738b981fe0952548c421042ad1e0cdfb31e/lib/gettext/core_ext/string.rb
+  Copyright (C) 2005-2009 Masao Mutoh
+  You may redistribute it and/or modify it under the same license terms as Ruby.
+=end
+
+if RUBY_VERSION < '1.9'
+
+  # KeyError is raised by String#% when the string contains a named placeholder
+  # that is not contained in the given arguments hash. Ruby 1.9 includes and
+  # raises this exception natively. We define it to mimic Ruby 1.9's behaviour
+  # in Ruby 1.8.x
+
+  class KeyError < IndexError
+    def initialize(message = nil)
+      super(message || "key not found")
+    end
+  end unless defined?(KeyError)
+
+  # Extension for String class. This feature is included in Ruby 1.9 or later but not occur TypeError.
+  #
+  # String#% method which accept "named argument". The translator can know
+  # the meaning of the msgids using "named argument" instead of %s/%d style.
+
+  class String
+    # For older ruby versions, such as ruby-1.8.5
+    alias :bytesize :size unless instance_methods.find {|m| m.to_s == 'bytesize'}
+    alias :interpolate_without_ruby_19_syntax :% # :nodoc:
+
+    INTERPOLATION_PATTERN = Regexp.union(
+      /%%/,
+      /%\{(\w+)\}/,                               # matches placeholders like "%{foo}"
+      /%<(\w+)>(.*?\d*\.?\d*[bBdiouxXeEfgGcps])/  # matches placeholders like "%<foo>.d"
+    )
+
+    # % uses self (i.e. the String) as a format specification and returns the
+    # result of applying it to the given arguments. In other words it interpolates
+    # the given arguments to the string according to the formats the string
+    # defines.
+    #
+    # There are three ways to use it:
+    #
+    # * Using a single argument or Array of arguments.
+    #
+    #   This is the default behaviour of the String class. See Kernel#sprintf for
+    #   more details about the format string.
+    #
+    #   Example:
+    #
+    #     "%d %s" % [1, "message"]
+    #     # => "1 message"
+    #
+    # * Using a Hash as an argument and unformatted, named placeholders.
+    #
+    #   When you pass a Hash as an argument and specify placeholders with %{foo}
+    #   it will interpret the hash values as named arguments.
+    #
+    #   Example:
+    #
+    #     "%{firstname}, %{lastname}" % {:firstname => "Masao", :lastname => "Mutoh"}
+    #     # => "Masao Mutoh"
+    #
+    # * Using a Hash as an argument and formatted, named placeholders.
+    #
+    #   When you pass a Hash as an argument and specify placeholders with %<foo>d
+    #   it will interpret the hash values as named arguments and format the value
+    #   according to the formatting instruction appended to the closing >.
+    #
+    #   Example:
+    #
+    #     "%<integer>d, %<float>.1f" % { :integer => 10, :float => 43.4 }
+    #     # => "10, 43.3"
+    def %(args)
+      if args.kind_of?(Hash)
+        dup.gsub(INTERPOLATION_PATTERN) do |match|
+          if match == '%%'
+            '%'
+          else
+            key = ($1 || $2).to_sym
+            raise KeyError unless args.has_key?(key)
+            $3 ? sprintf("%#{$3}", args[key]) : args[key]
+          end
+        end
+      elsif self =~ INTERPOLATION_PATTERN
+        raise ArgumentError.new('one hash required')
+      else
+        result = gsub(/%([{<])/, '%%\1')
+        result.send :'interpolate_without_ruby_19_syntax', args
+      end
+    end
+  end
+end