Module: I18n

Defined in:
lib/i18n/backend/cache.rb,
lib/i18n.rb,
lib/i18n/gettext.rb,
lib/i18n/exceptions.rb,
lib/i18n/locale/tag.rb,
lib/i18n/backend/base.rb,
lib/i18n/backend/fast.rb,
lib/i18n/backend/chain.rb,
lib/i18n/backend/simple.rb,
lib/i18n/backend/gettext.rb,
lib/i18n/helpers/gettext.rb,
lib/i18n/locale/fallbacks.rb,
lib/i18n/backend/fallbacks.rb,
lib/i18n/locale/tag/simple.rb,
lib/i18n/locale/tag/parents.rb,
lib/i18n/locale/tag/rfc4646.rb,
lib/i18n/backend/pluralization.rb,
lib/i18n/backend/lazy_reloading.rb,
lib/i18n/backend/fast/interpolation_compiler.rb

Overview

Speeds up the reload! method (usefull in development mode) by first making sure the locale files have actually changed (this is done using their last mtime). Usage:

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

Defined Under Namespace

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

Constant Summary collapse

@@backend = 
nil
@@load_path = 
nil
@@default_locale = 
:en
@@default_separator = 
'.'
@@exception_handler = 
:default_exception_handler
@@cache_store = 
nil
@@cache_namespace = 
nil
@@fallbacks = 
nil

Class Method Summary collapse

Class Method Details

.available_locales ⇒ Object

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.



57
58
59
 
# File 'lib/i18n.rb', line 57

def available_locales
  @@available_locales ||= backend.available_locales
end

.available_locales=(locales) ⇒ Object

Sets the available locales.



62
63
64
 
# File 'lib/i18n.rb', line 62

def available_locales=(locales)
  @@available_locales = locales
end

.backend ⇒ Object

Returns the current backend. Defaults to Backend::Simple.



25
26
27
 
# File 'lib/i18n.rb', line 25

def backend
  @@backend ||= Backend::Simple.new
end

.backend=(backend) ⇒ Object

Sets the current backend. Used to set a custom backend.



30
31
32
 
# File 'lib/i18n.rb', line 30

def backend=(backend)
  @@backend = backend
end

.cache_namespace ⇒ Object 



34
35
36
 
# File 'lib/i18n/backend/cache.rb', line 34

def cache_namespace
  @@cache_namespace
end

.cache_namespace=(namespace) ⇒ Object 



38
39
40
 
# File 'lib/i18n/backend/cache.rb', line 38

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

.cache_store ⇒ Object 



26
27
28
 
# File 'lib/i18n/backend/cache.rb', line 26

def cache_store
  @@cache_store
end

.cache_store=(store) ⇒ Object 



30
31
32
 
# File 'lib/i18n/backend/cache.rb', line 30

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

.default_locale ⇒ Object

Returns the current default locale. Defaults to :‘en’



35
36
37
 
# File 'lib/i18n.rb', line 35

def default_locale
  @@default_locale
end

.default_locale=(locale) ⇒ Object

Sets the current default locale. Used to set a custom default locale.



40
41
42
 
# File 'lib/i18n.rb', line 40

def default_locale=(locale)
  @@default_locale = locale.to_sym rescue nil
end

.default_separator ⇒ Object

Returns the current default scope separator. Defaults to ‘.’



67
68
69
 
# File 'lib/i18n.rb', line 67

def default_separator
  @@default_separator
end

.default_separator=(separator) ⇒ Object

Sets the current default scope separator.



72
73
74
 
# File 'lib/i18n.rb', line 72

def default_separator=(separator)
  @@default_separator = separator
end

.exception_handler=(exception_handler) ⇒ Object

Sets the exception handler.



77
78
79
 
# File 'lib/i18n.rb', line 77

def exception_handler=(exception_handler)
  @@exception_handler = exception_handler
end

.fallbacks ⇒ Object

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



19
20
21
 
# File 'lib/i18n/backend/fallbacks.rb', line 19

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

.fallbacks=(fallbacks) ⇒ Object

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



24
25
26
 
# File 'lib/i18n/backend/fallbacks.rb', line 24

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

.load_path ⇒ Object

Allow clients to register paths providing translation data sources. The backend defines acceptable sources.

E.g. the provided SimpleBackend accepts a list of paths to translation files which are either named *.rb and contain plain Ruby Hashes or are named *.yml and contain YAML data. So for the SimpleBackend clients may register translation files like this:

I18n.load_path << 'path/to/locale/en.yml'



89
90
91
 
# File 'lib/i18n.rb', line 89

def load_path
  @@load_path ||= []
end

.load_path=(load_path) ⇒ Object

Sets the load path instance. Custom implementations are expected to behave like a Ruby Array.



95
96
97
 
# File 'lib/i18n.rb', line 95

def load_path=(load_path)
  @@load_path = load_path
end

.locale ⇒ Object

Returns the current locale. Defaults to I18n.default_locale.



45
46
47
 
# File 'lib/i18n.rb', line 45

def locale
  Thread.current[:locale] ||= default_locale
end

.locale=(locale) ⇒ Object

Sets the current locale pseudo-globally, i.e. in the Thread.current hash.



50
51
52
 
# File 'lib/i18n.rb', line 50

def locale=(locale)
  Thread.current[:locale] = locale.to_sym rescue nil
end

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

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



219
220
221
222
223
 
# File 'lib/i18n.rb', line 219

def localize(object, options = {})
  locale = options[:locale] || I18n.locale
  format = options[:format] || :default
  backend.localize(locale, object, format)
end

.perform_caching? ⇒ Boolean

Returns:

  • (Boolean) 


42
43
44
 
# File 'lib/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.



102
103
104
 
# File 'lib/i18n.rb', line 102

def reload!
  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.



202
203
204
205
206
207
208
209
210
 
# File 'lib/i18n.rb', line 202

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 => exception
  raise exception if options[:raise]
  handle_exception(exception, locale, key, options)
end

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



213
214
215
 
# File 'lib/i18n.rb', line 213

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