Module: I18n

Defined in:
lib/active_support/vendor/i18n-0.4.1/i18n/backend/cache.rb,
lib/active_support/vendor.rb,
lib/active_support/vendor/i18n-0.4.1/i18n.rb,
lib/active_support/vendor/i18n-0.4.1/i18n/config.rb,
lib/active_support/vendor/i18n-0.4.1/i18n/locale.rb,
lib/active_support/vendor/i18n-0.4.1/i18n/backend.rb,
lib/active_support/vendor/i18n-0.4.1/i18n/gettext.rb,
lib/active_support/vendor/i18n-0.4.1/i18n/version.rb,
lib/active_support/vendor/i18n-0.4.1/i18n/exceptions.rb,
lib/active_support/vendor/i18n-0.4.1/i18n/locale/tag.rb,
lib/active_support/vendor/i18n-0.4.1/i18n/backend/base.rb,
lib/active_support/vendor/i18n-0.4.1/i18n/backend/cldr.rb,
lib/active_support/vendor/i18n-0.4.1/i18n/backend/chain.rb,
lib/active_support/vendor/i18n-0.4.1/i18n/backend/simple.rb,
lib/active_support/vendor/i18n-0.4.1/i18n/backend/cascade.rb,
lib/active_support/vendor/i18n-0.4.1/i18n/backend/flatten.rb,
lib/active_support/vendor/i18n-0.4.1/i18n/backend/gettext.rb,
lib/active_support/vendor/i18n-0.4.1/i18n/backend/memoize.rb,
lib/active_support/vendor/i18n-0.4.1/i18n/gettext/helpers.rb,
lib/active_support/vendor/i18n-0.4.1/i18n/backend/metadata.rb,
lib/active_support/vendor/i18n-0.4.1/i18n/locale/fallbacks.rb,
lib/active_support/vendor/i18n-0.4.1/i18n/backend/fallbacks.rb,
lib/active_support/vendor/i18n-0.4.1/i18n/backend/key_value.rb,
lib/active_support/vendor/i18n-0.4.1/i18n/locale/tag/simple.rb,
lib/active_support/vendor/i18n-0.4.1/i18n/locale/tag/parents.rb,
lib/active_support/vendor/i18n-0.4.1/i18n/locale/tag/rfc4646.rb,
lib/active_support/vendor/i18n-0.4.1/i18n/backend/active_record.rb,
lib/active_support/vendor/i18n-0.4.1/i18n/backend/pluralization.rb,
lib/active_support/vendor/i18n-0.4.1/i18n/backend/transliterator.rb,
lib/active_support/vendor/i18n-0.4.1/i18n/backend/active_record/missing.rb,
lib/active_support/vendor/i18n-0.4.1/i18n/backend/interpolation_compiler.rb,
lib/active_support/vendor/i18n-0.4.1/i18n/backend/active_record/store_procs.rb,
lib/active_support/vendor/i18n-0.4.1/i18n/backend/active_record/translation.rb

Overview

The InterpolationCompiler module contains optimizations that can tremendously speed up the interpolation process on the Simple backend.

It works by defining a pre-compiled method on stored translation Strings that already bring all the knowledge about contained interpolation variables etc. so that the actual recurring interpolation will be very fast.

To enable pre-compiled interpolations you can simply include the InterpolationCompiler module to the Simple backend:

I18n::Backend::Simple.send(:include, I18n::Backend::InterpolationCompiler)

Note that InterpolationCompiler does not yield meaningful results and consequently should not be used with Ruby 1.9 (YARV) but improves performance everywhere else (jRuby, Rubinius and 1.8.7).

Defined Under Namespace

Modules: Backend, Gettext, Locale Classes: ArgumentError, Config, InvalidLocale, InvalidPluralizationData, MissingInterpolationArgument, MissingTranslationData, ReservedInterpolationKey, UnknownFileType

Constant Summary collapse

VERSION = 
"0.4.1"
@@cache_store = 
nil
@@cache_namespace = 
nil
@@fallbacks = 
nil

Class Method Summary collapse

Class Method Details

.cache_namespace ⇒ Object 



34
35
36
 
# File 'lib/active_support/vendor/i18n-0.4.1/i18n/backend/cache.rb', line 34

def cache_namespace
  @@cache_namespace
end

.cache_namespace=(namespace) ⇒ Object 



38
39
40
 
# File 'lib/active_support/vendor/i18n-0.4.1/i18n/backend/cache.rb', line 38

def cache_namespace=(namespace)
  @@cache_namespace = namespace
end

.cache_store ⇒ Object 



26
27
28
 
# File 'lib/active_support/vendor/i18n-0.4.1/i18n/backend/cache.rb', line 26

def cache_store
  @@cache_store
end

.cache_store=(store) ⇒ Object 



30
31
32
 
# File 'lib/active_support/vendor/i18n-0.4.1/i18n/backend/cache.rb', line 30

def cache_store=(store)
  @@cache_store = store
end

.config ⇒ Object

Gets I18n configuration object.



21
22
23
 
# File 'lib/active_support/vendor/i18n-0.4.1/i18n.rb', line 21

def config
  Thread.current[:i18n_config] ||= I18n::Config.new
end

.config=(value) ⇒ Object

Sets I18n configuration object.



26
27
28
 
# File 'lib/active_support/vendor/i18n-0.4.1/i18n.rb', line 26

def config=(value)
  Thread.current[:i18n_config] = value
end

.fallbacks ⇒ Object

Returns the current fallbacks implementation. Defaults to I18n::Locale::Fallbacks.



17
18
19
 
# File 'lib/active_support/vendor/i18n-0.4.1/i18n/backend/fallbacks.rb', line 17

def fallbacks
  @@fallbacks ||= I18n::Locale::Fallbacks.new
end

.fallbacks=(fallbacks) ⇒ Object

Sets the current fallbacks implementation. Use this to set a different fallbacks implementation.



22
23
24
 
# File 'lib/active_support/vendor/i18n-0.4.1/i18n/backend/fallbacks.rb', line 22

def fallbacks=(fallbacks)
  @@fallbacks = fallbacks
end

.localize(object, options = {}) ⇒ Object Also known as: l

Localizes certain objects, such as dates and numbers to local formatting.



228
229
230
231
232
 
# File 'lib/active_support/vendor/i18n-0.4.1/i18n.rb', line 228

def localize(object, options = {})
  locale = options.delete(:locale) || config.locale
  format = options.delete(:format) || :default
  config.backend.localize(locale, object, format, options)
end

.normalize_keys(locale, key, scope, separator = nil) ⇒ Object

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.



250
251
252
253
254
255
256
257
258
 
# File 'lib/active_support/vendor/i18n-0.4.1/i18n.rb', line 250

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
end

.perform_caching? ⇒ Boolean

Returns:

  • (Boolean) 


42
43
44
 
# File 'lib/active_support/vendor/i18n-0.4.1/i18n/backend/cache.rb', line 42

def perform_caching?
  !cache_store.nil?
end

.reload! ⇒ Object

Tells the backend to reload translations. Used in situations like the Rails development environment. Backends can implement whatever strategy is useful.



47
48
49
 
# File 'lib/active_support/vendor/i18n-0.4.1/i18n.rb', line 47

def reload!
  config.backend.reload!
end

.translate(*args) ⇒ Object Also known as: t

Translates, pluralizes and interpolates a given key using a given locale, scope, and default, as well as interpolation values.

LOOKUP

Translation data is organized as a nested hash using the upper-level keys as namespaces. E.g., ActionView ships with the translation: :date => {:formats => {:short => "%b %d"}}.

Translations can be looked up at any level of this hash using the key argument and the scope option. E.g., in this example I18n.t :date returns the whole translations hash {:formats => {:short => "%b %d"}}.

Key can be either a single key or a dot-separated key (both Strings and Symbols work). E.g., the short format can be looked up using both:

I18n.t 'date.formats.short'
I18n.t :'date.formats.short'

Scope can be either a single key, a dot-separated key or an array of keys or dot-separated keys. Keys and scopes can be combined freely. So these examples will all look up the same short date format:

I18n.t 'date.formats.short'
I18n.t 'formats.short', :scope => 'date'
I18n.t 'short', :scope => 'date.formats'
I18n.t 'short', :scope => %w(date formats)

INTERPOLATION

Translations can contain interpolation variables which will be replaced by values passed to #translate as part of the options hash, with the keys matching the interpolation variable names.

E.g., with a translation :foo => "foo %{bar}" the option value for the key bar will be interpolated into the translation:

I18n.t :foo, :bar => 'baz' # => 'foo baz'

PLURALIZATION

Translation data can contain pluralized translations. Pluralized translations are arrays of singluar/plural versions of translations like ['Foo', 'Foos'].

Note that I18n::Backend::Simple only supports an algorithm for English pluralization rules. Other algorithms can be supported by custom backends.

This returns the singular version of a pluralized translation:

I18n.t :foo, :count => 1 # => 'Foo'

These both return the plural version of a pluralized translation:

I18n.t :foo, :count => 0 # => 'Foos'
I18n.t :foo, :count => 2 # => 'Foos'

The :count option can be used both for pluralization and interpolation. E.g., with the translation :foo => ['%{count} foo', '%{count} foos'], count will be interpolated to the pluralized translation:

I18n.t :foo, :count => 1 # => '1 foo'

DEFAULTS

This returns the translation for :foo or default if no translation was found:

I18n.t :foo, :default => 'default'

This returns the translation for :foo or the translation for :bar if no translation for :foo was found:

I18n.t :foo, :default => :bar

Returns the translation for :foo or the translation for :bar or default if no translations for :foo and :bar were found.

I18n.t :foo, :default => [:bar, 'default']

*BULK LOOKUP*

This returns an array with the translations for :foo and :bar.

I18n.t [:foo, :bar]

Can be used with dot-separated nested keys:

I18n.t [:'baz.foo', :'baz.bar']

Which is the same as using a scope option:

I18n.t [:foo, :bar], :scope => :baz

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 :salutation 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.



147
148
149
150
151
152
153
154
155
156
 
# File 'lib/active_support/vendor/i18n-0.4.1/i18n.rb', line 147

def translate(*args)
  options = args.pop if args.last.is_a?(Hash)
  key     = args.shift
  locale  = options && options.delete(:locale) || config.locale
  raises  = options && options.delete(:raise)
  config.backend.translate(locale, key, options || {})
rescue I18n::ArgumentError => exception
  raise exception if raises
  handle_exception(exception, locale, key, options)
end

.translate!(key, options = {}) ⇒ Object Also known as: t! 



159
160
161
 
# File 'lib/active_support/vendor/i18n-0.4.1/i18n.rb', line 159

def translate!(key, options = {})
  translate(key, options.merge( :raise => true ))
end

.transliterate(*args) ⇒ Object

Transliterates UTF-8 characters to ASCII. By default this method will transliterate only Latin strings to an ASCII approximation:

I18n.transliterate("Ærøskøbing")
# => "AEroskobing"

I18n.transliterate("日本語")
# => "???"

It’s also possible to add support for per-locale transliterations. I18n expects transliteration rules to be stored at i18n.transliterate.rule.

Transliteration rules can either be a Hash or a Proc. Procs must accept a single string argument. Hash rules inherit the default transliteration rules, while Procs do not.

Examples

Setting a Hash in <locale>.yml:

i18n:
  transliterate:
    rule:
      ü: "ue"
      ö: "oe"

Setting a Hash using Ruby:

store_translations(:de, :i18n => {
  :transliterate => {
    :rule => {
      "ü" => "ue",
      "ö" => "oe"
    }
  }
)

Setting a Proc:

translit = lambda {|string| MyTransliterator.transliterate(string) }
store_translations(:xx, :i18n => {:transliterate => {:rule => translit})

Transliterating strings:

I18n.locale = :en
I18n.transliterate("Jürgen") # => "Jurgen"
I18n.locale = :de
I18n.transliterate("Jürgen") # => "Juergen"
I18n.transliterate("Jürgen", :locale => :en) # => "Jurgen"
I18n.transliterate("Jürgen", :locale => :de) # => "Juergen"



215
216
217
218
219
220
221
222
223
224
225
 
# File 'lib/active_support/vendor/i18n-0.4.1/i18n.rb', line 215

def transliterate(*args)
  options      = args.pop if args.last.is_a?(Hash)
  key          = args.shift
  locale       = options && options.delete(:locale) || config.locale
  raises       = options && options.delete(:raise)
  replacement  = options && options.delete(:replacement)
  config.backend.transliterate(locale, key, replacement)
rescue I18n::ArgumentError => exception
  raise exception if raises
  handle_exception(exception, locale, key, options)
end

.with_locale(tmp_locale = nil) ⇒ Object

Executes block with given I18n.locale set.



236
237
238
239
240
241
242
243
244
 
# File 'lib/active_support/vendor/i18n-0.4.1/i18n.rb', line 236

def with_locale(tmp_locale = nil)
  if tmp_locale
    current_locale = self.locale
    self.locale    = tmp_locale
  end
  yield
ensure
  self.locale = current_locale if tmp_locale
end