Module: I18n

Defined in:
lib/vendor/i18n/lib/i18n/backend/cache.rb,
lib/vendor/i18n/lib/i18n.rb,
lib/polish/backend/advanced.rb,
lib/vendor/i18n/lib/i18n/gettext.rb,
lib/vendor/i18n/lib/i18n/exceptions.rb,
lib/vendor/i18n/lib/i18n/locale/tag.rb,
lib/vendor/i18n/lib/i18n/backend/base.rb,
lib/vendor/i18n/lib/i18n/backend/chain.rb,
lib/vendor/i18n/lib/i18n/backend/simple.rb,
lib/vendor/i18n/lib/i18n/backend/gettext.rb,
lib/vendor/i18n/lib/i18n/helpers/gettext.rb,
lib/vendor/i18n/lib/i18n/locale/fallbacks.rb,
lib/vendor/i18n/lib/i18n/backend/fallbacks.rb,
lib/vendor/i18n/lib/i18n/locale/tag/simple.rb,
lib/vendor/i18n/lib/i18n/locale/tag/parents.rb,
lib/vendor/i18n/lib/i18n/locale/tag/rfc4646.rb,
lib/vendor/i18n/lib/i18n/backend/pluralization.rb

Overview

I18n locale fallbacks are useful when you want your application to use translations from other locales when translations for the current locale are missing. E.g. you might want to use :en translations when translations in your applications main locale :de are missing.

To enable locale specific pluralizations you can simply include the Pluralization module to the Simple backend - or whatever other backend you are using.

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

You also need to make sure to provide pluralization algorithms to the backend, i.e. include them to your I18n.load_path accordingly.

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.



55
56
57
 
# File 'lib/vendor/i18n/lib/i18n.rb', line 55

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

.available_locales=(locales) ⇒ Object

Sets the available locales.



60
61
62
 
# File 'lib/vendor/i18n/lib/i18n.rb', line 60

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

.backend ⇒ Object

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



23
24
25
 
# File 'lib/vendor/i18n/lib/i18n.rb', line 23

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

.backend=(backend) ⇒ Object

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



28
29
30
 
# File 'lib/vendor/i18n/lib/i18n.rb', line 28

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

.cache_namespace ⇒ Object 



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

def cache_namespace
  @@cache_namespace
end

.cache_namespace=(namespace) ⇒ Object 



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

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

.cache_store ⇒ Object 



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

def cache_store
  @@cache_store
end

.cache_store=(store) ⇒ Object 



30
31
32
 
# File 'lib/vendor/i18n/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’



33
34
35
 
# File 'lib/vendor/i18n/lib/i18n.rb', line 33

def default_locale
  @@default_locale
end

.default_locale=(locale) ⇒ Object

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



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

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

.default_separator ⇒ Object

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



65
66
67
 
# File 'lib/vendor/i18n/lib/i18n.rb', line 65

def default_separator
  @@default_separator
end

.default_separator=(separator) ⇒ Object

Sets the current default scope separator.



70
71
72
 
# File 'lib/vendor/i18n/lib/i18n.rb', line 70

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

.exception_handler=(exception_handler) ⇒ Object

Sets the exception handler.



75
76
77
 
# File 'lib/vendor/i18n/lib/i18n.rb', line 75

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/vendor/i18n/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/vendor/i18n/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'



87
88
89
 
# File 'lib/vendor/i18n/lib/i18n.rb', line 87

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.



93
94
95
 
# File 'lib/vendor/i18n/lib/i18n.rb', line 93

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

.locale ⇒ Object

Returns the current locale. Defaults to I18n.default_locale.



43
44
45
 
# File 'lib/vendor/i18n/lib/i18n.rb', line 43

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

.locale=(locale) ⇒ Object

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



48
49
50
 
# File 'lib/vendor/i18n/lib/i18n.rb', line 48

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.



217
218
219
220
221
 
# File 'lib/vendor/i18n/lib/i18n.rb', line 217

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/vendor/i18n/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.



100
101
102
 
# File 'lib/vendor/i18n/lib/i18n.rb', line 100

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.



200
201
202
203
204
205
206
207
208
 
# File 'lib/vendor/i18n/lib/i18n.rb', line 200

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! 



211
212
213
 
# File 'lib/vendor/i18n/lib/i18n.rb', line 211

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