Mobility Ruby Gem

Mobility has its own locale setting that defaults to I18n.locale but can be set independently. This is useful when you want to show content in one language while the UI is in another.

Mobility.locale = :fr

# Set locale within a block
Mobility.with_locale(:ja) do
  Mobility.locale #=> :ja
end
# Mobility.locale is back to :fr

Mobility uses RequestStore to ensure these global variables are reset after every request, making it thread-safe in Rails environments.

Mobility.with_locale(:ja) do
  # code using Japanese translations
end

Mobility requires Sequel >= 4.0.

1. Configure Plugins: Ensure you include the sequel plugin in your global configuration:

   plugins do
     backend :key_value
     sequel
   end

2. Extend Models: You can extend models using extend Mobility (similar to ActiveRecord) or use the mobility plugin:

   class Word < ::Sequel::Model
     plugin :mobility
     translates :name, :meaning
   end

3. Migrations: Unlike Rails, there is no generator for Sequel. You must create the translation table migrations manually.

The default plugin allows you to return a fallback value if no translation is found for the current locale.

Global Default:

Mobility.configure do
  plugins do
    default 'foo'
  end
end

Model-level Default:

class Word < ApplicationRecord
  extend Mobility
  translates :name, default: 'foo'
end

Dynamic Defaults (Proc): You can pass a Proc as a default. The proc is called with the model instance as context and receives arguments like attribute, locale, and options:

translates :name, default: ->(model, attribute, locale, options) { "Default for #{locale}" }

Overriding at Runtime:

word.name(default: 'bar')

Fallbacks allow a locale to return a value from another locale if the requested one is missing.

1. Enable Plugins: You must enable both fallbacks and locale_accessors (for performance/tracking).

   plugins do
     fallbacks
     locale_accessors
   end

2. Define Fallbacks in Model: Pass a hash to the fallbacks option in translates.

class Word < ApplicationRecord
  extend Mobility
  translates :name, fallbacks: { de: :ja, fr: :ja }
end

In this example, if name is requested in German (:de) or French (:fr) and is missing, Mobility will return the Japanese (:ja) value.

Disabling Fallbacks:

• Pass fallback: false to the getter: word.meaning(fallback: false).
• Pass a specific locale option: word.meaning(locale: :de) (this disables fallbacks for that call).

Mobility requires ActiveRecord >= 7.0 for Rails integration.

To set up the default KeyValue backend, run the following generator to create an initializer and the necessary migration for shared translation tables:

rails generate mobility:install

Note: If you plan to use a different backend (not the default KeyValue), use the --without_tables option to skip generating the default migration:

rails generate mobility:install --without_tables

After running the generator, you can configure plugins in config/initializers/mobility.rb using the Mobility.configure block.

To track changes to translated attributes (e.g., using attribute_was or changed?), enable the dirty plugin. This requires an ORM plugin (active_record or sequel) to be enabled as well.

Configuration:

plugins do
  active_record
  dirty
end

Usage: Mobility uses locale suffixes to indicate which locale has changed:

post.title = "a new title"
Mobility.with_locale(:ja) { post.title = "新しいタイトル" }

post.changed #=> ["title_en", "title_ja"]
post.title_was #=> "Introducing Mobility"
post.previous_changes #=> { "title_en" => [...], "title_ja" => [...] }

Performance Tip: Always enable locale_accessors for the locales you use with the dirty plugin to avoid the performance penalty of method_missing.

Add the mobility gem to your application's Gemfile.

gem 'mobility', '~> 1.3.2'

The Mobility::Backends::Sequel::KeyValue backend relies on a caching mechanism to manage translation changes. Because Sequel lacks certain association-building capabilities found in ActiveRecord, the backend uses a cache to track which translations need to be saved or destroyed during the model lifecycle.

Ensure your configuration explicitly enables the cache to avoid a CacheRequired error.

When setting up a backend for attributes, you can specify the backend using several formats:

1. A Symbol or String: Represents the name of the backend (e.g., :json).
2. A Class: The actual backend class to use.
3. A two-element Array: [backend_name_or_class, options_hash]. This allows you to pass specific configuration options to that backend.

If you provide an array, all keys in the options hash must be valid for that specific backend. If invalid keys are provided, an InvalidOptionKey error is raised.

# Example of configuring a backend with specific options using an array
# mobility_backend_class, [backend, options]
# (Note: The exact DSL syntax depends on the model setup block defined in the main documentation)