mobility 0.8.13 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bd73c4e94757a4138786f7ebfeb2ac7bbdbcb219030af3319043232b696d70c2
-  data.tar.gz: c05a86a128d80fb859b531c25745474a561f92bf1c610a6d41250c4995f8b0a0
+  metadata.gz: d927c413815d0bd56b1f75e5b0a352d2f5832415c4e1f8c50a98fde44d973e92
+  data.tar.gz: 72d484c61b6b17b9d99e1061444d209ce66a4de70f904d68d1ce612b24656ae0
 SHA512:
-  metadata.gz: cfcddf59bc7a203fd00508bbcb32c8e59658eded31cbf637fb5fe9e9ccfd4cde3b59f762113b1f32c1427d5e2fecfa67e9c91d6c9d8b58c05928cf90356370be
-  data.tar.gz: 887fbb7bb02fa80fc421b45f8f434972c4d163e11e0d6d5dc2618f94e7f86307feb2fc4801c988fd86d19735edb863519b60addacaebebb49d2cb27490af0210
+  metadata.gz: 1167adec126a34ff482d01beaa38e18e4188a79aa1be9e5031f8786d86629724984f7597c29d947ae11ad77d72c7538ecc84ed7474c70c87a3da226e81b1f59c
+  data.tar.gz: d64f21cab45ffa292e9980962d38c7f76fcaacdcac48b7d83b25fbcc0856b49b6814cefdc78e39382d7c12b944ef27ebedb23c14bffb6f819c972e8c9176cb43

checksums.yaml.gz.sig

@@ -1,2 +1,2 @@
->0��R(������p��*�χ-�s����d��������\ذ~m(���@�@U^����*��Z���k�r+4A"�R���6'��D�If��7ɣ��ta\�.���cۆ��i3Ê�Yxh��S	U�s$y���dޣ��l���hH�f>͐�9.������h���F(|��A7��z�1���5~;c��dWw�J �K΃�ηp#�?)Eo�ʉ�"Y��`x����:��q7.G	�b�c8*ꊢ�c����g�b$��q����sx���p
-
�MPm#��[a*���&������ë�aC]=X1J�Q!�S1ףev��v�7�p	���wn
\�*�ל��$�k�
+Z���y�yWy��=���T�R?��6�Jl����-��a���q
��te����������&�r��Ş�I�8��KJ���@FS�I�CĔm�z��1y�/�qDIe�~:�!�/��_�8�
+Σ��U�π�Y��>�)��)�"0�_k�L���N6~#���o��P��^��5К%��\ M9�$�/)t����uԋ�^�t�ʎ@

data/CHANGELOG.md

@@ -1,5 +1,68 @@
 # Mobility Changelog
 
+## 1.0
+
+1.0 is a rewrite of many internals of the gem. Please see the [wiki page on v1.0](https://github.com/shioyama/mobility/wiki/Introduction-to-Mobility-v1.0) for more details on how to upgrade.
+
+## 1.0.0
+
+- Fix setting a locale from Rails config
+	([#468](https://github.com/shioyama/mobility/pull/468)) thanks
+	[sergey-alekseev](https://github.com/sergey-alekseev)!
+- Fixes validations with validates_uniqueness_of
+  ([#470](https://github.com/shioyama/mobility/pull/470)) thanks
+  [artplan1](https://github.com/shioyama/mobility/pull/470)!
+
+## 1.0.0.rc1 (pre-release)
+
+- Remove `Mobility::ActiveRecord`, `Mobility::Sequel` and `Mobility::Arel`, and
+  general cleanup ([#464](https://github.com/shioyama/mobility/pull/464))
+
+## 1.0.0.beta2 (pre-release)
+
+- Refactor attributes & backend plugins and make `mobility_attributes` public
+  ([#462](https://github.com/shioyama/mobility/pull/462))
+- Make attribute_methods plugin depend on attributes
+  ([#461](https://github.com/shioyama/mobility/pull/461))
+
+## 1.0.0.beta1 (pre-release)
+
+- Remove `Mobility::Backend#apply_plugin`
+  ([#454](https://github.com/shioyama/mobility/pull/454))
+- Instance exec configure block if it takes no arguments
+  ([#456](https://github.com/shioyama/mobility/pull/456))
+- Raise an exception if invalid options are passed to Translations initializer
+  ([#457](https://github.com/shioyama/mobility/pull/457/files))
+- Fix Ruby 2.7 deprecation warnings
+  ([#460](https://github.com/shioyama/mobility/pull/460))
+
+## 1.0.0.alpha (pre-release)
+
+- Default fallbacks plugin to `true` when enabled
+  ([#447](https://github.com/shioyama/mobility/pull/447))
+- Remove `Mobility::Backend.method_name`
+  ([#400](https://github.com/shioyama/mobility/pull/400))
+- Remove `translated_attribute_names` as alias for `mobility_attributes`
+  ([#402](https://github.com/shioyama/mobility/pull/402))
+- Move `_backend` methods into `backend_reader` plugin
+  ([#403](https://github.com/shioyama/mobility/pull/403))
+- Replace `Configuration#query_method` configuration with Query plugin option
+  ([#414](https://github.com/shioyama/mobility/pull/414))
+- Remove `Mobility::Configuration#default_accessor_locales`. Use plugin option
+  to configure global default instead.
+  ([#424](https://github.com/shioyama/mobility/pull/424))
+- Pass `model_class` to `Mobility::Backend#configure` via class method rather
+  than on options hash ([#429](https://github.com/shioyama/mobility/pull/429))
+- Remove `Mobility.new_fallbacks` and `Configuration#fallbacks_generator`
+  ([#433](https://github.com/shioyama/mobility/pull/433))
+- Rename `backend_name` to `backend`
+  ([#443](https://github.com/shioyama/mobility/pull/443))
+- Remove `Configuration#accessor_method`
+  ([#450](https://github.com/shioyama/mobility/pull/450))
+- Rename `Mobility::Attributes` to `Mobility::Translations`
+- Remove `Mobility::Configuration` altogether
+  ([#452](https://github.com/shioyama/mobility/pull/452))
+
 ## 0.8
 
 ### 0.8.13 (May 27, 2020)

data/Gemfile

@@ -29,8 +29,6 @@ group :development, :test do
     else
       raise ArgumentError, 'Invalid ActiveRecord version'
     end
-
-    gem "generator_spec", '~> 0.9.4'
   when 'sequel'
     orm_version ||= '5'
     case orm_version
@@ -48,6 +46,11 @@ group :development, :test do
 
   gem 'allocation_stats' if ENV['FEATURE'] == 'performance'
 
+  if ENV['FEATURE'] == 'rails'
+    gem 'rails'
+    gem 'generator_spec', '~> 0.9.4'
+  end
+
   platforms :ruby do
     gem 'guard-rspec'
     gem 'pry-byebug'

data/Gemfile.lock

@@ -1,20 +1,31 @@
 PATH
   remote: .
   specs:
-    mobility (1.0.alpha.1)
+    mobility (1.0.0.rc1)
       i18n (>= 0.6.10, < 2)
       request_store (~> 1.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    benchmark-ips (2.8.2)
+    activemodel (6.0.3.4)
+      activesupport (= 6.0.3.4)
+    activerecord (6.0.3.4)
+      activemodel (= 6.0.3.4)
+      activesupport (= 6.0.3.4)
+    activesupport (6.0.3.4)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 0.7, < 2)
+      minitest (~> 5.1)
+      tzinfo (~> 1.1)
+      zeitwerk (~> 2.2, >= 2.2.2)
+    benchmark-ips (2.8.3)
     byebug (11.1.3)
-    coderay (1.1.2)
-    concurrent-ruby (1.1.6)
+    coderay (1.1.3)
+    concurrent-ruby (1.1.7)
     database_cleaner (1.8.5)
-    diff-lcs (1.3)
-    ffi (1.12.2)
+    diff-lcs (1.4.4)
+    ffi (1.13.1)
     formatador (0.2.5)
     guard (2.16.2)
       formatador (>= 0.2.4)
@@ -30,55 +41,63 @@ GEM
       guard (~> 2.1)
       guard-compat (~> 1.1)
       rspec (>= 2.99.0, < 4.0)
-    i18n (1.8.2)
+    i18n (1.8.5)
       concurrent-ruby (~> 1.0)
     listen (3.2.1)
       rb-fsevent (~> 0.10, >= 0.10.3)
       rb-inotify (~> 0.9, >= 0.9.10)
-    lumberjack (1.2.4)
+    lumberjack (1.2.8)
     method_source (1.0.0)
+    minitest (5.14.2)
     nenv (0.3.0)
     notiffany (0.1.3)
       nenv (~> 0.1)
       shellany (~> 0.0)
+    pg (1.2.3)
     pry (0.13.1)
       coderay (~> 1.1)
       method_source (~> 1.0)
     pry-byebug (3.9.0)
       byebug (~> 11.0)
       pry (~> 0.13.0)
-    rack (2.2.2)
+    rack (2.2.3)
     rake (12.3.3)
     rb-fsevent (0.10.4)
     rb-inotify (0.10.1)
       ffi (~> 1.0)
     request_store (1.5.0)
       rack (>= 1.4)
-    rspec (3.9.0)
-      rspec-core (~> 3.9.0)
-      rspec-expectations (~> 3.9.0)
-      rspec-mocks (~> 3.9.0)
-    rspec-core (3.9.2)
-      rspec-support (~> 3.9.3)
-    rspec-expectations (3.9.2)
+    rspec (3.10.0)
+      rspec-core (~> 3.10.0)
+      rspec-expectations (~> 3.10.0)
+      rspec-mocks (~> 3.10.0)
+    rspec-core (3.10.0)
+      rspec-support (~> 3.10.0)
+    rspec-expectations (3.10.0)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.9.0)
-    rspec-mocks (3.9.1)
+      rspec-support (~> 3.10.0)
+    rspec-mocks (3.10.0)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.9.0)
-    rspec-support (3.9.3)
+      rspec-support (~> 3.10.0)
+    rspec-support (3.10.0)
     shellany (0.0.1)
     thor (1.0.1)
+    thread_safe (0.3.6)
+    tzinfo (1.2.8)
+      thread_safe (~> 0.1)
     yard (0.9.25)
+    zeitwerk (2.4.1)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
+  activerecord (>= 6.0.0, < 6.1)
   benchmark-ips
   database_cleaner (~> 1.5, >= 1.5.3)
   guard-rspec
   mobility!
+  pg
   pry-byebug
   rake (~> 12, >= 12.2.1)
   rspec (~> 3.0)

data/README.md

@@ -2,16 +2,20 @@ Mobility
 ========
 
 [![Gem Version](https://badge.fury.io/rb/mobility.svg)][gem]
-[![Build Status](https://travis-ci.org/shioyama/mobility.svg?branch=master)][travis]
+[![Build Status](https://github.com/shioyama/mobility/workflows/CI/badge.svg)][actions]
 [![Code Climate](https://api.codeclimate.com/v1/badges/72200f2b00c339ec4537/maintainability.svg)][codeclimate]
 [![Gitter Chat](https://badges.gitter.im/mobility-ruby/mobility.svg)](https://gitter.im/mobility-ruby/mobility)
 
 [gem]: https://rubygems.org/gems/mobility
-[travis]: https://travis-ci.org/shioyama/mobility
+[actions]: https://github.com/shioyama/mobility/actions
 [codeclimate]: https://codeclimate.com/github/shioyama/mobility
 [docs]: http://www.rubydoc.info/gems/mobility
 [wiki]: https://github.com/shioyama/mobility/wiki
 
+**This is the readme for version 1.0 of Mobility. If you are using an earlier
+version (0.8.x or earlier), you probably want the readme on the [0-8-stable
+branch](https://github.com/shioyama/mobility/tree/0-8-stable).**
+
 Mobility is a gem for storing and retrieving translations as attributes on a
 class. These translations could be the content of blog posts, captions on
 images, tags on bookmarks, or anything else you might want to store in
@@ -36,10 +40,10 @@ and [Sequel](http://sequel.jeremyevans.net/) ORM, with support for other
 platforms planned.
 
 For a detailed introduction to Mobility, see [Translating with
-Mobility](http://dejimata.com/2017/3/3/translating-with-mobility). See also the
-[Roadmap](https://github.com/shioyama/mobility/wiki/Roadmap) for what's in the
-works for future releases, and other pages of the [wiki][wiki] for more detail
-on usage.
+Mobility](http://dejimata.com/2017/3/3/translating-with-mobility). See also my
+talk at RubyConf 2018, [Building Generic
+Software](https://www.youtube.com/watch?v=RZkemV_-__A), where I explain the
+thinking behind Mobility's design.
 
 If you're coming from Globalize, be sure to also read the [Migrating from
 Globalize](https://github.com/shioyama/mobility/wiki/Migrating-from-Globalize)
@@ -48,22 +52,15 @@ section of the wiki.
 Installation
 ------------
 
-Add this line to your application's Gemfile:
+To use the latest pre-version of Mobility 1.0, add this line to your
+application's Gemfile:
 
 ```ruby
-gem 'mobility', '~> 0.8.13'
-```
-
-Mobility is cryptographically signed. To be sure the gem you install hasn't
-been tampered with, add my public key as a trusted certificate and install:
-
-```
-gem cert --add <(curl -Ls https://raw.github.com/shioyama/mobility/master/certs/shioyama.pem)
-gem install mobility -P MediumSecurity
+gem 'mobility', '~> 1.0.0'
 ```
 
-The MediumSecurity trust profile will verify signed gems, but allow the
-installation of unsigned dependencies.
+For the latest stable version of Mobility, see the readme on the
+[0-8-stable](https://github.com/shioyama/mobility/tree/0-8-stable) branch.
 
 ### ActiveRecord (Rails)
 
@@ -72,7 +69,7 @@ Requirements:
 
 (Support for most backends and features is also supported with
 ActiveRecord/Rails 4.2, but there are some tests still failing. To see exactly
-what might not work, check pending specs in Rails 4.2 Travis builds.)
+what might not work, check pending specs in Rails 4.2 builds.)
 
 To translate attributes on a model, extend `Mobility`, then call `translates`
 passing in one or more attributes as well as a hash of options (see below).
@@ -89,36 +86,52 @@ rails generate mobility:install
 the `--without_tables` option here to skip the migration generation.)
 
 The generator will create an initializer file `config/initializers/mobility.rb`
-with the lines:
+which looks something like this:
 
 ```ruby
-Mobility.configure do |config|
-  config.default_backend = :key_value
-  config.accessor_method = :translates
-  config.query_method    = :i18n
+Mobility.configure do
+
+  # PLUGINS
+  plugins do
+    backend :key_value
+
+    active_record
+
+    reader
+    writer
+
+    # ...
+  end
 end
 ```
 
-To use a different default backend, set `default_backend` to another value (see
-possibilities [below](#backends)).
+Each method call inside the block passed to `plugins` declares a plugin, along
+with an optional default. To use a different default backend, you can
+change the default passed to the `backend` plugin, like this:
+
+```diff
+ Mobility.configure do
+
+   # PLUGINS
+   plugins do
+-    backend :key_value
++    backend :table
+```
 
-You will likely also want to set default values for the various translation
-options described below. You can set these defaults by assigning values to keys
-on the `config.default_options` hash. Below, we turn on the Dirty plugin by
-default, so it will be enabled for all models.
+See other possible backends in the [backends section](#backends).
 
 You can also set defaults for backend-specific options. Below, we set the
-default `type` option for the KeyValue backend to `:string` (this is
-unnecessary and will be ignored if you are using a different backend).
+default `type` option for the KeyValue backend to `:string`.
 
 ```diff
- Mobility.configure do |config|
-   config.default_backend = :key_value
-   config.accessor_method = :translates
-   config.query_method    = :i18n
-+  config.default_options[:dirty] = true
-+  config.default_options[:type]  = :string
-end
+ Mobility.configure do
+
+   # PLUGINS
+   plugins do
+-    backend :key_value
++    backend :key_value, type: :string
+   end
+ end
 ```
 
 We will assume the configuration above in the examples that follow. Other
@@ -132,6 +145,16 @@ See [Getting Started](#quickstart) to get started translating your models.
 Requirements:
 - Sequel >= 4.0
 
+When configuring Mobility, ensure that you include the `sequel` plugin:
+
+```diff
+ plugins do
+   backend :key_value
+
+-    active_record
++    sequel
+```
+
 You can extend `Mobility` just like in ActiveRecord, or you can use the
 `mobility` plugin, which does the same thing:
 
@@ -143,8 +166,8 @@ end
 ```
 
 Otherwise everything is (almost) identical to AR, with the exception that there
-is no equivalent to a Rails generator (so you will need to create the migration
-for any translation table(s) yourself, using Rails generators as a reference).
+is no equivalent to a Rails generator, so you will need to create the migration
+for any translation table(s) yourself, using Rails generators as a reference.
 
 The models in examples below all inherit from `ApplicationRecord`, but
 everything works exactly the same if the parent class is `Sequel::Model`.
@@ -259,15 +282,25 @@ changed and/or customized (see the [Backends](#backends) section below).
 ### <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
-access the value of an attribute in a specific locale, independent of the
-current value of `I18n.locale` (or `Mobility.locale`). There are a few ways to
-do this.
+methods described above (`word.name` and `word.name=`), enabled by including
+the `reader` and `writer` plugins.
+
+You may also want to access the value of an attribute in a specific locale,
+independent of the current value of `I18n.locale` (or `Mobility.locale`). There
+are a few ways to do this.
 
 The first way is to define locale-specific methods, one for each locale you
 want to access directly on a given attribute. These are called "locale
-accessors" in Mobility, and they can be defined by passing a `locale_accessors`
-option when defining translated attributes on the model class:
+accessors" in Mobility, and can be enabled by including the `locale_accessors`
+plugin, with a default set of accessors:
+
+```diff
+ plugins do
+   # ...
++  locale_accessors [:en, :ja]
+```
+
+You can also override this default from `translates` in any model:
 
 ```ruby
 class Word < ApplicationRecord
@@ -296,24 +329,23 @@ word.name_ru
 #=> NoMethodError: undefined method `name_ru' for #<Word id: ... >
 ```
 
-To generate methods for all locales in `I18n.available_locales` (at the time
-the model is first loaded), use `locale_accessors: true`.
+With no plugin option (or a default of `true`), Mobility generates methods for
+all locales in `I18n.available_locales` at the time the model is first loaded.
 
-An alternative to using the `locale_accessors` option is to use the
-`fallthrough_accessors` option, with `fallthrough_accessors: true`. This uses
-Ruby's [`method_missing`](http://apidock.com/ruby/BasicObject/method_missing)
-method to implicitly define the same methods as above, but supporting any
-locale without any method definitions. (Locale accessors and fallthrough
-locales can be used together without conflict, with locale accessors taking
-precedence if defined for a given locale.)
+An alternative to using the `locale_accessors` plugin is to use the
+`fallthrough_accessors` plugin. This uses Ruby's
+[`method_missing`](http://apidock.com/ruby/BasicObject/method_missing) method
+to implicitly define the same methods as above, but supporting any locale
+without any method definitions. (Locale accessors and fallthrough locales can
+be used together without conflict, with locale accessors taking precedence if
+defined for a given locale.)
 
-For example, if we define `Word` this way:
+Ensure the plugin is enabled:
 
-```ruby
-class Word < ApplicationRecord
-  extend Mobility
-  translates :name, fallthrough_accessors: true
-end
+```diff
+ plugins do
+   # ...
++  fallthrough_accessors
 ```
 
 ... then we can access any locale we want, without specifying them upfront:
@@ -374,11 +406,24 @@ word.name_backend.read(:en)
 ```
 
 Internally, all methods for accessing translated attributes ultimately end up
-reading and writing from the backend instance this way.
+reading and writing from the backend instance this way.  (The `write` methods
+do not call underlying backend's methods to persist the change. This is up to
+the user, so e.g. with ActiveRecord you should call `save` write the changes to
+the database).
 
-The `write` methods do not call underlying backend's methods to persist the change.
-This is up to the user (e.g. with ActiveRecord you should call `save` write
-the changes to the database).
+Note that accessor methods are defined in an included module, so you can wrap
+reads or writes in custom logic:
+
+```ruby
+class Post < ApplicationRecord
+  extend Mobility
+  translates :title
+
+  def title(*)
+    super.reverse
+  end
+end
+```
 
 ### Setting the Locale
 
@@ -419,15 +464,28 @@ details on how to configure it for your use case.
 
 ### <a name="fallbacks"></a>Fallbacks
 
-Mobility offers basic support for translation fallbacks. To enable fallbacks,
-pass a hash with fallbacks for each locale as an option when defining
+Mobility offers basic support for translation fallbacks. First, enable the
+`fallbacks` plugin:
+
+```diff
+ plugins do
+   # ...
++  fallbacks
++  locale_accessors
+```
+
+Fallbacks will require `fallthrough_accessors` to handle methods like
+`title_en`, which are used to track changes. For performance reasons it's
+generally best to also enable the `locale_accessors` plugin as shown above.
+
+Now pass a hash with fallbacks for each locale as an option when defining
 translated attributes on a class:
 
 ```ruby
 class Word < ApplicationRecord
   extend Mobility
-  translates :name,    fallbacks: { de: :ja, fr: :ja }, locale_accessors: true
-  translates :meaning, fallbacks: { de: :ja, fr: :ja }, locale_accessors: true
+  translates :name,    fallbacks: { de: :ja, fr: :ja }
+  translates :meaning, fallbacks: { de: :ja, fr: :ja }
 end
 ```
 
@@ -516,7 +574,16 @@ fallbacks](https://github.com/svenfuchs/i18n/wiki/Fallbacks).
 
 ### <a name="default"></a>Default values
 
-Another option is to assign a default value, which will be used if the result of a fetch would otherwise be `nil`:
+Another option is to assign a default value, using the `default` plugin:
+
+```diff
+ plugins do
+   # ...
++  default 'foo'
+```
+
+Here we've set a "default default" of `'foo'`, which will be returned if a fetch would
+otherwise return `nil`. This can be overridden from model classes:
 
 ```ruby
 class Word < ApplicationRecord
@@ -558,24 +625,29 @@ support it. Currently this is models which include
 [dirty](http://sequel.jeremyevans.net/rdoc-plugins/classes/Sequel/Plugins/Dirty.html)
 plugin).
 
-Enabling dirty tracking is as simple as sending the `dirty: true` option when
-defining a translated attribute. The way dirty tracking works is somewhat
-dependent on the model class (ActiveModel or Sequel); we will describe the
-ActiveModel implementation here.
+First, ensure the `dirty` plugin is enabled in your configuration, and that you
+have enabled an ORM plugin (either `active_record` or `sequel`), since the
+dirty plugin will depend on one of these being enabled.
+
+```diff
+ plugins do
+   # ...
+   active_record
++  dirty
+```
+
+(Once enabled globally, the dirty plugin can be selectively disabled on classes
+by passing `dirty: false` to `translates`.)
 
-First, enable dirty tracking (note that this is a persisted AR model, although
-dirty tracking is not specific to AR and works for non-persisted models as well):
+Take this ActiveRecord class:
 
 ```ruby
 class Post < ApplicationRecord
   extend Mobility
-  translates :title, dirty: true
+  translates :title
 end
 ```
 
-(If you want to enable dirty tracking on all models, set the
-`config.default_options[:dirty]` option in your Mobility configuration.)
-
 Let's assume we start with a post with a title in English and Japanese:
 
 ```ruby
@@ -637,9 +709,6 @@ For performance reasons, it is highly recommended that when using the Dirty
 plugin, you also enable [locale accessors](#getset) for all locales which will
 be used, so that methods like `title_en` above are defined; otherwise they will
 be caught by `method_missing` (using fallthrough accessors), which is much slower.
-The easiest way to do this is to set `config.default_options[:locale_accessors]
-= true` in your Mobility config, and make sure that `I18n.available_locales`
-includes all locales you use in production.
 
 For more details on dirty tracking, see the [API
 documentation](http://www.rubydoc.info/gems/mobility/Mobility/Plugins/Dirty).
@@ -647,9 +716,17 @@ documentation](http://www.rubydoc.info/gems/mobility/Mobility/Plugins/Dirty).
 ### Cache
 
 The Mobility cache caches localized values that have been fetched once so they
-can be quickly retrieved again. The cache is enabled by default and should
-generally only be disabled when debugging; this can be done by passing `cache:
-false` when defining an attribute, like this:
+can be quickly retrieved again. The cache plugin is included in the default
+configuration created by the install generator:
+
+```diff
+ plugins do
+   # ...
++  cache
+```
+
+It can be disabled selectively per model by passing `cache: false` when
+defining an attribute, like this:
 
 ```ruby
 class Word < ApplicationRecord
@@ -659,7 +736,8 @@ end
 ```
 
 You can also turn off the cache for a single fetch by passing `cache: false` to
-the getter method, i.e. `post.title(cache: false)`.
+the getter method, i.e. `post.title(cache: false)`. To remove the cache plugin
+entirely, remove the `cache` line from the global plugins configuration.
 
 The cache is normally just a hash with locale keys and string (translation)
 values, but some backends (e.g. KeyValue and Table backends) have slightly more
@@ -667,11 +745,23 @@ complex implementations.
 
 ### <a name="querying"></a>Querying
 
-Mobility backends also support querying on translated attributes, in two
-different ways. The first is via query methods like `where` (and `not` and
-`find_by` in ActiveRecord, and `except` in Sequel). To query this way, use the
-`i18n` class method, which will return a model relation or dataset extended
-with Mobility-specific query method overrides.
+Mobility backends also support querying on translated attributes. To enable
+this feature, include the `query` plugin, and ensure you also have an ORM
+plugin enabled (`active_record` or `sequel`):
+
+```diff
+ plugins do
+   # ...
+   active_record
++  query
+```
+
+Querying defines a scope or dataset class method, whose default name is `i18n`.
+You can override this by passing a default in the configuration, like
+`query :t` to use a name `t`.
+
+Querying is supported in two different ways. The first is via query methods
+like `where` (and `not` and `find_by` in ActiveRecord, and `except` in Sequel).
 
 So for ActiveRecord, assuming a model using KeyValue as its default backend: