module Mobility::Plugins::Fallbacks
Falls back to one or more alternative locales in case no value is defined for a given locale.
For +fallbacks: true+, Mobility
will use an instance of I18n::Locale::Fallbacks
, but this can be configured by overriding generate_fallbacks
in the translations class.
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, pass this value to the plugin in your Mobility
configuration.
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
.
@see github.com/svenfuchs/i18n/wiki/Fallbacks I18n Fallbacks
@example 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"
@example 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"
@example 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é"
@example 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
Private Instance Methods
# File lib/mobility/plugins/fallbacks.rb, line 126 def generate_fallbacks(fallbacks) fallbacks_class = I18n.respond_to?(:fallbacks) ? I18nFallbacks : I18n::Locale::Fallbacks fallbacks_class.new(fallbacks) end