Class: Mobility::Plugins::Fallbacks

Inherits:
Module
  • Object
show all
Defined in:
lib/mobility/plugins/fallbacks.rb

Overview

Falls back to one or more alternative locales in case no value is defined for a given locale.

For fallbacks: true, Mobility will use the value of Configuration#new_fallbacks for the fallbacks instance. This defaults to an instance of I18n::Locale::Fallbacks, but can be configured (see Configuration).

If a hash is passed to the fallbacks option, a new fallbacks instance will be created for the model with the hash defining additional fallbacks. To set a default value for this hash, use set the value of `default_options` in your Mobility configuration (see below).

In addition, fallbacks are disabled in certain situations. To explicitly disable fallbacks when reading and writing, you can pass the fallback: false option to the reader method. This can be useful to determine the actual value of the translated attribute, including a possible nil value.

The other situation where fallbacks are disabled is when the locale is specified explicitly, either by passing a `locale` option to the accessor or by using locale or fallthrough accessors. (See example below.)

You can also pass a locale or array of locales to the fallback option to use that locale or locales that read, e.g. fallback: :fr would fetch the French translation if the value in the current locale was nil, whereas fallback: [:fr, :es] would try French, then Spanish if the value in the current locale was nil.

Examples:

With default fallbacks enabled (falls through to default locale)

class Post
  extend Mobility
  translates :title, fallbacks: true
end

I18n.default_locale = :en
Mobility.locale = :en
post = Post.new(title: "foo")

Mobility.locale = :ja
post.title
#=> "foo"

post.title = "bar"
post.title
#=> "bar"

With additional fallbacks enabled

class Post
  extend Mobility
  translates :title, fallbacks: { :'en-US' => 'de-DE', :pt => 'de-DE' }
end

Mobility.locale = :'de-DE'
post = Post.new(title: "foo")

Mobility.locale = :'en-US'
post.title
#=> "foo"

post.title = "bar"
post.title
#=> "bar"

Passing fallback option when reading value

class Post
  extend Mobility
  translates :title, fallbacks: true
end

I18n.default_locale = :en
Mobility.locale = :en
post = Post.new(title: "Mobility")
Mobility.with_locale(:fr) { post.title = "Mobilité" }

Mobility.locale = :ja
post.title
#=> "Mobility"
post.title(fallback: false)
#=> nil
post.title(fallback: :fr)
#=> "Mobilité"

Fallbacks disabled

class Post
  extend Mobility
  translates :title, fallbacks: { :'fr' => 'en' }, locale_accessors: true
end

I18n.default_locale = :en
Mobility.locale = :en
post = Post.new(title: "Mobility")

Mobility.locale = :fr
post.title
#=> "Mobility"
post.title(fallback: false)
#=> nil
post.title(locale: :fr)
#=> nil
post.title_fr
#=> nil

Setting default fallbacks across all models

Mobility.configure do |config|
  # ...
  config.default_options[:fallbacks] = { :'fr' => 'en' }
  # ...
end

class Post
  # Post will fallback from French to English by default
  translates :title, fallbacks: true
end

See Also:

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(fallbacks_option) ⇒ Fallbacks

Returns a new instance of Fallbacks


134
135
136
# File 'lib/mobility/plugins/fallbacks.rb', line 134

def initialize(fallbacks_option)
  define_read(convert_option_to_fallbacks(fallbacks_option))
end

Class Method Details

.apply(attributes, option) ⇒ Object

Applies fallbacks plugin to attributes. Completely disables fallbacks on model if option is false.

Parameters:


130
131
132
# File 'lib/mobility/plugins/fallbacks.rb', line 130

def self.apply(attributes, option)
  attributes.backend_class.include(new(option)) unless option == false
end