embedded_localization 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c558dc3ee3d3357b8bf674ee00423dda8dd10c855deb800b1b4e47946fa1318f
-  data.tar.gz: 252b5481dbc39a41e800551411a1426db9f4fea1759c2c6a7b05e9e6285a1a24
+  metadata.gz: 6957e8085bbd37d3849c1b6f53b58f5d43188277db18acb757da7072d72ca6bc
+  data.tar.gz: 2f1ad574f456f63b92ab8f569e30da8a6d929ca70b941c4dfa1e5685694e0ce9
 SHA512:
-  metadata.gz: a8a28976e403460d65d6fd9c5af50b224ffa46a9d7b466c7bfec4e4766aa762c2c65e5bb54fdb2b0dd7b7c2a4f6d91759889b067e370af9161a869e7ad7b1804
-  data.tar.gz: f7353af27a41afcc4db023bcff8b229f90e062bb8388c84bf4991de528f3021c5e1d00116ea91d8728ff1ffc59f22c648326379d1501e5749f2c3c999992a3df
+  metadata.gz: 940207de0ca5710093871a3abada7fc47ff1eef2993f0038f3bc624a94c1b7af9971fc817eaefadd0db73a1e88ac28f650e55237c1f2f04a72a49516883b6db6
+  data.tar.gz: dc86f831f57c6ec45e8192a8f1ae1dda75c2ae7f0107ff36b4a48ab68840c657e39031b115431d3967825ab2866b39183414e00a4c6825e0265038f55a4f26d7

data/CHANGELOG.md

@@ -1,7 +1,20 @@
 # EmbeddedLocalization CHANGE LOG
 
+## 1.4.0 (2026-08-24)
+ * new `storage:` option for `translates`: store the translations in a `json` / `jsonb` column (`storage: :json`) or in a PostgreSQL `hstore` column (`storage: :hstore`) instead of the YAML `text` column; the translated values are then queryable in SQL (see README, Example 3)
+ * fallbacks now follow the chain configured in `I18n.fallbacks` (e.g. `config.i18n.fallbacks = { 'de-AT' => 'de' }`: `:"de-AT"` → `:de` → `I18n.default_locale`); `I18n.default_locale` is always the last fallback, as before
+ * bug fix: fallbacks did not work for the current `I18n.locale` of a record loaded from the database, nor for a locale that had translations for other attributes; a `nil` translation now always falls back (as the README documented)
+ * bug fix: with `fallbacks: true`, reading an attribute that has no translation in `I18n.default_locale` returned a Hash of nils on unsaved records instead of nil
+ * bug fix: assigning a translation equal to the current value marked the record as changed on models without a DB column for that attribute (the fix for issue #4 only covered models with such a column)
+ * bug fix: `set_localized_attribute(attr, locale, value)` compared against `I18n.locale` instead of `locale`; when the current locale already held the same value, the translation for `locale` was not stored
+ * removed the `Hash.zip` monkey patch (`lib/extensions/hash.rb`); the gem no longer adds methods to core classes
+ * CI: ActiveRecord 6.1, 7.0, 7.1, 7.2, 8.0 and 8.1 are tested against SQLite, PostgreSQL and MySQL; Ruby 2.5 through 4.0, `head` and TruffleRuby; coverage upload through `codecov/codecov-action` instead of the unmaintained `codecov` gem
+
+## 1.3.1 (2024-11-26)
+ * [Issue 14](https://github.com/tilo/embedded_localization/pull/14) Fix active support proxy object deprecation (thanks to [Romain Morlevat](https://github.com/RomainMorlevat))
+
 ## 1.3.0 (2024-11-13)
-  - fixed ([issue 10](https://github.com/tilo/embedded_localization/issues)) to support Rails >= 7.1 (thanks to [Romain Morlevat](https://github.com/RomainMorlevat))
+ * fixed ([issue 10](https://github.com/tilo/embedded_localization/issues)) to support Rails >= 7.1 (thanks to [Romain Morlevat](https://github.com/RomainMorlevat))
   
 ## 1.2.2 (2022-04-25)
 * improved docs

data/Gemfile

@@ -1,4 +1,6 @@
-source "http://rubygems.org"
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
 
 # Specify your gem's dependencies in embedded_localization.gemspec
 gemspec
@@ -7,7 +9,16 @@ gem 'rake'
 
 group :test do
   gem 'rspec'
-  gem 'activerecord'
+  gem 'simplecov'
   gem 'i18n'
-  gem 'sqlite3'
+  gem 'pg'     if ENV['DB'] == 'postgresql'   # DB=postgresql bundle exec rake  (jsonb and hstore columns)
+  gem 'mysql2' if ENV['DB'] == 'mysql'        # DB=mysql      bundle exec rake
+
+  if ENV['RAILS_VERSION']                     # RAILS_VERSION=7.2 bundle exec rake
+    gem 'activerecord', "~> #{ENV['RAILS_VERSION']}.0"
+    gem 'sqlite3', Gem::Version.new(ENV['RAILS_VERSION']) < Gem::Version.new('7.1') ? '~> 1.4' : '>= 1.4'   # the sqlite adapter of Rails < 7.1 requires sqlite3 ~> 1.4
+  else
+    gem 'activerecord'
+    gem 'sqlite3'
+  end
 end

data/README.md

@@ -1,10 +1,12 @@
 # Embedded Localization
 
-[![Build Status](https://secure.travis-ci.org/tilo/embedded_localization.png?branch=master)](http://travis-ci.org/tilo/embedded_localization) [![Gem Version](https://badge.fury.io/rb/embedded_localization.svg)](http://badge.fury.io/rb/embedded_localization)
+![Gem Version](https://img.shields.io/gem/v/embedded_localization) [![codecov](https://codecov.io/gh/tilo/embedded_localization/graph/badge.svg?token=MX3ULB0S1Y)](https://codecov.io/gh/tilo/embedded_localization) <!-- [![Downloads](https://img.shields.io/gem/dt/embedded_localization)](https://rubygems.org/gems/embedded_localization) --> [![RubyGems](https://img.shields.io/badge/RubyGems-embedded__localization-brightgreen?logo=rubygems&logoColor=white)](https://rubygems.org/gems/embedded_localization) [![Ruby Toolbox](https://img.shields.io/badge/Ruby%20Toolbox-embedded__localization-brightgreen)](https://www.ruby-toolbox.com/projects/embedded_localization)
 
-`embedded_localization` is compatible with Rails 6.x, 7.x, and adds model translations to ActiveRecord.  `embedded_localization` is compatible with and builds on the new [I18n API in Ruby on Rails](http://guides.rubyonrails.org/i18n.html)
+`embedded_localization` allows you to store your translations directly insight each record. 
 
-`embedded_localization` is very lightweight, and allows you to transparently store translations of attributes right inside each record — no extra database tables needed to store the localization data! Make sure that your database default encoding is UTF-8 or UFT-16.
+`embedded_localization` is compatible with Rails 6.1, 7.x and 8.x, and adds model translations to ActiveRecord, and is compatible with and builds on the [I18n API in Ruby on Rails](http://guides.rubyonrails.org/i18n.html)
+
+`embedded_localization` is very lightweight, and allows you to transparently store multiple translations of attributes right inside each record — no extra database tables needed to store the localization data! Make sure that your database default encoding is UTF-8 or UFT-16.
 
 Model translations with `embedded_localization` use default ActiveRecord features and do not limit any ActiveRecord functionality.
 
@@ -13,7 +15,7 @@ On top of that, you also get tools for checking into which locales an attribute
 
 ## Motivation
 
-One real-life scenario is that you have a SaaS system which needs custom text for each company, which also needs to be translated in to several languages. Another scenario is that you have dynamic content that needs to be translated.
+One real-life scenario is that you have a SaaS system which needs custom text for each company, which also needs to be translated in to several languages. Product translations are another use case, as well as movies, books, TV-shows, etc. Another scenario is that you have dynamic content that needs to be translated.
 
 A recent project needed some localization support for ActiveRecord model data, but I did not want to clutter the schema with one additional table for each translated model, as the globalize gem requires.  A second requirement was to allow SQL queries of the fields using the default locale.
 
@@ -24,7 +26,8 @@ If your requirements are different, this approach might not work for you. In tha
 
 ## Requirements
 
-* ActiveRecord >= 6  
+* Ruby >= 2.5  # Ruby 2.5 through 4.0, `head` and TruffleRuby are tested in CI
+* ActiveRecord >= 6  # ActiveRecord 6.1, 7.0, 7.1, 7.2, 8.0 and 8.1 are tested in CI, against SQLite, PostgreSQL and MySQL
 * [I18n](http://guides.rubyonrails.org/i18n.html)
 
 ## Installation
@@ -38,6 +41,8 @@ To install Embedded_Localization, use:
 
 Adding localization to a table is very simple. Just add a text field named `i18n` to the table, and you are ready to go!  This allows you to add translated fields via the helper method `translates` in the model.
 
+Instead of a text field, the `i18n` column can also be a `json` / `jsonb` column, or a PostgreSQL `hstore` column, which makes the translated values queryable in SQL — see [Example 3](#example-3).
+
 Optionally, you can also keep a DB field with the same name as the translated field, which will store the values for the `I18n.default_locale`.
 
 Model translations allow you to translate your models’ attribute values. The attribute type needs to be string or text.
@@ -89,6 +94,68 @@ class CreateGenres < ActiveRecord::Migration
 end
 ```
 
+### Example 3
+
+Instead of the YAML text column, the translations can be stored in a `json` / `jsonb` column, or in a PostgreSQL `hstore` column. Tell `translates` which one you use with the `storage:` option:
+
+| `translates ... storage:` | `i18n` column type                                         | Stored as                                              | SQL example: find `name` translated to `:de`                                                                                                           |
+|---------------------------|------------------------------------------------------------|--------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `:yaml` (default)         | `text`                                                     | YAML: `{en: {name: "..."}, de: {name: "..."}}`         | not possible                                                                                                                                           |
+| `:json` or `:jsonb`       | `json` (SQLite, MySQL, PostgreSQL) or `jsonb` (PostgreSQL) | JSON: `{"en": {"name": "..."}, "de": {"name": "..."}}` | PostgreSQL: `i18n -> 'de' ->> 'name' = ?` ; SQLite: `json_extract(i18n, '$.de.name') = ?` ; MySQL: `JSON_UNQUOTE(JSON_EXTRACT(i18n, '$.de.name')) = ?` |
+| `:hstore`                 | `hstore` (PostgreSQL)                                      | flat keys: `"en.name" => "...", "de.name" => "..."`    | `i18n -> 'de.name' = ?`                                                                                                                                |
+
+```ruby
+class CreateGenres < ActiveRecord::Migration[7.1]
+  def change
+    create_table :genres do |t|
+      t.jsonb  :i18n    # stores ALL the translated attributes; persisted as JSON  (`t.json :i18n` on SQLite / MySQL, or on PostgreSQL if you prefer json over jsonb)
+
+      t.timestamps
+    end
+  end
+end
+
+class Genre < ActiveRecord::Base
+  translates :name, :description, storage: :json     # :json for json and jsonb columns (:jsonb is accepted as well), :hstore for an hstore column
+end
+
+Genre.where("i18n -> 'de' ->> 'name' = ?", "Science-Fiction")                        # PostgreSQL json / jsonb
+Genre.where("json_extract(i18n, '$.de.name') = ?", "Science-Fiction")                  # SQLite json
+Genre.where("JSON_UNQUOTE(JSON_EXTRACT(i18n, '$.de.name')) = ?", "Science-Fiction")    # MySQL json
+```
+
+For an `hstore` column, the migration needs `enable_extension 'hstore'`, and each translation is stored under the key `"<locale>.<attribute>"`, because `hstore` cannot nest:
+
+```ruby
+class CreateGenres < ActiveRecord::Migration[7.1]
+  def change
+    enable_extension 'hstore'
+
+    create_table :genres do |t|
+      t.hstore :i18n    # stores ALL the translated attributes; persisted as "en.name" => "...", "de.name" => "...", ...
+
+      t.timestamps
+    end
+  end
+end
+
+class Genre < ActiveRecord::Base
+  translates :name, :description, storage: :hstore
+end
+
+Genre.where("i18n -> 'de.name' = ?", "Science-Fiction")
+```
+
+The extra DB column for the default locale from Example 2 (`t.string :name`) works the same way with all three storages.
+
+Notes:
+
+* In Ruby, the `i18n` Hash always has Symbol keys for locales and attributes, whatever the storage: `genre.i18n  # => {en: {name: "Science Fiction"}, de: {name: "Science-Fiction"}}`.
+* Existing tables keep working unchanged: the default is still the YAML `text` column. Changing the column type of an existing table means converting the stored YAML to JSON or hstore in a data migration; the gem does not do that for you.
+* `json` columns work on SQLite, MySQL and PostgreSQL; `jsonb` and `hstore` columns are PostgreSQL only. The test suite runs against all three databases (`DB=postgresql` / `DB=mysql`, default SQLite).
+* `Genre.translation_storage  # => :json` reports the storage of a model.
+
+
 # Usage
 
 In your code you can modify the values of your translated attributes in two ways.
@@ -162,7 +229,20 @@ g.set_localized_attribute( :name, :jp, "サイエンスフィクション" )
 scifi = Genre.where(:name => "science fiction").first
 ```
 
-Limitation: You can not search for the translated strings other than for your default locale.
+Limitation: with the YAML text column (the default), you can not search for the translated strings other than for your default locale.
+
+With a `json` / `jsonb` / `hstore` column (see Example 3) every locale can be searched, and the extra DB column for the default locale is still possible on top of that:
+
+```ruby
+class Genre < ActiveRecord::Base
+  translates :name, :description, storage: :json     # or :hstore
+end
+
+Genre.where("i18n -> 'jp' ->> 'name' = ?", "サイエンスフィクション")                        # PostgreSQL json / jsonb
+Genre.where("json_extract(i18n, '$.jp.name') = ?", "サイエンスフィクション")                  # SQLite json
+Genre.where("JSON_UNQUOTE(JSON_EXTRACT(i18n, '$.jp.name')) = ?", "サイエンスフィクション")    # MySQL json
+Genre.where("i18n -> 'jp.name' = ?", "サイエンスフィクション")                               # PostgreSQL hstore (storage: :hstore)
+```
 
 
 ## Data Migration
@@ -179,9 +259,41 @@ end
 Genre.record_timestamps = true
 ```
 
+### Converting the `i18n` column from YAML text to json / jsonb / hstore
+
+The gem does not convert stored data. This migration does it for a table that was created as in Example 1 or 2: it renames the old column, adds the new one, copies every record's translations, and drops the old column. The model inside the migration reads the old column with `serialize` (the way the gem wrote it) and writes the new column through `translates ... storage:`, so the conversion is the same for `:json`, `:jsonb` and `:hstore`.
+
+```ruby
+class ConvertGenresI18nToJsonb < ActiveRecord::Migration[7.1]
+  # a model for this migration only
+  class Genre < ActiveRecord::Base
+    serialize :i18n_yaml, coder: YAML, type: Hash          # the old column
+    translates :name, :description, storage: :jsonb        # the new column;  :json or :hstore work the same way
+  end
+
+  def up
+    rename_column :genres, :i18n, :i18n_yaml
+    add_column    :genres, :i18n, :jsonb                     # or :json / :hstore  (hstore also needs enable_extension 'hstore')
+    Genre.reset_column_information
+
+    Genre.find_each do |genre|
+      genre.update_column(:i18n, genre.i18n_yaml)            # update_column: no validations, no callbacks, timestamps untouched
+    end
+
+    remove_column :genres, :i18n_yaml
+  end
+
+  def down
+    raise ActiveRecord::IrreversibleMigration
+  end
+end
+```
+
+Afterwards, change the model to `translates :name, :description, storage: :jsonb` (or `:json` / `:hstore`). This migration is run by the test suite against SQLite (json), MySQL (json) and PostgreSQL (json, jsonb, hstore), see `spec/embedded_localization/storage_conversion_spec.rb`.
+
 ## I18n fallbacks for empty translations
 
-It is possible to enable fallbacks for empty translations. It will depend on the configuration setting you have set for I18n translations in your Rails config, or you can enable fallback when you define the translation fields. Currently we only support fallback to `I18n.default_locale`
+It is possible to enable fallbacks for empty translations. It will depend on the configuration setting you have set for I18n translations in your Rails config, or you can enable fallback when you define the translation fields. The fallback locales are the chain configured in `I18n.fallbacks` (e.g. `config.i18n.fallbacks = { 'de-AT' => 'de' }` makes `:"de-AT"` fall back to `:de`), followed by `I18n.default_locale`, which is always the last fallback; without a configured chain, the fallback is `I18n.default_locale` alone.
 
 You can enable them by adding the next line to `config/application.rb` (or only `config/environments/production.rb` if you only want them in production)
 
@@ -211,6 +323,22 @@ I18n.locale = :de
 g.name  # => 'science fiction'
 ```
 
+With a fallback chain (Rails: `config.i18n.fallbacks = { 'de-AT' => 'de' }`), the locales are tried in this order: the requested locale, its chain, then `I18n.default_locale`:
+
+```ruby
+class Genre < ActiveRecord::Base
+  translates :name, :description, :fallbacks => true
+end
+
+g = Genre.first
+g.name(:en)       # => 'science fiction'
+g.name(:de)       # => 'Science-Fiction'
+g.name(:"de-AT")  # => 'Science-Fiction'    (no :"de-AT" translation, so :de is used)
+g.name(:fr)       # => 'science fiction'    (no chain for :fr, so I18n.default_locale is used)
+
+Genre.fallback_locales(:"de-AT")  # => [:de, :en]   the locales tried after :"de-AT"
+```
+
 ## Want some Candy?
 
 It's nice to have the values of attributes be set or read with the current locale, but `embedded_localization` offers you a couple of additional features, which can come in handy.
@@ -222,6 +350,7 @@ Each class which uses `embedded_localization` will have these additional methods
 * Klass.translated_attributes
 * Klass.translated?
 * Klass.fallbacks?
+* Klass.translation_storage
 
 e.g.:
 
@@ -229,6 +358,7 @@ e.g.:
 Genre.translated_attributes # => [:name,:description]
 Genre.translated?  # => true
 Genre.fallbacks?  # => false
+Genre.translation_storage  # => :yaml   (the `storage:` option given to `translates`: :yaml, :json, :jsonb or :hstore)
 ```
 
 ### Instance Methods

data/Rakefile

@@ -1,18 +1,15 @@
-require "bundler/gem_tasks"
-
-require 'rubygems'
-require 'rake'
+# frozen_string_literal: true
 
+require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
 
-desc "Run RSpec"
-RSpec::Core::RakeTask.new do |t|
-  t.verbose = false
-end
+RSpec::Core::RakeTask.new(:spec)
 
-desc "Run specs for all test cases"
-task :spec_all do
-  system "rake spec"
-end
+task default: :spec
 
-task :default => :spec
+desc 'Run spec with coverage'
+task :coverage do
+  ENV['COVERAGE'] = 'true'
+  Rake::Task['spec'].execute
+  `open coverage/index.html`
+end

data/embedded_localization.gemspec

@@ -1,6 +1,7 @@
 # -*- encoding: utf-8 -*-
-$:.push File.expand_path("../lib", __FILE__)
-require "embedded_localization/version"
+# frozen_string_literal: true
+
+require File.expand_path("lib/embedded_localization/version", __dir__)
 
 Gem::Specification.new do |spec|
   spec.name        = "embedded_localization"
@@ -9,24 +10,27 @@ Gem::Specification.new do |spec|
   spec.email       = ["tilo.sloboda@gmail.com"]
   spec.homepage    = "https://github.com/tilo/embedded_localization"
   spec.summary     = %q{Rails I18n: library for embedded ActiveRecord model/data translation}
-  spec.description = %q{Rails I18n: Embedded_Localization for ActiveRecord is very lightweight, and allows you to transparently store translations of attributes right inside each record -- no extra database tables needed to store the localization data!}
+  spec.description = %q{Rails I18n: a very lightweight tool to allow you to transparently store multiple translations of attributes directly inside each DB record -- no extra database tables needed to store the localization data! All translations of a record live in one column: a YAML text column, a json/jsonb column, or a PostgreSQL hstore column.}
+  spec.license     = "MIT"
 
-  # spec.platform = Gem::Platform::RUBY
   spec.required_ruby_version = ">= 2.5.0"
 
-  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["homepage_uri"]    = spec.homepage
   spec.metadata["source_code_uri"] = spec.homepage
-  spec.metadata["changelog_uri"] = "https://github.com/tilo/embedded_localization/blob/main/CHANGELOG.md"
+  spec.metadata["changelog_uri"]   = "https://github.com/tilo/embedded_localization/blob/main/CHANGELOG.md"
+  spec.metadata["bug_tracker_uri"] = "https://github.com/tilo/embedded_localization/issues"
 
-  spec.files         = `git ls-files`.split("\n")
-  spec.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
-  spec.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  # Files shipped in the gem: everything tracked by git except the specs and the CI / git configuration.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      f.match(%r{\A(?:spec/|\.(?:git|github|rspec|circleci))})
+    end
+  end
   spec.require_paths = ["lib"]
-  spec.licenses = ['MIT']
-  # specify any dependencies here; for example:
+
   spec.add_development_dependency "rspec"
+  spec.add_development_dependency "simplecov"
   spec.add_development_dependency "activerecord", ">= 6"
   spec.add_development_dependency "i18n"
   spec.add_development_dependency "sqlite3"
-  # spec.add_runtime_dependency "rest-client"
 end

data/lib/embedded_localization/active_record/act_macro.rb

@@ -1,15 +1,24 @@
 module EmbeddedLocalization
   module ActiveRecord
     module ActMacro
+      STORAGES = [:yaml, :json, :jsonb, :hstore].freeze
+
+      # translates :name, :description                    # `i18n` is a text column, stored as YAML (default)
+      # translates :name, :description, storage: :json     # `i18n` is a json or jsonb column
+      # translates :name, :description, storage: :hstore   # `i18n` is a PostgreSQL hstore column
+      # translates :name, :description, fallbacks: true    # a locale without translations reads the I18n.default_locale value
+      #
+      # for details about I18n fallbacks, check the source:
+      # i18n-0.9.0/lib/i18n/backend/fallbacks.rb
+      # i18n-0.9.0/lib/i18n/locale/fallbacks.rb
       def translates(*attr_names)
         return if translates?  # cludge to make sure we don't set this up twice..
 
-        # for details about I18n fallbacks, check the source:
-        # i18n-0.9.0/lib/i18n/backend/fallbacks.rb
-        # i18n-0.9.0/lib/i18n/locale/fallbacks.rb
-
-        # options[:fallbacks] => true or false # not used at this time
         options = attr_names.extract_options!
+        storage = (options[:storage] || :yaml).to_sym
+        unless STORAGES.include?(storage)
+          raise ArgumentError, "unknown storage: #{storage.inspect} -- use one of #{STORAGES.inspect}"
+        end
 
         class_attribute :translated_attribute_names, :translation_options
         self.translated_attribute_names = attr_names.map(&:to_sym).sort.uniq
@@ -18,73 +27,27 @@ module EmbeddedLocalization
         include InstanceMethods
         extend  ClassMethods
 
-        #-
-        # if ActiveRecord::Base is in the parent-chain of the class where we are included into:
-        # ::Rails::Railtie.subclasses.map(&:to_s).include?("ActiveRecord::Railtie")
-        #+
-
-        serialize :i18n, coder: YAML, type: Hash   # we should also protect it from direct assignment by the user
-
-        #-
-        # if Mongoid::Document is in the list of classes which extends the class we are included into:
-        # ::Rails::Railtie.subclasses.map(&:to_s).include?("Rails::Mongoid::Railtie")
-
-        #    field :i18n, type: Hash
-        # but on the other hand, Mongoid now supports "localized fields" -- so we don't need to re-implement this.
-        # Yay! Durran Jordan is awesome! :-) See: http://mongoid.org/docs/documents/localized.html
-        #
-        # NOTE: I like how Durran implemented the localization in Mongoid.. too bad I didn't see that before.
-        # I'm thinking of re-writing this gem to store the localization hash per attribute... hmm... hmm... thinking...
-        # there would be a couple of advantages to store the I18n-hash per attribute:
-        #   - drop-in internationalization for existing String type attributes
-        #   - works well with rails scaffolding and with protection of attributes (attr_protected / attr_accessible)
-        #   - we can easily hide the internal hash by re-defining the attr-accessors for doing the I18n
-        #   - we can better add the per-attribute versioning, which is planned
-        #   -
-        #+
+        # the `i18n` column holds all translations of the record as {locale => {attribute => value}}
+        # we should also protect it from direct assignment by the user
+        case storage
+        when :yaml
+          serialize :i18n, coder: YAML, type: Hash
+        when :json, :jsonb
+          attribute :i18n, EmbeddedLocalization::Storage::Json.new
+        when :hstore
+          attribute :i18n, EmbeddedLocalization::Storage::Hstore.new
+        end
 
         after_initialize :initialize_i18n_hashes
 
         # dynamically define the accessors for the translated attributes:
-
         translated_attribute_names.each do |attr_name|
-          class_eval do
-            # define the getter method
-            #
-            define_method(attr_name) do |locale = I18n.locale|
-              if self.i18n.has_key?(locale)
-                if self.i18n[locale].keys.include?(attr_name)
-                  self.i18n[ locale ][attr_name]
-                else
-                  nil
-                end
-              else
-                # fallback to the I18n.default_locale if we do fallbacks:
-                if self.class.fallbacks? && self.i18n[ I18n.default_locale ]
-                  return self.i18n[ I18n.default_locale ][attr_name]
-                else
-                  return nil
-                end
-              end
-            end
-
-            # define the setter method
-            #
-            define_method(attr_name.to_s+ '=') do |new_translation|
-              # first check if nothing changed - then we can just return, so that timestamps and other records don't get touched
-              if self.i18n.class == Hash && (self.i18n[I18n.locale]) && (self.i18n[I18n.locale][attr_name.to_sym] == new_translation)
-                return if (I18n.locale != I18n.default_locale)
-                return if (I18n.locale == I18n.default_locale) && (read_attribute(attr_name) == new_translation) # both i18n and attr_name need to be equal to new_translation
-              end
+          define_method(attr_name) do |locale = I18n.locale|
+            get_localized_attribute(attr_name, locale)
+          end
 
-              self.i18n_will_change!     # for ActiveModel Dirty tracking
-              if self.attributes.has_key?(attr_name.to_s)  # if user has defined DB field with that name
-                write_attribute(attr_name , new_translation) if I18n.locale == I18n.default_locale
-              end
-              self.i18n ||= Hash.new
-              self.i18n[I18n.locale] ||= Hash.new
-              self.i18n[I18n.locale][attr_name.to_sym] = new_translation
-            end
+          define_method("#{attr_name}=") do |new_translation|
+            set_localized_attribute(attr_name, I18n.locale, new_translation)
           end
         end
       end
@@ -95,4 +58,3 @@ module EmbeddedLocalization
     end
   end
 end
-

data/lib/embedded_localization/active_record/class_methods.rb

@@ -16,12 +16,26 @@ module EmbeddedLocalization
         translated_attribute_names.include?(name.to_sym)
       end
 
+      # How the `i18n` column is stored: :yaml (text column, the default), :json, :jsonb or :hstore
+      def translation_storage
+        (translation_options[:storage] || :yaml).to_sym
+      end
+
       # # determine if we are using fallbacks
       def fallbacks?
         i18n_fallbacks = I18n.backend.class.included_modules.map(&:to_s).include?('I18n::Backend::Fallbacks')   # will be true if config.i18n.fallbacks => true in config
         i18n_fallbacks || translation_options[:fallbacks] == true
       end
 
+      # The locales to look at, in order, when `locale` has no translation for an attribute:
+      # the chain configured in I18n.fallbacks (e.g. config.i18n.fallbacks = { 'de-AT' => 'de' } gives :de for :"de-AT";
+      # I18n.fallbacks exists once i18n/backend/fallbacks is loaded, which Rails does for config.i18n.fallbacks),
+      # followed by I18n.default_locale. `locale` itself is not part of the result.
+      def fallback_locales(locale)
+        chain = I18n.respond_to?(:fallbacks) ? I18n.fallbacks[locale] : []
+        (chain + [I18n.default_locale]).uniq - [locale]
+      end
+
       #-
       # # fetch the fallbacks from the i18n backend
       # def fallbacks

data/lib/embedded_localization/active_record/instance_methods.rb

@@ -2,44 +2,42 @@ module EmbeddedLocalization
   module ActiveRecord
     module InstanceMethods
 
-      # - we only support fallbacks to I18n.default_locale for now
+      # Returns the translation of attr_name for the given locale; nil if there is none.
       # - will convert given locale to symbol, e.g. "en","En" to :en
-
+      # - with fallbacks (see ClassMethods#fallbacks?), a nil translation is looked up in the fallback locales instead:
+      #   the chain configured in I18n.fallbacks, then I18n.default_locale (see ClassMethods#fallback_locales)
       def get_localized_attribute(attr_name, locale)
-        locale = locale.downcase.to_sym  if locale.class == String # ensure that locale is always a symbol
+        attr_name = attr_name.to_sym
+        locale    = normalize_locale(locale)
 
-        if self.i18n.has_key?(locale)
-          if self.i18n[locale].keys.include?(attr_name)
-            self.i18n[locale][attr_name]
-          else
-            nil
-          end
-        else
-          if self.class.fallbacks? && self.i18n[ I18n.default_locale ]
-            return self.i18n[ I18n.default_locale ][attr_name]
-          else
-            return nil
-          end
+        translation = translation_for(attr_name, locale)
+        return translation unless translation.nil? && self.class.fallbacks?
+
+        self.class.fallback_locales(locale).each do |fallback_locale|
+          translation = translation_for(attr_name, fallback_locale)
+          return translation unless translation.nil?
         end
+        nil
       end
 
+      # Sets the translation of attr_name for the given locale.
       # - will convert given locale to symbol, e.g. "en","En" to :en
-
+      # - for I18n.default_locale, a DB column with the attribute's name (if the user defined one) is written too,
+      #   so that the default locale values can be used in SQL queries
+      # - does nothing when the value is unchanged, so the record stays clean and its timestamps are not touched
       def set_localized_attribute(attr_name, locale, new_translation)
-        locale = locale.downcase.to_sym  if locale.class == String # ensure that locale is always a symbol
+        attr_name = attr_name.to_sym
+        locale    = normalize_locale(locale)
 
-        # first check if nothing changed - then we can just return, so that timestamps and other records don't get touched
-        if self.i18n.class == Hash && (self.i18n[I18n.locale]) && (self.i18n[I18n.locale][attr_name.to_sym] == new_translation)
-          return if (I18n.locale != I18n.default_locale)
-          return if (I18n.locale == I18n.default_locale) && (read_attribute(attr_name) == new_translation) # both i18n and attr_name need to be equal to new_translation
-        end
+        return if translation_unchanged?(attr_name, locale, new_translation)
 
         self.i18n_will_change!     # for ActiveModel Dirty tracking
-        if self.attributes.has_key?(attr_name.to_s)  # if user has defined DB field with that name
-          write_attribute(attr_name , new_translation) if locale == I18n.default_locale
+        if native_column?(attr_name) && locale == I18n.default_locale
+          write_attribute(attr_name, new_translation)
         end
+        self.i18n ||= Hash.new
         self.i18n[locale] ||= Hash.new
-        self.i18n[locale][attr_name.to_sym] = new_translation
+        self.i18n[locale][attr_name] = new_translation
       end
 
       # Returns all locales used for translation of all documents of this class.
@@ -63,7 +61,6 @@ module EmbeddedLocalization
       #
       def translated?(name)
         self.class.translated?(name)
-#        self.class.instance_variable_get(translated_attribute_names).include?(name.to_sym)
       end
 
       # Purpose: to see the translation coverage
@@ -114,14 +111,37 @@ module EmbeddedLocalization
       end
 
       private
-      # initialized the serialized 'i18n' attribute with Hash of Hashes,
-      #   containing all pre-defined translated attributes with nil value
+
+      # initializes the `i18n` attribute with an empty Hash for I18n.locale and for I18n.default_locale
       def initialize_i18n_hashes
         self.i18n ||= Hash.new
-        self.i18n[ I18n.locale ] ||= Hash.new(Hash.zip(translated_attribute_names,[]))
-        if I18n.locale != I18n.default_locale
-          self.i18n[ I18n.default_locale ] ||= Hash.new(Hash.zip(translated_attribute_names,[]))
-        end
+        self.i18n[ I18n.locale ]         ||= Hash.new
+        self.i18n[ I18n.default_locale ] ||= Hash.new
+      end
+
+      def normalize_locale(locale)
+        locale.is_a?(String) ? locale.downcase.to_sym : locale   # ensure that locale is always a symbol
+      end
+
+      # the stored translation of attr_name in locale; nil when the locale or the attribute is not there
+      def translation_for(attr_name, locale)
+        translations = self.i18n[locale]
+        translations[attr_name] if translations
+      end
+
+      # did the user define a DB column with the name of the translated attribute?
+      def native_column?(attr_name)
+        has_attribute?(attr_name)
+      end
+
+      # true when the record already holds exactly this translation -- and, for I18n.default_locale on a model
+      # with a native column for the attribute, the column holds it too
+      def translation_unchanged?(attr_name, locale, new_translation)
+        return false unless self.i18n.is_a?(Hash) && self.i18n[locale]
+        return false unless self.i18n[locale][attr_name] == new_translation
+        return true  unless locale == I18n.default_locale && native_column?(attr_name)
+
+        read_attribute(attr_name) == new_translation
       end
 
     end