embedded_localization 1.0.0 → 1.1.0

data/.travis.yml

@@ -0,0 +1,21 @@
+language: ruby
+bundler_args: --without development
+rvm:
+  - 1.8.7
+  - 1.9.2
+  - 1.9.3
+  - 2.0.0
+  - ruby-head
+  - ree
+matrix:
+  allow_failures:
+    - rbx-18mode
+    - rbx-19mode
+    - rvm: ruby-head
+    - rvm: ree
+    - rvm: 1.8.7
+    - rvm: 1.9.2
+    - rvm: rbx-18mode
+branches:
+  only:
+    - master

data/Gemfile

@@ -2,3 +2,12 @@ source "http://rubygems.org"
 
 # Specify your gem's dependencies in embedded_localization.gemspec
 gemspec
+
+gem 'rake'
+
+group :test do
+  gem 'rspec', "~> 2.14"
+  gem 'activerecord', "~> 4.0.0"
+  gem 'i18n'
+  gem 'sqlite3'
+end

data/README.md

@@ -0,0 +1,372 @@
+# Embedded Localization
+
+[![Build Status](https://secure.travis-ci.org/tilo/embedded_localization.png?branch=master)](http://travis-ci.org/tilo/embedded_locallization)
+
+`embedded_loalization` is compatible with Rails 3 and Rails 4, 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` 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.
+
+Model translations with `embedded_localization` use default ActiveRecord features and do not limit any ActiveRecord functionality.
+
+On top of that, you also get tools for checking into which locales an attribute was translated to, as well as for checking overall translation coverage.
+
+
+## Requirements
+
+* ActiveRecord > 3.0.0.rc   # Tested with Rails 4.0.2, 3.2.18, 3.2.2
+* I18n
+
+## Installation
+
+To install Embedded_Localization, use:
+
+	  $ gem install embedded_localization
+
+
+## Translated Models
+
+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.
+
+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.
+
+### Example 1
+
+Let's assume you have a table for movie genres, and you want to translate the names and the descriptions of the genres.   Simply define your `Genre` model as follows:
+
+	  class Genre < ActiveRecord::Base
+		translates :name, :description
+	  end
+
+In the DB migration, you just need to add the `i18n` text field:
+
+	  class CreateGenres < ActiveRecord::Migration
+		def self.change
+		  create_table :genres do |t|
+			t.text   :i18n	# stores ALL the translated attributes; persisted as a Hash
+
+			t.timestamps
+		  end  
+		end
+	  end
+
+### Example 2
+
+Obviously you can't do SQL queries against tanslated fields which are stored in the `i18n` text field.
+To eliviate this problem, you can also define a normal DB attribute with the same name as your translated attribute, and it will store the value for your `I18n.default_locale`. 
+
+This way you can always do SQL queries against the values in the `I18n.default_locale`.
+
+To do this, using the same model as in example 1, you can modify your migration as follows:
+
+	  class CreateGenres < ActiveRecord::Migration
+		def self.change
+		  create_table :genres do |t|
+			t.text   :i18n	# stores the translated attributes; persisted as a Hash
+
+            t.string :name  # allows us to do SQL queries
+            
+			t.timestamps
+		  end  
+		end
+	  end
+
+# Usage
+
+In your code you can modify the values of your translated attributes in two ways.
+
+## Using Setters / Getters
+
+Using the built-in getter/setter methods you can set the values for any locale directly, even though 
+you are using your own locale.
+
+	  I18n.locale = :en
+	  g = Genre.first
+	  g.name = 'science fiction' 
+	  	  
+	  # even though you are using the :en locale, you can still set the values for other locales:
+	  
+	  g.set_localized_attribute( :name, :jp, "サイエンスフィクション" )
+	  g.set_localized_attribute( :name, :ko, "공상 과학 소설" )
+	  
+	  g.name       # => 'science fiction'
+	  g.name(:jp)  # => "サイエンスフィクション"
+	  g.name(:ko)  # => "공상 과학 소설"
+	  
+	  g.get_localized_attribute( :name, :jp )  # => "サイエンスフィクション"
+	  g.get_localized_attribute( :name, :ko )  # => "공상 과학 소설"
+	 
+## Tweaking `I18n.locale`
+
+By manipulating the `I18n.locale`. This is what happens if you have user's with different locales entering values into a database.
+
+   The controller is just assigning the new value via `name=` , but `embedded_localization` gem takes care of storing it for the correct given locale.
+
+	  I18n.locale = :en
+	  g = Genre.first
+	  g.name  # => 'science fiction'
+	  
+	  I18n.locale = :jp
+	  g.name = "サイエンスフィクション"
+	  
+	  I18n.locale = :ko
+	  g.name = "공상 과학 소설"
+	  g.name  # => "공상 과학 소설"
+	  
+	  I18n.locale = :jp
+	  g.name  # => "サイエンスフィクション"
+	  	  
+	  I18n.locale = :en  # MAKE SURE to switch back to your default locale if you tweak it
+	  
+	 
+## SQL Queries against Translated Fields
+
+Old `embedded_localization` implementations < 0.2.0 had the drawback that you can not do SQL queries on translated attributes.
+
+To eliminate this limitation, you can now define any translated attribute as a first-class database column in your migration. 
+
+If you define a translated attribute as a column, `embedded_localization` will store the attribute value for I18n.default_locale in that column, so you can search for it. 
+
+After defining the column, and running the migration, you need to populate the column initially. It will auto-update every time you write while you are using I18n.default_locale .
+
+See also Example 2 above. 
+
+	  I18n.locale = :en
+	  g = Genre.first
+	  g.name = 'science fiction'   # in Example 2 this will be stored in the DB column :name as well
+	  ...
+	  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.
+
+
+## Data Migration
+
+
+Existing data can be migrated from an existing (not-translated) column, into a translated column with the same name as follows:
+
+	Genre.record_timestamps = false   # to not modify your existing timestamps
+	Genre.all.each do |g|
+	  g.name = g.name   # the right-hand-side fetches the translation from the i18n attribute hash
+	  g.save			# saves the :name attribute without updating the updated_at timestamp
+	end
+	Genre.record_timestamps = true
+
+## 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`
+
+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)
+
+
+		config.i18n.fallbacks = true # falls back to I18n.default_locale
+
+
+By default, `embedded_localization` will only use fallbacks when the translation value for the item you've requested is `nil`.
+
+
+		class Genre < ActiveRecord::Base
+		  translates :name, :description # , :fallbacks => true
+		end
+
+		I18n.locale = :en
+		g = Genre.first
+		g.name  # => 'science fiction'
+
+		I18n.locale = :jp
+		g.name  # => "サイエンスフィクション"
+
+		I18n.locale = :de
+		g.name  # => nil
+
+		I18n.fallbacks = true
+		I18n.locale = :de
+		g.name  # => 'science fiction'
+
+## 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.
+
+### Class Methods
+
+Each class which uses `embedded_localization` will have these additional methods defined:
+
+* Klass.translated_attributes
+* Klass.translated?
+* Klass.fallbacks?
+
+e.g.:
+
+     Genre.translated_attributes # => [:name,:description]
+     Genre.translated?  # => true
+     Genre.fallbacks?  # => false
+
+
+### Instance Methods
+
+Each model instance of a class which uses `embedded_localization` will have these additional features:
+
+  * on-the-fly translations, via `g.name(:locale)`
+  * list of translated locales
+  * list of translated attributes
+  * hash of translation coverage for a given record's attributes or a particular attribute
+  * hash of missing translations for a given record's attributes or a particular attribute
+  * directly setting and getting attribute values for a given locale; without having to change `I18n.locale`
+  
+e.g.:
+
+	g = Genre.where(:name => "science fiction").first
+	
+	# check if an attribute is translated:
+	g.translated?(:name) # => true
+	
+	# which attributes are translated?
+	g.translated_attributes   # => [:description, :name]
+	
+	# check for which locales we have values: (spanning all translated fields)
+	g.translated_locales  # => [:en]
+
+	g.set_localized_attribute(:description, :de, "Ich liebe Science Fiction Filme")
+
+    # check again for which locales we have values: (spanning all translated fields)
+    g.translated_locales  # => [:en, :de]
+
+	# show details for which locales the attributes have values for:
+    #   for all attributes:
+	g.translation_coverage  # => {:name=>[:en], :description=>[:de]}
+	
+	#   for a specific attribute:	
+	g.translation_coverage(:name) # => [:en]
+	g.translation_coverage(:description)  # => [:de]
+
+	# show where translations are missing:
+    #   for all attributes:	
+	g.translation_missing   # => {:description=>[:en], :name=>[:de]}
+
+	#   for a specific attribute:
+	g.translation_missing(:name)  # => [:de]
+	g.translation_missing(:description)  # => [:en]
+
+
+	
+
+#### translated_locales vs translation_coverage
+
+##### translated_locales
+
+`translated_locales` lists the super-set of all locales, including the default locale, even if there is no value set for a specific attribute.
+For a new empty record, this will report `I18n.default_locale`.
+
+`translated_locales` reports which translations / languages are possible.
+
+##### translation_coverage
+
+`translation_coverage` only lists locales for which a non-nil value is set.
+For a new empty record, this will be empty.
+
+`translation_coverage` reports for which languages translations exist (actual values exist).
+
+##### Example
+
+	   I18n.locale = :jp
+	   g = Genre.first
+	   g.name  # => "サイエンスフィクション"
+	
+	   g.name(:en)  # => 'science fiction'
+	   g.name(:ko)  # => "공상 과학 소설"
+	   g.name(:de)  # => nil
+	
+	   g.translated_locales  # => [:en,:jp,:ko]
+	   g.translated_attributes # => [:name,:description]
+	   g.translated?  # => true
+	
+	   g.translation_coverage
+	   # => {"name"=>["en", "ko", "jp"] , "description"=>["en", "de", "fr", "ko", "jp", "es"]}
+	
+	   g.translation_coverage(:name)
+	   # => {"name"=>["en", "ko", "jp"]}
+	
+	   g.translation_missing
+	   # => {"name"=>["de", "fr", "es"]}
+	
+	   g.translation_missing(:display)
+	   # => {}     # this indicates that there are no missing translations for the :display attribute
+	
+	   g.get_localized_attribute(:name, :de)
+	   # => nil
+	
+	   g.set_localized_attribute(:name, :de, "Science-Fiction")
+	   # => "Science-Fiction"
+
+## Motivation
+
+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 globalization3 requires.  A second requirement was to allow SQL queries of the fields using the default locale.
+
+The advantage of EmbeddedLocalization is that it does not need extra tables, and therefore no joins or additional table lookups to get to the translated data.
+
+If your requirements are different, my approach might not work for you. In that case, I recommend to look at the alternative solutions listed below.
+
+## Changes
+
+### 1.1.0 (2014-01-12)
+* adding more rspec tests.
+* improving documentation and README
+
+### 1.0.0 (2014-01-11)
+* adding rspec tests.
+* fixing issue #6: translated fields for new records were not nil
+* fixing issue #7: translation_missing for new records is breaking
+
+
+### 0.2.5 (2013-11-02)
+* adding MIT and GPL-2 licenses to gem-spec file; contact me if you need another license
+
+### 0.2.4 (2012-03-02)
+* Issue #5 : bugfix for attr_writer
+
+### 0.2.3 (2012-03-02)
+* Issue #4 : bugfix for attr_writer - no longer updates attributes if value didn't change => timestamps don't change in that case
+
+### 0.2.2 (2012-02-06)
+* bugfix for attr_writer
+
+### 0.2.1 (2012-01-31)
+* bugfix for serialized i18n attribute
+
+### 0.2.0 (2012-01-31)
+* added support for having DB columns for translated attributes, to enable SQL queries in `I18n.default_locale`
+
+### 0.1.4 (2012-01-31)
+* fixed bug with dirty tracking of serialized i18n attribute
+* renamed #fallback? to #fallbacks?
+
+### 0.1.3 Initial Version (2012-01-27)
+* initial version
+
+
+## Alternative Solutions
+
+* [Mongoid](https://github.com/mongoid/mongoid) - awesome Ruby ORM for MongoDB, which includes in-table localization of attributes (mongoid >= 2.3.0)
+* [Globalize3](https://github.com/svenfuchs/globalize3) - is an awesome gem, but different approach with more tables in the schema.
+* [Veger's fork of Globalize2](http://github.com/veger/globalize2) - uses default AR schema for the default locale, delegates to the translations table for other locales only
+* [TranslatableColumns](http://github.com/iain/translatable_columns) - have multiple languages of the same attribute in a model (Iain Hecker)
+* [localized_record](http://github.com/glennpow/localized_record) - allows records to have localized attributes without any modifications to the database (Glenn Powell)
+* [model_translations](http://github.com/janne/model_translations) - Minimal implementation of Globalize2 style model translations (Jan Andersson)
+
+## Related Solutions
+
+* [globalize2_versioning](http://github.com/joshmh/globalize2_versioning) - acts_as_versioned style versioning for globalize2 (Joshua Harvey)
+* [i18n_multi_locales_validations](http://github.com/ZenCocoon/i18n_multi_locales_validations) - multi-locales attributes validations to validates attributes from globalize2 translations models (Sébastien Grosjean)
+* [globalize2 Demo App](http://github.com/svenfuchs/globalize2-demo) - demo application for globalize2 (Sven Fuchs)
+* [migrate_from_globalize1](http://gist.github.com/120867) - migrate model translations from Globalize1 to globalize2 (Tomasz Stachewicz)
+* [easy_globalize2_accessors](http://github.com/astropanic/easy_globalize2_accessors) - easily access (read and write) globalize2-translated fields (astropanic, Tomasz Stachewicz)
+* [globalize2-easy-translate](http://github.com/bsamman/globalize2-easy-translate) - adds methods to easily access or set translated attributes to your model (bsamman)
+* [batch_translations](http://github.com/alvarezrilla/batch_translations) - allow saving multiple globalize2 translations in the same request (Jose Alvarez Rilla)
+
+
+
+
+

data/embedded_localization.gemspec

@@ -23,7 +23,7 @@ Gem::Specification.new do |s|
   s.licenses = ['MIT','GPL-2']
   # specify any dependencies here; for example:
   s.add_development_dependency "rspec"
-  s.add_development_dependency "activerecord", "~> 3.2.0"
+  s.add_development_dependency "activerecord", "~> 4.0.0"
   s.add_development_dependency "i18n"
   s.add_development_dependency "sqlite3"
   # s.add_runtime_dependency "rest-client"

data/lib/embedded_localization/version.rb

@@ -1,3 +1,3 @@
 module EmbeddedLocalization
-  VERSION = '1.0.0'
+  VERSION = '1.1.0'
 end

data/spec/embedded_localization/native_column_spec.rb

@@ -8,132 +8,177 @@ I18n.locale = :en
 
 describe 'model has translated field with attribute of that same name' do
   let(:movie){ Movie.new }
-  let(:title_en){ "Blade Runner" }
-  let(:title_ru){'аЕЦСЫХИ ОН КЕГБХЧ'}
-  let(:title_tr){"Ölüm takibi"}
-  let(:title_de){"Der Blade Runner"}
-  let(:blade_runner){ Movie.new(:title => title_en) }
-
-  it 'reports it translates' do
-    Movie.translates?.should be_true
-  end
-
-  it 'correctly reports the list of translated_attributes' do
-    Movie.translated_attributes.sort.should eq [:description, :title]
-  end
-
-  it 'correctly reports the list of translated_attribute_names' do
-    Movie.translated_attribute_names.sort.should eq [:description, :title]
-  end
-
-  it 'correcty shows the translated attribute as translated' do
-    Movie.translated?(:title).should be_true
-    Movie.translated?(:description).should be_true
-  end
-
-  it 'correcty shows not translated attribute' do
-    Movie.translated?(:other).should be_false
-  end
-
-  it 'correctly reports translated_locales for new record' do
-    movie.translated_locales.should eq [I18n.default_locale]
-  end
-
-  it 'correctly reports translation_missing for new record' do
-    movie.translation_missing.should be_true
-  end
 
-  it 'creates the accessor methods' do
-    movie.methods.should include(:title)
-    movie.methods.should include(:title=)
-    movie.methods.should include(:description)
-    movie.methods.should include(:description=)
-  end
 
-  it 'correctly reports translated field for new record for default locale' do
-    movie.title.should be_nil
-    movie.description.should be_nil
-    movie.description( I18n.default_locale ).should be_nil
-  end
+  describe "basic things that need to work" do
 
-  it 'correctly reports translated field for new record for other locale' do
-    movie.title(:ko).should be_nil
-    movie.description(:de).should be_nil
-  end
+    it 'reports it translates' do
+      Movie.translates?.should be_true
+    end
 
-  it 'correctly reports translation_coverage for new record' do
-    movie.translation_coverage.should eq Hash.new
-  end
+    it 'correctly reports the list of translated_attributes' do
+      Movie.translated_attributes.sort.should eq [:description, :title]
+    end
 
-  it 'correctly reports translation_goverate for attributes of new record' do
-    movie.translation_coverage(:title).should eq []
-    movie.translation_coverage(:description).should eq []
-  end
+    it 'correctly reports the list of translated_attribute_names' do
+      Movie.translated_attribute_names.sort.should eq [:description, :title]
+    end
 
-  it 'translated_coverage returns nil for not-translated attributes' do
-    movie.translation_coverage(:other).should be_nil
-  end
+    it 'correcty shows the translated attribute as translated' do
+      Movie.translated?(:title).should be_true
+      Movie.translated?(:description).should be_true
+    end
 
-  it 'correctly reports translation_missing for new record' do
-    movie.translation_missing.should == {:description=>[:en], :title=>[:en]}
-    movie.translation_missing(:title).should eq [:en]
-    movie.translation_missing(:description).should eq [:en]
+    it 'correcty shows not translated attribute' do
+      Movie.translated?(:other).should be_false
+    end
   end
 
-  # when setting all fields in the default locale's languange:
-  it 'correctly reports translation_missing for updated record' do
-    movie.title = title_en
-    movie.description = "an awesome movie"
-    movie.save
-    movie.translation_missing.should eq Hash.new
-    movie.translation_missing(:title).should eq nil
-    movie.translation_missing(:description).should eq nil
-  end
+  describe "new DB records" do
 
-  it 'correctly reports translated_coverage for updated record' do
-    movie.title = title_en
-    movie.description = "an awesome movie"
-    movie.save
-    movie.translation_coverage.should == {:title=>[:en], :description=>[:en]}
-    movie.translation_coverage(:title).should eq [:en]
-    movie.translation_coverage(:description).should eq [:en]
-  end
-
-  # when setting all fields in additional languanges:
-  it 'correctly reports values, translation_coverage, translation_missing for updated record' do
-    movie.title = title_en
-    movie.description = "an awesome movie"
-    I18n.locale = :ru
-    movie.title = title_ru
-    movie.set_localized_attribute(:title , :tr, title_tr)
-    I18n.locale = :de
-    movie.description = "ein grossartiger Film"
-    I18n.locale = I18n.default_locale   # MAKE SURE you switch back to your default
-    movie.save
-    movie.reload
-    movie.title(:en).should eq title_en
-    movie.title(:tr).should eq title_tr
-    movie.get_localized_attribute(:title, :ru).should eq title_ru
-
-    # what values are actually present
-    movie.translation_coverage.should == {:title=>[:en, :ru, :tr], :description=>[:en, :de]}
-    movie.translation_coverage(:title).should eq [:en,:ru,:tr]
-    movie.translation_coverage(:description).should eq [:en,:de]
-
-    # what values are missing
-    movie.translation_missing.should == {:description=>[:ru, :tr], :title=>[:de]}
-    movie.translation_missing(:title).should eq [:de]
-    movie.translation_missing(:description).should eq [:ru,:tr]
-  end
+    it 'correctly reports translated_locales for new record' do
+      movie.translated_locales.should eq [I18n.default_locale]
+    end
+
+    it 'correctly reports translation_missing for new record' do
+      movie.translation_missing.should be_true
+    end
+
+    it 'creates the accessor methods' do
+      movie.methods.should include(:title)
+      movie.methods.should include(:title=)
+      movie.methods.should include(:description)
+      movie.methods.should include(:description=)
+    end
+
+    it 'correctly reports translated field for new record for default locale' do
+      movie.title.should be_nil
+      movie.description.should be_nil
+      movie.description( I18n.default_locale ).should be_nil
+    end
+
+    it 'correctly reports translated field for new record for other locale' do
+      movie.title(:ko).should be_nil
+      movie.description(:de).should be_nil
+    end
+
+    it 'correctly reports translation_coverage for new record' do
+      movie.translation_coverage.should eq Hash.new
+    end
+
+    it 'correctly reports translation_goverate for attributes of new record' do
+      movie.translation_coverage(:title).should eq []
+      movie.translation_coverage(:description).should eq []
+    end
+
+    it 'translated_coverage returns nil for not-translated attributes' do
+      movie.translation_coverage(:other).should be_nil
+    end
+
+    it 'correctly reports translation_missing for new record' do
+      movie.translation_missing.should == {:description=>[:en], :title=>[:en]}
+      movie.translation_missing(:title).should eq [:en]
+      movie.translation_missing(:description).should eq [:en]
+    end
+  end
+
+
+  describe "DB record with pre-set fields" do
+    let(:title_en){ "Blade Runner" }
+    let(:blade_runner){ Movie.new(:title => title_en) }
+
+    it 'correctly shows the attribute for new record' do
+      blade_runner.title.should eq title_en
+    end
+  end
+
+
+  describe "updated DB record" do
+    let(:title_en){ "Blade Runner" }
+    let(:title_ru){'аЕЦСЫХИ ОН КЕГБХЧ'}
+    let(:title_tr){"Ölüm takibi"}
+    let(:title_de){"Der Blade Runner"}
+    let(:blade_runner){ Movie.new(:title => title_en) }
+
+    describe 'updating just default locale' do
+
+      before :each do
+        movie.title = title_en
+        movie.description = "an awesome movie"
+        movie.save
+        movie.reload
+      end
+
+      # when setting all fields in the default locale's languange:
+      it 'correctly reports translation_missing for updated record' do
+        movie.translation_missing.should eq Hash.new
+      end
+
+      it 'correctly reports translation_missing for attributes' do
+        movie.translation_missing(:title).should eq nil
+        movie.translation_missing(:description).should eq nil
+      end
+
+      it 'correctly reports translated_coverage for updated record' do
+        movie.translation_coverage.should == {:title=>[:en], :description=>[:en]}
+      end
+
+      it 'correctly reports translated_coverage for attributes' do
+        movie.translation_coverage(:title).should eq [:en]
+        movie.translation_coverage(:description).should eq [:en]
+      end
+    end
+
+    describe 'updating other locales' do
+      before :each do
+        movie.title = title_en
+        movie.description = "an awesome movie"
+        I18n.locale = :ru
+        movie.title = title_ru
+        movie.set_localized_attribute(:title , :tr, title_tr)
+        I18n.locale = :de
+        movie.description = "ein grossartiger Film"
+        I18n.locale = I18n.default_locale   # MAKE SURE you switch back to your default loale if you tweak it
+        movie.save
+        movie.reload
+      end
+
+      it 'can assign the translated field' do
+        movie.title = title_en
+        movie.save.should be_true
+        movie.title.should eq  title_en
+        movie.title(:en).should eq  title_en
+      end
+
+      # when setting all fields in additional languanges:
+      it 'correctly reports values for updated record via attr(:locale)' do
+        movie.title(:tr).should eq title_tr
+      end
+
+      it 'correctly reports values for updated record via getter' do
+        movie.get_localized_attribute(:title, :ru).should eq title_ru
+      end
+
+      it 'correctly reports translation_coverage for updated record' do
+        # what values are actually present
+        movie.translation_coverage.should == {:title=>[:en, :ru, :tr], :description=>[:en, :de]}
+      end
+
+      it 'correctly reports translation_coverage for attributes' do
+        movie.translation_coverage(:title).should eq [:en,:ru,:tr]
+        movie.translation_coverage(:description).should eq [:en,:de]
+      end
+
+      it 'correctly reports translation_missing for updated record' do
+        # what values are missing
+        movie.translation_missing.should == {:description=>[:ru, :tr], :title=>[:de]}
+      end
+
+      it 'correctly reports translation_missing for attributes' do
+        movie.translation_missing(:title).should eq [:de]
+        movie.translation_missing(:description).should eq [:ru,:tr]
+      end
+    end
 
-  it 'can assign the translated field' do
-    movie.title = title_en
-    movie.save.should be_true
-    movie.title.should eq  title_en
   end
-
-  it 'correctly shows the attribute for new record' do
-    blade_runner.title.should eq title_en
-  end
-
 end

data/spec/embedded_localization/simple_model_spec.rb

@@ -9,131 +9,174 @@ I18n.locale = :en
 
 describe 'model has translated field without attribute of that same name' do
   let(:genre){ Genre.new }
-  let(:genre_name_en){"Science Fiction"}
-  let(:genre_name_jp){"サイエンスフィクション"}
-  let(:genre_name_ko){"공상 과학 소설"}
-  let(:scifi){ Genre.new(:name => genre_name_en) }
 
-  it 'reports it translates' do
-    Genre.translates?.should be_true
-  end
-
-  it 'correctly reports the list of translated_attributes' do
-    Genre.translated_attributes.sort.should eq [:description, :name]
-  end
-
-  it 'correctly reports the list of translated_attribute_names' do
-    Genre.translated_attribute_names.sort.should eq [:description, :name]
-  end
-
-  it 'correcty shows the translated attribute as translated' do
-    Genre.translated?(:name).should be_true
-    Genre.translated?(:description).should be_true
-  end
-
-  it 'correcty shows not translated attribute' do
-    Genre.translated?(:other).should be_false
-  end
-
-  it 'correctly reports translated_locales for new record' do
-    genre.translated_locales.should eq [I18n.default_locale]
-  end
+  describe "basic things that need to work" do
 
-  it 'correctly reports translation_missing for new record' do
-    genre.translation_missing.should be_true
-  end
+    it 'reports it translates' do
+      Genre.translates?.should be_true
+    end
 
-  it 'creates the accessor methods' do
-    genre.methods.should include(:name)
-    genre.methods.should include(:name=)
-    genre.methods.should include(:description)
-    genre.methods.should include(:description=)
-  end
+    it 'correctly reports the list of translated_attributes' do
+      Genre.translated_attributes.sort.should eq [:description, :name]
+    end
 
-  it 'correctly reports translated field for new record for default locale' do
-    genre.name.should be_nil
-    genre.description.should be_nil
-    genre.description( I18n.default_locale ).should be_nil
-  end
+    it 'correctly reports the list of translated_attribute_names' do
+      Genre.translated_attribute_names.sort.should eq [:description, :name]
+    end
 
-  it 'correctly reports translated field for new record for other locale' do
-    genre.name(:ko).should be_nil
-    genre.description(:de).should be_nil
-  end
+    it 'correcty shows the translated attribute as translated' do
+      Genre.translated?(:name).should be_true
+      Genre.translated?(:description).should be_true
+    end
 
-  it 'correctly reports translation_coverage for new record' do
-    genre.translation_coverage.should eq Hash.new
-  end
+    it 'correcty shows not translated attribute' do
+      Genre.translated?(:other).should be_false
+    end
+  end
+
+  describe "new DB records" do
+
+    it 'correctly reports translated_locales for new record' do
+      genre.translated_locales.should eq [I18n.default_locale]
+    end
+
+    it 'correctly reports translation_missing for new record' do
+      genre.translation_missing.should be_true
+    end
+
+    it 'creates the accessor methods' do
+      genre.methods.should include(:name)
+      genre.methods.should include(:name=)
+      genre.methods.should include(:description)
+      genre.methods.should include(:description=)
+    end
+
+    it 'correctly reports translated field for new record for default locale' do
+      genre.name.should be_nil
+      genre.description.should be_nil
+      genre.description( I18n.default_locale ).should be_nil
+    end
+
+    it 'correctly reports translated field for new record for other locale' do
+      genre.name(:ko).should be_nil
+      genre.description(:de).should be_nil
+    end
+
+    it 'correctly reports translation_coverage for new record' do
+      genre.translation_coverage.should eq Hash.new
+    end
+
+    it 'correctly reports translation_goverate for attributes of new record' do
+      genre.translation_coverage(:name).should eq []
+      genre.translation_coverage(:description).should eq []
+    end
+
+    it 'translated_coverage returns nil for not-translated attributes' do
+      genre.translation_coverage(:other).should be_nil
+    end
+
+    it 'correctly reports translation_missing for new record' do
+      genre.translation_missing.should == {:description=>[:en], :name=>[:en]}
+      genre.translation_missing(:name).should eq [:en]
+      genre.translation_missing(:description).should eq [:en]
+    end
+  end
+
+  describe "DB record with pre-set fields" do
+    let(:genre_name_en){"Science Fiction"}
+    let(:scifi){ Genre.new(:name => genre_name_en) }
+
+    it 'correctly shows the attribute for new record' do
+      scifi.name.should eq genre_name_en
+    end
+  end
+
+  describe "updated DB record" do
+    let(:genre_name_en){"Science Fiction"}
+    let(:genre_name_jp){"サイエンスフィクション"}
+    let(:genre_name_ko){"공상 과학 소설"}
+    let(:scifi){ Genre.new(:name => genre_name_en) }
+
+    describe 'updating just default locale' do
+
+      before :each do
+        genre.name = genre_name_en
+        genre.description = "an awesome genre"
+        genre.save
+        genre.reload
+      end
+
+       # when setting all fields in the default locale's languange:
+      it 'correctly reports translation_missing for updated record' do
+        genre.translation_missing.should eq Hash.new
+      end
+
+      it 'correctly reports translation_missing for attributes' do
+        genre.translation_missing(:name).should eq nil
+        genre.translation_missing(:description).should eq nil
+      end
+
+      it 'correctly reports translated_coverage for updated record' do
+        genre.translation_coverage.should == {:name=>[:en], :description=>[:en]}
+      end
+
+      it 'correctly reports translated_coverage for attributes' do
+        genre.translation_coverage(:name).should eq [:en]
+        genre.translation_coverage(:description).should eq [:en]
+      end
+    end
+
+
+    describe 'updating other locales' do
+      before :each do
+        genre.name = genre_name_en
+        genre.description = "an awesome genre"
+        I18n.locale = :jp
+        genre.name = genre_name_jp
+        genre.set_localized_attribute(:name, :ko, genre_name_ko)
+        I18n.locale = :de
+        genre.description = "ein grossartiges Genre"
+        I18n.locale = I18n.default_locale   # MAKE SURE you switch back to your default locale if you tweak it
+        genre.save
+        genre.reload
+      end
+
+      it 'can assign the translated field' do
+        genre.name = genre_name_en
+        genre.save.should be_true
+        genre.name.should eq  genre_name_en
+        genre.name(:en).should eq genre_name_en
+      end
+
+      # when setting all fields in additional languanges:
+      it 'correctly reports values for updated record via attr(:locale)' do
+        genre.name(:ko).should eq genre_name_ko
+      end
+
+      it 'correctly reports values for updated record via getter' do
+        genre.get_localized_attribute(:name, :jp).should eq genre_name_jp
+      end
+
+      it 'correctly reports translation_coverage for updated record' do
+          # what values are actually present
+        genre.translation_coverage.should == {:name=>[:en, :jp, :ko], :description=>[:en, :de]}
+      end
+
+      it 'correctly reports translation_coverage for attributes' do
+        genre.translation_coverage(:name).should eq [:en, :jp, :ko]
+        genre.translation_coverage(:description).should eq [:en,:de]
+      end
+
+      it 'correctly reports translation_missing for updated record' do
+         # what values are missing
+        genre.translation_missing.should == {:description=>[:jp, :ko], :name=>[:de]}
+      end
+
+      it 'correctly reports translation_missing for attributes' do
+        genre.translation_missing(:name).should eq [:de]
+        genre.translation_missing(:description).should eq [:jp, :ko]
+      end
+    end
 
-  it 'correctly reports translation_goverate for attributes of new record' do
-    genre.translation_coverage(:name).should eq []
-    genre.translation_coverage(:description).should eq []
   end
-
-  it 'translated_coverage returns nil for not-translated attributes' do
-    genre.translation_coverage(:other).should be_nil
-  end
-
-  it 'correctly reports translation_missing for new record' do
-    genre.translation_missing.should == {:description=>[:en], :name=>[:en]}
-    genre.translation_missing(:name).should eq [:en]
-    genre.translation_missing(:description).should eq [:en]
-  end
-
-   # when setting all fields in the default locale's languange:
-  it 'correctly reports translation_missing for updated record' do
-    genre.name = genre_name_en
-    genre.description = "an awesome genre"
-    genre.save
-    genre.translation_missing.should eq Hash.new
-    genre.translation_missing(:name).should eq nil
-    genre.translation_missing(:description).should eq nil
-  end
-
-  it 'correctly reports translated_coverage for updated record' do
-    genre.name = genre_name_en
-    genre.description = "an awesome genre"
-    genre.save
-    genre.translation_coverage.should == {:name=>[:en], :description=>[:en]}
-    genre.translation_coverage(:name).should eq [:en]
-    genre.translation_coverage(:description).should eq [:en]
-  end
-
-  # when setting all fields in additional languanges:
-  it 'correctly reports values, translation_coverage, translation_missing for updated record' do
-    genre.name = genre_name_en
-    genre.description = "an awesome genre"
-    I18n.locale = :jp
-    genre.name = genre_name_jp
-    genre.set_localized_attribute(:name, :ko, genre_name_ko)
-    I18n.locale = :de
-    genre.description = "ein grossartiger Film"
-    I18n.locale = I18n.default_locale   # MAKE SURE you switch back to your default
-    genre.save
-    genre.reload
-    genre.name(:en).should eq genre_name_en
-    genre.get_localized_attribute(:name, :jp).should eq genre_name_jp
-    genre.name(:ko).should eq genre_name_ko
-
-    # what values are actually present
-    genre.translation_coverage.should == {:name=>[:en, :jp, :ko], :description=>[:en, :de]}
-    genre.translation_coverage(:name).should eq [:en, :jp, :ko]
-    genre.translation_coverage(:description).should eq [:en,:de]
-
-    # what values are missing
-    genre.translation_missing.should == {:description=>[:jp, :ko], :name=>[:de]}
-    genre.translation_missing(:name).should eq [:de]
-    genre.translation_missing(:description).should eq [:jp, :ko]
-  end
-
-  it 'can assign the translated field' do
-    genre.name = genre_name_en
-    genre.save.should be_true
-    genre.name.should eq  genre_name_en
-  end
-
-  it 'correctly shows the attribute for new record' do
-    scifi.name.should eq genre_name_en
-  end
-
 end

data/spec/models.rb

@@ -1,9 +1,7 @@
 class Genre < ActiveRecord::Base
    translates :name, :description
-   attr_accessible :name, :description
 end
 
 class Movie < ActiveRecord::Base
    translates :title, :description
-   attr_accessible :title, :description
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: embedded_localization
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -34,7 +34,7 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: 3.2.0
+        version: 4.0.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -42,7 +42,7 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: 3.2.0
+        version: 4.0.0
 - !ruby/object:Gem::Dependency
   name: i18n
   requirement: !ruby/object:Gem::Requirement
@@ -85,8 +85,9 @@ extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
+- .travis.yml
 - Gemfile
-- README.textile
+- README.md
 - Rakefile
 - embedded_localization.gemspec
 - lib/embedded_localization.rb

data/README.textile

@@ -1,272 +0,0 @@
-h1. Embedded Localization
-
-Embedded_Localization is a Rails 3 localization gem, targeted at ActiveRecord 3. It is compatible with and builds on the new "I18n API in Ruby on Rails":http://guides.rubyonrails.org/i18n.html and adds model translations to ActiveRecord.
-
-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.
-
-Model translations with Embedded_Localization use default ActiveRecord features and do not limit any ActiveRecord functionality.
-
-
-h2. Requirements
-
-ActiveRecord > 3.0.0.rc
-I18n
-
-Tested with Rails 3.2.2 , 3.2.16
-
-h2. Installation
-
-To install Embedded_Localization, use:
-
-<pre><code>
-$ gem install embedded_localization
-
-</code></pre>
-
-h2. Model translations
-
-Model translations allow you to translate your models' attribute values. The attribute type needs to be string or text, and you need to generate the database fields as usual with ActiveRecord database migrations. e.g.:
-
-<font color='red'>Note for version <0.2.0:</font> do not define the attributes in the DB migration, but define one text field :i18n for each table which uses Embedded_Localization
-
-<pre><code>
-class Genre < ActiveRecord::Base
-  translates :name, :description
-end
-
-</code></pre>
-
-This allows you to translate the attributes :name and :description per locale:
-
-<pre><code>
-I18n.locale = :en
-g = Genre.first
-g.name  # => 'science fiction'
-
-I18n.locale = :jp
-g.name  # => "サイエンスフィクション"
-
-I18n.locale = :ko
-g.name  # => "공상 과학 소설"
-</code></pre>
-
-No extra tables needed for this!
-
-h3. Rails 3.x
-
-<pre><code>
-class CreateGenres < ActiveRecord::Migration
-  def self.up
-    create_table :genres do |t|
-      t.text   :i18n    # stores the translated attributes; persisted as a Hash
-
-# optional:
-#      t.string :name    # you CAN define :name as a real column in your DB (but you don't have to)
-#                        # If you define it, it will store the I18n.default_locale translation for SQL lookups
-#                        # You can do this for any of the translated attributes.
-      t.timestamps
-    end
-    # -- example for a data migration: ---
-    # Genre.record_timestamps = false
-    # Genre.all.each do |g|
-    #   g.name = g.name   # the right-hand-side fetches the translation from the i18n attribute hash
-    #   g.save            # saves the :name attribute without updating the updated_at timestamp
-    # end
-    # Genre.record_timestamps = true
-    # ------------------------------------
-  end
-  def self.down
-    drop_table :posts
-  end
-end
-</code></pre>
-
-h4. NOTE:
-
-EmbeddedLocalization implementations < 0.2.0 had the drawback that you can not do SQL queries on translated attributes.
-
-To eliminate this limitation, you can now define any translated attribute as a first-class database column in your migration. If you define a translated attribute as a column, EmbeddedLocalization will store the attribute value for I18n.default_locale in that column, so you can search for it. After defining the column, and running the migration, you need to populate the column initially. It will auto-update every time you write while you are using I18n.default_locale .
-e.g.:
-
-<pre><code>
-  g = Genre.where(:name => "science fiction")   # this only works if you define :name as a DB column, and populate it
-</pre></code>
-
-Note that the ActiveRecord model @Genre@ must already exist and have a @translates@ directive listing the translated fields.
-
-
-h2. 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@
-
-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)
-
-<pre><code>config.i18n.fallbacks = true # falls back to I18n.default_locale
-</code></pre>
-
-By default, Embedded_Localization will only use fallbacks when the translation value for the item you've requested is @nil@.
-
-<pre><code>
-class Genre < ActiveRecord::Base
-  translates :name, :description # , :fallbacks => true
-end
-
-I18n.locale = :en
-g = Genre.first
-g.name  # => 'science fiction'
-
-I18n.locale = :jp
-g.name  # => "サイエンスフィクション"
-
-I18n.locale = :de
-g.name  # => nil
-
-I18n.fallbacks = true
-I18n.locale = :de
-g.name  # => 'science fiction'
-
-</code></pre>
-
-
-h2. 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..
-
-h3. Class Methods
-
-Each class which uses Embedded_Localization will have these additional methods defined:
-<ul>
-  <li>Klass.translated_attributes
-  <li>Klass.translated?
-  <li>Klass.fallbacks?
-</ul>
-
-e.g.:
-
-<pre><code>
-   Genre.translated_attributes # => [:name,:description]
-   Genre.translated?  # => true
-   Genre.fallbacks?  # => false
-
-</code></pre>
-
-h3. Instance Methods
-
-Each model instance of a class which uses Embedded_Localization will have these additional features:
-<ul>
-  <li>on-the-fly translations, via <code>.name(:locale)</code>
-  <li>list of translated locales
-  <li>list of translated attributes
-  <li>hash of translation coverage for a given record's attributes or a particular attribute
-  <li>hash of missing translations for a given record's attributes or a particular attribute
-  <li>directly setting and getting attribute values for a given locale; without having to change <code>I18n.locale</code>
-</ul>
-
-Notes:
-
-<pre><code>translated_locales</code></pre> lists the super-set of all locales, including the default locale, even if there is no value set for a specific attribute.
-For a new empty record, this will report I18n.default_locale.
-
-translated_locales reports which translations / languages are possible.
-
-<pre><code>translation_coverage</code></pre> only lists locales for which a non-nil value is set.
-For a new empty record, this will be empty.
-
-translation_coverage reports for which languages translations exist (actual values exist).
-
-e.g.:
-
-<pre><code>
-   I18n.locale = :jp
-   g = Genre.first
-   g.name  # => "サイエンスフィクション"
-
-   g.name(:en)  # => 'science fiction'
-   g.name(:ko)  # => "공상 과학 소설"
-   g.name(:de)  # => nil
-
-   g.translated_locales  # => [:en,:jp,:ko]
-   g.translated_attributes # => [:name,:description]
-   g.translated?  # => true
-
-   g.translation_coverage
-   # => {"name"=>["en", "ko", "jp"] , "description"=>["en", "de", "fr", "ko", "jp", "es"]}
-
-   g.translation_coverage(:name)
-   # => {"name"=>["en", "ko", "jp"]}
-
-   g.translation_missing
-   # => {"name"=>["de", "fr", "es"]}
-
-   g.translation_missing(:display)
-   # => {}     # this indicates that there are no missing translations for the :display attribute
-
-   g.get_localized_attribute(:name, :de)
-   # => nil
-
-   g.set_localized_attribute(:name, :de, "Science-Fiction")
-   # => "Science-Fiction"
-
-</code></pre>
-
-h2. Motivation
-
-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 globalization3 requires.  A second requirement was to allow SQL queries of the fields using the default locale.
-
-The advantage of EmbeddedLocalization is that it does not need extra tables, and therefore no joins or additional table lookups to get to the translated data.
-
-If your requirements are different, my approach might not work for you. In that case, I recommend to look at the alternative solutions listed below.
-
-h2. Changes
-
-
-h3. 1.0.0 (2014-01-11)
-* adding rspec tests.
-* fixing issue #6: translated fields for new records were not nil
-* fixing issue #7: translation_missing for new records is breaking
-
-
-h3. 0.2.5 (2013-11-02)
-* adding MIT and GPL-2 licenses to gem-spec file; contact me if you need another license
-
-h3. 0.2.4 (2012-03-02)
-* Issue #5 : bugfix for attr_writer
-
-h3. 0.2.3 (2012-03-02)
-* Issue #4 : bugfix for attr_writer - no longer updates attributes if value didn't change => timestamps don't change in that case
-
-h3. 0.2.2 (2012-02-06)
-* bugfix for attr_writer
-
-h3. 0.2.1 (2012-01-31)
-* bugfix for serialized i18n attribute
-
-h3. 0.2.0 (2012-01-31)
-* added support for having DB columns for translated attributes, to enable SQL queries in I18n.default_locale
-
-h3. 0.1.4 (2012-01-31)
-* fixed bug with dirty tracking of serialized i18n attribute
-* renamed #fallback? to #fallbacks?
-
-h3. 0.1.3 Initial Version (2012-01-27)
-
-
-h2. Alternative Solutions
-
-* "Mongoid":https://github.com/mongoid/mongoid - awesome Ruby ORM for MongoDB, which includes in-table localization of attributes (mongoid >= 2.3.0)
-* "Globalize3":https://github.com/svenfuchs/globalize3 - is an awesome gem, but different approach with more tables in the schema.
-* "Veger's fork":http://github.com/veger/globalize2 - uses default AR schema for the default locale, delegates to the translations table for other locales only
-* "TranslatableColumns":http://github.com/iain/translatable_columns - have multiple languages of the same attribute in a model (Iain Hecker)
-* "localized_record":http://github.com/glennpow/localized_record - allows records to have localized attributes without any modifications to the database (Glenn Powell)
-* "model_translations":http://github.com/janne/model_translations - Minimal implementation of Globalize2 style model translations (Jan Andersson)
-
-h2. Related solutions
-
-* "globalize2_versioning":http://github.com/joshmh/globalize2_versioning - acts_as_versioned style versioning for globalize2 (Joshua Harvey)
-* "i18n_multi_locales_validations":http://github.com/ZenCocoon/i18n_multi_locales_validations - multi-locales attributes validations to validates attributes from globalize2 translations models (Sébastien Grosjean)
-* "globalize2 Demo App":http://github.com/svenfuchs/globalize2-demo - demo application for globalize2 (Sven Fuchs)</li>
-* "migrate_from_globalize1":http://gist.github.com/120867 - migrate model translations from Globalize1 to globalize2 (Tomasz Stachewicz)</li>
-* "easy_globalize2_accessors":http://github.com/astropanic/easy_globalize2_accessors - easily access (read and write) globalize2-translated fields (astropanic, Tomasz Stachewicz)</li>
-* "globalize2-easy-translate":http://github.com/bsamman/globalize2-easy-translate - adds methods to easily access or set translated attributes to your model (bsamman)</li>
-* "batch_translations":http://github.com/alvarezrilla/batch_translations - allow saving multiple globalize2 translations in the same request (Jose Alvarez Rilla)</li>
-