Disable fallbacks when using locale/fallthrough accessors

README.md

@@ -222,7 +222,7 @@ locations, usually database columns. By default these values are stored as keys
 tables, one for strings and one for text columns, but this can be easily
 changed and/or customized (see the [Backends](#backends) section below).
 
-### Getting and Setting Translations
+### <a name="getset"></a> Getting and Setting Translations
 
 The easiest way to get or set a translation is to use the getter and setter
 methods described above (`word.name` and `word.name=`), but you may want to
@@ -309,6 +309,11 @@ word.name(locale: :fr)
 #=> "mobilité"
 ```
 
+Note that setting the locale this way will pass an option `locale: true` to the
+backend and all plugins. Plugins may use this option to change their behavior
+(passing the locale explicitly this way, for example, disables
+[fallbacks](#fallbacks), see below for details).
+
 You can also *set* the value of an attribute this way; however, since the
 `word.name = <value>` syntax does not accept any options, the only way to do this is to
 use `send` (this is included mostly for consistency):
@@ -387,8 +392,8 @@ translated attributes on a class:
 ```ruby
 class Word < ApplicationRecord
   extend Mobility
-  translates :name,    type: :string, fallbacks: { de: :ja, fr: :ja }
-  translates :meaning, type: :text,   fallbacks: { de: :ja, fr: :ja }
+  translates :name,    type: :string, fallbacks: { de: :ja, fr: :ja }, locale_accessors: true
+  translates :meaning, type: :text,   fallbacks: { de: :ja, fr: :ja }, locale_accessors: true
 end
 ```
 
@@ -404,17 +409,20 @@ but not for other locales:
 ```ruby
 Mobility.locale = :ja
 word = Word.create(name: "モビリティ", meaning: "(名詞):動きやすさ、可動性")
-word.name(locale: :de)
+Mobility.locale = :de
+word.name
 #=> "モビリティ"
-word.meaning(locale: :de)
+word.meaning
 #=> "(名詞):動きやすさ、可動性"
-word.name(locale: :fr)
+Mobility.locale = :fr
+word.name
 #=> "モビリティ"
-word.meaning(locale: :fr)
+word.meaning
 #=> "(名詞):動きやすさ、可動性"
-word.name(locale: :ru)
+Mobility.locale = :ru
+word.name
 #=> nil
-word.meaning(locale: :ru)
+word.meaning
 #=> nil
 ```
 
@@ -423,11 +431,14 @@ You can optionally disable fallbacks to get the real value for a given locale
 passing `fallback: false` (*singular*, not plural) to the getter method:
 
 ```ruby
-word.meaning(locale: :de, fallback: false)
+Mobility.locale = :de
+word.meaning(fallback: false)
 #=> nil
-word.meaning(locale: :fr, fallback: false)
+Mobility.locale = :fr
+word.meaning(fallback: false)
 #=> nil
-word.meaning(locale: :ja, fallback: false)
+Mobility.locale = :ja
+word.meaning(fallback: false)
 #=> "(名詞):動きやすさ、可動性"
 ```
 
@@ -439,11 +450,28 @@ Mobility.with_locale(:fr) do
   word.meaning = "(nf): aptitude à bouger, à se déplacer, à changer, à évoluer"
 end
 word.save
-word.meaning(locale: :de, fallback: false)
+Mobility.locale = :de
+word.meaning(fallback: false)
 #=> nil
-word.meaning(locale: :de, fallback: :fr)
+word.meaning(fallback: :fr)
 #=> "(nf): aptitude à bouger, à se déplacer, à changer, à évoluer"
-word.meaning(locale: :de, fallback: [:ja, :fr])
+word.meaning(fallback: [:ja, :fr])
+#=> "(名詞):動きやすさ、可動性"
+```
+
+Also note that passing a `locale` option into an attribute reader or writer, or
+using [locale accessors or fallthrough accessors](#getset) to get or set
+any attribute value, will disable fallbacks (just like `fallback: false`).
+(This will take precedence over any value of the `fallback` option.)
+
+Continuing from the last example:
+
+```ruby
+word.meaning(locale: :de)
+#=> nil
+word.meaning_de
+#=> nil
+Mobility.with_locale(:de) { word.meaning }
 #=> "(名詞):動きやすさ、可動性"
 ```
 

lib/mobility/attributes.rb

@@ -19,7 +19,7 @@ module Mobility
 
   Attributes.new("title", backend: :my_backend, locale_accessors: [:en, :ja], cache: true, fallbacks: true)
 
-will generate an anonymous module that behaves like this:
+will generate an anonymous module that behaves (approximately) like this:
 
   Module.new do
     def title_backend
@@ -168,6 +168,17 @@ def each &block
       names.each(&block)
     end
 
+    # Process options passed into accessor method before calling backend, and
+    # return locale
+    # @param [Hash] options Options hash passed to accessor method
+    # @return [Symbol] locale
+    def self.process_options!(options)
+      (options[:locale] || Mobility.locale).tap { |locale|
+        Mobility.enforce_available_locales!(locale)
+        options[:locale] &&= !!locale
+      }.to_sym
+    end
+
     private
 
     def define_backend(attribute)
@@ -179,24 +190,24 @@ def define_backend(attribute)
     end
 
     def define_reader(attribute)
-      define_method attribute do |locale: Mobility.locale, **options|
+      define_method attribute do |**options|
         return super() if options.delete(:super)
-        Mobility.enforce_available_locales!(locale)
-        mobility_backend_for(attribute).read(locale.to_sym, options)
+        locale = Mobility::Attributes.process_options!(options)
+        mobility_backend_for(attribute).read(locale, options)
       end
 
-      define_method "#{attribute}?" do |locale: Mobility.locale, **options|
+      define_method "#{attribute}?" do |**options|
         return super() if options.delete(:super)
-        Mobility.enforce_available_locales!(locale)
-        mobility_backend_for(attribute).present?(locale.to_sym, options)
+        locale = Mobility::Attributes.process_options!(options)
+        mobility_backend_for(attribute).present?(locale, options)
       end
     end
 
     def define_writer(attribute)
-      define_method "#{attribute}=" do |value, locale: Mobility.locale, **options|
+      define_method "#{attribute}=" do |value, **options|
         return super(value) if options.delete(:super)
-        Mobility.enforce_available_locales!(locale)
-        mobility_backend_for(attribute).write(locale.to_sym, value, options)
+        locale = Mobility::Attributes.process_options!(options)
+        mobility_backend_for(attribute).write(locale, value, options)
       end
     end
 

lib/mobility/plugins/dirty.rb

@@ -14,11 +14,7 @@ module Plugins
 @note Dirty tracking can have unexpected results when combined with fallbacks.
   A change in the fallback locale value will not mark an attribute falling
   through to that locale as changed, even though it may look like it has
-  changed. However, when the value for the current locale is changed from nil
-  or blank to a new value, the change will be recorded as a change from that
-  fallback value, rather than from the nil or blank value. The specs are the
-  most reliable source of information on the interaction between dirty tracking
-  and fallbacks.
+  changed. See the specs for details on expected behavior.
 
 =end
     module Dirty

lib/mobility/plugins/fallbacks.rb

@@ -15,14 +15,20 @@ module Plugins
 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. 
 
-In addition, fallbacks can be disabled when reading by passing <tt>fallback:
-false</tt> to the reader method. This can be useful to determine the actual
-value of the translated attribute, including a possible +nil+ value. You can
-also pass a locale or array of locales to the +fallback+ option to use that
-locale or locales that read, e.g. <tt>fallback: :fr</tt> would fetch the French
-translation if the value in the current locale was +nil+, whereas <tt>fallback:
-[:fr, :es]</tt> would try French, then Spanish if the value in the current
-locale was +nil+.
+In addition, fallbacks are disabled in certain situation. To explicitly disable
+fallbacks when reading and writing, you can pass the <tt>fallback: false</tt>
+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. <tt>fallback: :fr</tt> would fetch the
+French translation if the value in the current locale was +nil+, whereas
+<tt>fallback: [:fr, :es]</tt> would try French, then Spanish if the value in
+the current locale was +nil+.
 
 @see https://github.com/svenfuchs/i18n/wiki/Fallbacks I18n Fallbacks
 
@@ -76,6 +82,26 @@ class Post
   #=> nil
   post.title(fallback: :fr)
   #=> "Mobilité"
+
+@example Fallbacks disabled
+  class Post
+    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
+
 =end
     class Fallbacks < Module
       # Applies fallbacks plugin to attributes.
@@ -93,14 +119,15 @@ def initialize(fallbacks_option)
 
       def define_read(fallbacks)
         define_method :read do |locale, fallback: true, **options|
-          return super(locale, options) if !fallback
-          return super(locale, options) if fallbacks.nil? && fallback == true
+          return super(locale, options) if !fallback || options[:locale]
 
           locales = fallback == true ? fallbacks[locale] : [locale, *fallback]
-          locales.detect do |fallback_locale|
+          locales.each do |fallback_locale|
             value = super(fallback_locale, options)
-            break value if Util.present?(value)
+            return value if Util.present?(value)
           end
+
+          super(locale, options)
         end
       end
 
@@ -110,7 +137,7 @@ def convert_option_to_fallbacks(option)
         elsif option == true
           Mobility.default_fallbacks
         else
-          nil
+          Hash.new { [] }
         end
       end
     end

lib/mobility/plugins/fallthrough_accessors.rb

@@ -46,12 +46,12 @@ def self.apply(attributes, option)
       def initialize(*attributes)
         method_name_regex = /\A(#{attributes.join('|'.freeze)})_([a-z]{2}(_[a-z]{2})?)(=?|\??)\z/.freeze
 
-        define_method :method_missing do |method_name, *arguments, &block|
+        define_method :method_missing do |method_name, *arguments, **options, &block|
           if method_name =~ method_name_regex
             attribute = $1.to_sym
             locale, suffix = $2.split('_'.freeze)
             locale = "#{locale}-#{suffix.upcase}".freeze if suffix
-            Mobility.with_locale(locale) { public_send("#{attribute}#{$4}".freeze, *arguments) }
+            public_send("#{attribute}#{$4}".freeze, *arguments, **options, locale: locale.to_sym)
           else
             super(method_name, *arguments, &block)
           end

lib/mobility/plugins/locale_accessors.rb

@@ -58,14 +58,14 @@ def define_reader(name, locale)
 
         define_method "#{name}_#{normalized_locale}" do |**options|
           return super() if options.delete(:super)
-          warn warning_message if options.delete(:locale)
-          Mobility.with_locale(locale) { send(name, options) }
+          warn warning_message if options[:locale]
+          send(name, **options, locale: locale)
         end
 
         define_method "#{name}_#{normalized_locale}?" do |**options|
           return super() if options.delete(:super)
-          warn warning_message if options.delete(:locale)
-          Mobility.with_locale(locale) { send("#{name}?", options) }
+          warn warning_message if options[:locale]
+          send("#{name}?", **options, locale: locale)
         end
       end
 
@@ -75,8 +75,8 @@ def define_writer(name, locale)
 
         define_method "#{name}_#{normalized_locale}=" do |value, **options|
           return super(value) if options.delete(:super)
-          warn warning_message if options.delete(:locale)
-          Mobility.with_locale(locale) { send("#{name}=", value, options) }
+          warn warning_message if options[:locale]
+          send("#{name}=", value, **options, locale: locale)
         end
       end
     end

spec/mobility/active_record_compatibility_spec.rb

@@ -77,7 +77,7 @@
   describe "fallbacks" do
     let!(:post) { FallbackPost.create(title: "foo title") }
 
-    it "falls through to default locale" do
+    it "falls through to default locale with no options" do
       Mobility.locale = :ja
       expect(post.title).to eq("foo title")
     end
@@ -86,5 +86,15 @@
       Mobility.locale = :ja
       expect(post.title(fallback: false)).to eq(nil)
     end
+
+    it "does not fall through to default locale when locale is set explicitly" do
+      Mobility.locale = :en
+      expect(post.title(locale: :ja)).to eq(nil)
+    end
+
+    it "does not fall through to default locale when locale accessor is used" do
+      Mobility.locale = :en
+      expect(post.title_ja).to eq(nil)
+    end
   end
 end

spec/mobility/attributes_spec.rb

@@ -132,8 +132,8 @@
           expect(article.title?).to eq(true)
         end
 
-        it "correctly maps locale through getter options" do
-          expect(backend).to receive(:read).with(:fr, {}).and_return("foo")
+        it "correctly maps locale through getter options and converts to boolean" do
+          expect(backend).to receive(:read).with(:fr, locale: true).and_return("foo")
           expect(article.title(locale: "fr")).to eq("foo")
         end
 

spec/mobility/plugins/active_model/dirty_spec.rb

@@ -284,7 +284,7 @@ def save
         expect(article.title).to eq("Title")
         expect(article.changed?).to eq(true)
         expect(article.changed).to match_array(["title_ja", "title_en"])
-        expect(article.changes).to eq({ "title_ja" => [nil, "ばばば"], "title_en" => ["ばばば", "Title"]})
+        expect(article.changes).to eq({ "title_ja" => [nil, "ばばば"], "title_en" => [nil, "Title"]})
       end
     end
   end

spec/mobility/plugins/fallthrough_accessors_spec.rb

@@ -16,10 +16,6 @@ def title=(_value, **_); end
     it_behaves_like "locale accessor", :title, :en
     it_behaves_like "locale accessor", :title, :de
     it_behaves_like "locale accessor", :title, :'pt-BR'
-
-    it "raises InvalidLocale if locale is not in I18n.available_locales" do
-      expect { model_class.new.title_ru }.to raise_error(Mobility::InvalidLocale)
-    end
   end
 
   describe ".apply" do

spec/mobility/plugins/locale_accessors_spec.rb

@@ -40,11 +40,11 @@ def title=(_value, **_); end
         model_class.include(described_class.new(:title))
         instance = model_class.new
         warning_message = /locale passed as option to locale accessor will be ignored/
-        expect(instance).to receive(:title).and_return("foo")
+        expect(instance).to receive(:title).with(locale: :pt).and_return("foo")
         expect { expect(instance.title_pt(locale: :en)).to eq("foo") }.to output(warning_message).to_stderr
-        expect(instance).to receive(:title?).and_return(true)
+        expect(instance).to receive(:title?).with(locale: :pt).and_return(true)
         expect { expect(instance.title_pt?(locale: :en)).to eq(true) }.to output(warning_message).to_stderr
-        expect(instance).to receive(:title=).with("new foo", {})
+        expect(instance).to receive(:title=).with("new foo", locale: :pt)
         expect { instance.send(:title_pt=, "new foo", locale: :en)}.to output(warning_message).to_stderr
       end
     end

spec/mobility/plugins/sequel/dirty_spec.rb

@@ -201,9 +201,9 @@ def values
         article.title = "Title"
         expect(article.title).to eq("Title")
         expect(article.column_changed?(:title)).to eq(true)
-        expect(article.column_change(:title)).to eq(["ばばば", "Title"])
+        expect(article.column_change(:title)).to eq([nil, "Title"])
         expect(article.changed_columns).to match_array([:title_ja, :title_en])
-        expect(article.column_changes).to eq({ title_ja: [nil, "ばばば"], title_en: ["ばばば", "Title"]})
+        expect(article.column_changes).to eq({ title_ja: [nil, "ばばば"], title_en: [nil, "Title"]})
       end
     end
   end