lib/mcollective/vendor/i18n/lib/i18n.rb

   1 require 'i18n/version'
   2 require 'i18n/exceptions'
   3 require 'i18n/interpolate/ruby'
   4
   5 module I18n
   6   autoload :Backend, 'i18n/backend'
   7   autoload :Config,  'i18n/config'
   8   autoload :Gettext, 'i18n/gettext'
   9   autoload :Locale,  'i18n/locale'
  10   autoload :Tests,   'i18n/tests'
  11
  12   RESERVED_KEYS = [:scope, :default, :separator, :resolve, :object, :fallback, :format, :cascade, :throw, :raise, :rescue_format]
  13   RESERVED_KEYS_PATTERN = /%\{(#{RESERVED_KEYS.join("|")})\}/
  14
  15   extend Module.new {
  16     # Gets I18n configuration object.
  17     def config
  18       Thread.current[:i18n_config] ||= I18n::Config.new
  19     end
  20
  21     # Sets I18n configuration object.
  22     def config=(value)
  23       Thread.current[:i18n_config] = value
  24     end
  25
  26     # Write methods which delegates to the configuration object
  27     %w(locale backend default_locale available_locales default_separator
  28       exception_handler load_path).each do |method|
  29       module_eval <<-DELEGATORS, __FILE__, __LINE__ + 1
  30         def #{method}
  31           config.#{method}
  32         end
  33
  34         def #{method}=(value)
  35           config.#{method} = (value)
  36         end
  37       DELEGATORS
  38     end
  39
  40     # Tells the backend to reload translations. Used in situations like the
  41     # Rails development environment. Backends can implement whatever strategy
  42     # is useful.
  43     def reload!
  44       config.backend.reload!
  45     end
  46
  47     # Translates, pluralizes and interpolates a given key using a given locale,
  48     # scope, and default, as well as interpolation values.
  49     #
  50     # *LOOKUP*
  51     #
  52     # Translation data is organized as a nested hash using the upper-level keys
  53     # as namespaces. <em>E.g.</em>, ActionView ships with the translation:
  54     # <tt>:date => {:formats => {:short => "%b %d"}}</tt>.
  55     #
  56     # Translations can be looked up at any level of this hash using the key argument
  57     # and the scope option. <em>E.g.</em>, in this example <tt>I18n.t :date</tt>
  58     # returns the whole translations hash <tt>{:formats => {:short => "%b %d"}}</tt>.
  59     #
  60     # Key can be either a single key or a dot-separated key (both Strings and Symbols
  61     # work). <em>E.g.</em>, the short format can be looked up using both:
  62     #   I18n.t 'date.formats.short'
  63     #   I18n.t :'date.formats.short'
  64     #
  65     # Scope can be either a single key, a dot-separated key or an array of keys
  66     # or dot-separated keys. Keys and scopes can be combined freely. So these
  67     # examples will all look up the same short date format:
  68     #   I18n.t 'date.formats.short'
  69     #   I18n.t 'formats.short', :scope => 'date'
  70     #   I18n.t 'short', :scope => 'date.formats'
  71     #   I18n.t 'short', :scope => %w(date formats)
  72     #
  73     # *INTERPOLATION*
  74     #
  75     # Translations can contain interpolation variables which will be replaced by
  76     # values passed to #translate as part of the options hash, with the keys matching
  77     # the interpolation variable names.
  78     #
  79     # <em>E.g.</em>, with a translation <tt>:foo => "foo %{bar}"</tt> the option
  80     # value for the key +bar+ will be interpolated into the translation:
  81     #   I18n.t :foo, :bar => 'baz' # => 'foo baz'
  82     #
  83     # *PLURALIZATION*
  84     #
  85     # Translation data can contain pluralized translations. Pluralized translations
  86     # are arrays of singluar/plural versions of translations like <tt>['Foo', 'Foos']</tt>.
  87     #
  88     # Note that <tt>I18n::Backend::Simple</tt> only supports an algorithm for English
  89     # pluralization rules. Other algorithms can be supported by custom backends.
  90     #
  91     # This returns the singular version of a pluralized translation:
  92     #   I18n.t :foo, :count => 1 # => 'Foo'
  93     #
  94     # These both return the plural version of a pluralized translation:
  95     #   I18n.t :foo, :count => 0 # => 'Foos'
  96     #   I18n.t :foo, :count => 2 # => 'Foos'
  97     #
  98     # The <tt>:count</tt> option can be used both for pluralization and interpolation.
  99     # <em>E.g.</em>, with the translation
 100     # <tt>:foo => ['%{count} foo', '%{count} foos']</tt>, count will
 101     # be interpolated to the pluralized translation:
 102     #   I18n.t :foo, :count => 1 # => '1 foo'
 103     #
 104     # *DEFAULTS*
 105     #
 106     # This returns the translation for <tt>:foo</tt> or <tt>default</tt> if no translation was found:
 107     #   I18n.t :foo, :default => 'default'
 108     #
 109     # This returns the translation for <tt>:foo</tt> or the translation for <tt>:bar</tt> if no
 110     # translation for <tt>:foo</tt> was found:
 111     #   I18n.t :foo, :default => :bar
 112     #
 113     # Returns the translation for <tt>:foo</tt> or the translation for <tt>:bar</tt>
 114     # or <tt>default</tt> if no translations for <tt>:foo</tt> and <tt>:bar</tt> were found.
 115     #   I18n.t :foo, :default => [:bar, 'default']
 116     #
 117     # *BULK LOOKUP*
 118     #
 119     # This returns an array with the translations for <tt>:foo</tt> and <tt>:bar</tt>.
 120     #   I18n.t [:foo, :bar]
 121     #
 122     # Can be used with dot-separated nested keys:
 123     #   I18n.t [:'baz.foo', :'baz.bar']
 124     #
 125     # Which is the same as using a scope option:
 126     #   I18n.t [:foo, :bar], :scope => :baz
 127     #
 128     # *LAMBDAS*
 129     #
 130     # Both translations and defaults can be given as Ruby lambdas. Lambdas will be
 131     # called and passed the key and options.
 132     #
 133     # E.g. assuming the key <tt>:salutation</tt> resolves to:
 134     #   lambda { |key, options| options[:gender] == 'm' ? "Mr. %{options[:name]}" : "Mrs. %{options[:name]}" }
 135     #
 136     # Then <tt>I18n.t(:salutation, :gender => 'w', :name => 'Smith') will result in "Mrs. Smith".
 137     #
 138     # It is recommended to use/implement lambdas in an "idempotent" way. E.g. when
 139     # a cache layer is put in front of I18n.translate it will generate a cache key
 140     # from the argument values passed to #translate. Therefor your lambdas should
 141     # always return the same translations/values per unique combination of argument
 142     # values.
 143     def translate(*args)
 144       options  = args.last.is_a?(Hash) ? args.pop : {}
 145       key      = args.shift
 146       backend  = config.backend
 147       locale   = options.delete(:locale) || config.locale
 148       handling = options.delete(:throw) && :throw || options.delete(:raise) && :raise # TODO deprecate :raise
 149
 150       raise I18n::ArgumentError if key.is_a?(String) && key.empty?
 151
 152       result = catch(:exception) do
 153         if key.is_a?(Array)
 154           key.map { |k| backend.translate(locale, k, options) }
 155         else
 156           backend.translate(locale, key, options)
 157         end
 158       end
 159       result.is_a?(MissingTranslation) ? handle_exception(handling, result, locale, key, options) : result
 160     end
 161     alias :t :translate
 162
 163     # Wrapper for <tt>translate</tt> that adds <tt>:raise => true</tt>. With
 164     # this option, if no translation is found, it will raise <tt>I18n::MissingTranslationData</tt>
 165     def translate!(key, options={})
 166       translate(key, options.merge(:raise => true))
 167     end
 168     alias :t! :translate!
 169
 170     # Transliterates UTF-8 characters to ASCII. By default this method will
 171     # transliterate only Latin strings to an ASCII approximation:
 172     #
 173     #    I18n.transliterate("Ærøskøbing")
 174     #    # => "AEroskobing"
 175     #
 176     #    I18n.transliterate("日本語")
 177     #    # => "???"
 178     #
 179     # It's also possible to add support for per-locale transliterations. I18n
 180     # expects transliteration rules to be stored at
 181     # <tt>i18n.transliterate.rule</tt>.
 182     #
 183     # Transliteration rules can either be a Hash or a Proc. Procs must accept a
 184     # single string argument. Hash rules inherit the default transliteration
 185     # rules, while Procs do not.
 186     #
 187     # *Examples*
 188     #
 189     # Setting a Hash in <locale>.yml:
 190     #
 191     #    i18n:
 192     #      transliterate:
 193     #        rule:
 194     #          ü: "ue"
 195     #          ö: "oe"
 196     #
 197     # Setting a Hash using Ruby:
 198     #
 199     #     store_translations(:de, :i18n => {
 200     #       :transliterate => {
 201     #         :rule => {
 202     #           "ü" => "ue",
 203     #           "ö" => "oe"
 204     #         }
 205     #       }
 206     #     )
 207     #
 208     # Setting a Proc:
 209     #
 210     #     translit = lambda {|string| MyTransliterator.transliterate(string) }
 211     #     store_translations(:xx, :i18n => {:transliterate => {:rule => translit})
 212     #
 213     # Transliterating strings:
 214     #
 215     #     I18n.locale = :en
 216     #     I18n.transliterate("Jürgen") # => "Jurgen"
 217     #     I18n.locale = :de
 218     #     I18n.transliterate("Jürgen") # => "Juergen"
 219     #     I18n.transliterate("Jürgen", :locale => :en) # => "Jurgen"
 220     #     I18n.transliterate("Jürgen", :locale => :de) # => "Juergen"
 221     def transliterate(*args)
 222       options      = args.pop if args.last.is_a?(Hash)
 223       key          = args.shift
 224       locale       = options && options.delete(:locale) || config.locale
 225       handling     = options && (options.delete(:throw) && :throw || options.delete(:raise) && :raise)
 226       replacement  = options && options.delete(:replacement)
 227       config.backend.transliterate(locale, key, replacement)
 228     rescue I18n::ArgumentError => exception
 229       handle_exception(handling, exception, locale, key, options || {})
 230     end
 231
 232     # Localizes certain objects, such as dates and numbers to local formatting.
 233     def localize(object, options = {})
 234       locale = options.delete(:locale) || config.locale
 235       format = options.delete(:format) || :default
 236       config.backend.localize(locale, object, format, options)
 237     end
 238     alias :l :localize
 239
 240     # Executes block with given I18n.locale set.
 241     def with_locale(tmp_locale = nil)
 242       if tmp_locale
 243         current_locale = self.locale
 244         self.locale    = tmp_locale
 245       end
 246       yield
 247     ensure
 248       self.locale = current_locale if tmp_locale
 249     end
 250
 251     # Merges the given locale, key and scope into a single array of keys.
 252     # Splits keys that contain dots into multiple keys. Makes sure all
 253     # keys are Symbols.
 254     def normalize_keys(locale, key, scope, separator = nil)
 255       separator ||= I18n.default_separator
 256
 257       keys = []
 258       keys.concat normalize_key(locale, separator)
 259       keys.concat normalize_key(scope, separator)
 260       keys.concat normalize_key(key, separator)
 261       keys
 262     end
 263
 264   # making these private until Ruby 1.9.2 can send to protected methods again
 265   # see http://redmine.ruby-lang.org/repositories/revision/ruby-19?rev=24280
 266   private
 267
 268     # Any exceptions thrown in translate will be sent to the @@exception_handler
 269     # which can be a Symbol, a Proc or any other Object unless they're forced to
 270     # be raised or thrown (MissingTranslation).
 271     #
 272     # If exception_handler is a Symbol then it will simply be sent to I18n as
 273     # a method call. A Proc will simply be called. In any other case the
 274     # method #call will be called on the exception_handler object.
 275     #
 276     # Examples:
 277     #
 278     #   I18n.exception_handler = :default_exception_handler             # this is the default
 279     #   I18n.default_exception_handler(exception, locale, key, options) # will be called like this
 280     #
 281     #   I18n.exception_handler = lambda { |*args| ... }                 # a lambda
 282     #   I18n.exception_handler.call(exception, locale, key, options)    # will be called like this
 283     #
 284     #  I18n.exception_handler = I18nExceptionHandler.new                # an object
 285     #  I18n.exception_handler.call(exception, locale, key, options)     # will be called like this
 286     def handle_exception(handling, exception, locale, key, options)
 287       case handling
 288       when :raise
 289         raise(exception.respond_to?(:to_exception) ? exception.to_exception : exception)
 290       when :throw
 291         throw :exception, exception
 292       else
 293         case handler = options[:exception_handler] || config.exception_handler
 294         when Symbol
 295           send(handler, exception, locale, key, options)
 296         else
 297           handler.call(exception, locale, key, options)
 298         end
 299       end
 300     end
 301
 302     def normalize_key(key, separator)
 303       normalized_key_cache[separator][key] ||=
 304         case key
 305         when Array
 306           key.map { |k| normalize_key(k, separator) }.flatten
 307         else
 308           keys = key.to_s.split(separator)
 309           keys.delete('')
 310           keys.map! { |k| k.to_sym }
 311           keys
 312         end
 313     end
 314
 315     def normalized_key_cache
 316       @normalized_key_cache ||= Hash.new { |h,k| h[k] = {} }
 317     end
 318
 319     # DEPRECATED. Use I18n.normalize_keys instead.
 320     def normalize_translation_keys(locale, key, scope, separator = nil)
 321       puts "I18n.normalize_translation_keys is deprecated. Please use the class I18n.normalize_keys instead."
 322       normalize_keys(locale, key, scope, separator)
 323     end
 324
 325     # DEPRECATED. Please use the I18n::ExceptionHandler class instead.
 326     def default_exception_handler(exception, locale, key, options)
 327       puts "I18n.default_exception_handler is deprecated. Please use the class I18n::ExceptionHandler instead " +
 328            "(an instance of which is set to I18n.exception_handler by default)."
 329       exception.is_a?(MissingTranslation) ? exception.message : raise(exception)
 330     end
 331   }
 332 end