embedded_localization 0.1.3 → 0.1.4

data/README.textile

@@ -50,25 +50,6 @@ g.name  # => "공상 과학 소설"
 
 No extra tables needed for this!
 
-h3. Rails 3.0
-
-<pre><code>
-class CreateGenres < ActiveRecord::Migration
-  def self.up
-    create_table :genres do |t|
-      t.string :name
-      t.text   :description
-      t.timestamps
-    end
-  end
-  def self.down
-    drop_table :posts
-  end
-end
-</code></pre>
-
-Note that the ActiveRecord model @Genre@ must already exist and have a @translates@ directive listing the translated fields.
-
 h3. Rails 3.0 + Embedded_Localization version < 0.2.0
 
 <pre><code>
@@ -87,19 +68,23 @@ end
 
 Please note, if you use Embedded_Localization with version < 0.2.0, that you should not define the translated attributes in the migrations -- instead define one text attribute with the name :i18n -- this will change in version 0.2.0
 
+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.
+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</code></pre>
+<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
+  translates :name, :description # , :fallbacks => true
 end
 
 I18n.locale = :en
@@ -129,7 +114,7 @@ Each class which uses Embedded_Localization will have these additional methods d
 <ul>
   <li>Klass.translated_attributes
   <li>Klass.translated?
-  <li>Klass.fallback?
+  <li>Klass.fallbacks?
 </ul> 
 
 e.g.: 
@@ -137,7 +122,7 @@ e.g.:
 <pre><code>
    Genre.translated_attributes # => [:name,:description]
    Genre.translated?  # => true
-   Genre.fallback?  # => false
+   Genre.fallbacks?  # => false
 
 </code></pre>
 
@@ -188,10 +173,23 @@ e.g.:
 
 </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
 
-This is the initial version.
+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
 

data/embedded_localization.gemspec

@@ -9,9 +9,7 @@ Gem::Specification.new do |s|
   s.email       = ["tilo.sloboda@gmail.com"]
   s.homepage    = "http://www.unixgods.org/~tilo/Ruby/embedded_localization"
   s.summary     = %q{Rails I18n: library for embedded ActiveRecord 3 model/data translation}
-  s.description = %q{Rails I18n: Embedded_Localization for ActiveRecord 3 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!}
+  s.description = %q{Rails I18n: Embedded_Localization for ActiveRecord 3 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!}
 
 #  s.rubyforge_project = "embedded_localization"
   s.rubyforge_project = "[none]"

data/lib/embedded_localization/active_record/act_macro.rb

@@ -4,8 +4,12 @@ module EmbeddedLocalization
       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.6.0/lib/i18n/backend/fallbacks.rb  
+        # i18n-0.6.0/lib/i18n/locale/fallbacks.rb
+
+        # options[:fallbacks] => true or false # not used at this time
         options = attr_names.extract_options!
-        # options[:fallback] => true or false
 
         class_attribute :translated_attribute_names, :translation_options
         self.translated_attribute_names = attr_names.map(&:to_sym).sort.uniq
@@ -14,10 +18,17 @@ 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   # 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
@@ -30,32 +41,40 @@ module EmbeddedLocalization
         #   - 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
         #   - 
+        #+
 
         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)
-                return self.i18n[ I18n.default_locale ][attr_name] if ActsAsI18n.fallback?
-                return nil
+              if self.i18n.has_key?(locale)
+                self.i18n[ locale ][attr_name]
+              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
-              self.i18n[ locale ][attr_name]
             end
 
-          # define the setter method
+            # define the setter method
+            #
             define_method(attr_name.to_s+ '=') do |new_translation|
+              self.i18n_will_change!     # for ActiveModel Dirty tracking
               self.i18n[I18n.locale] ||= HashWithIndifferentAccess.new
               self.i18n[I18n.locale][attr_name] = new_translation
             end
           end
         end
       end
-
+      
       def translates?
         included_modules.include?(InstanceMethods)
       end

data/lib/embedded_localization/active_record/class_methods.rb

@@ -16,9 +16,18 @@ module EmbeddedLocalization
         translated_attribute_names.include?(name.to_sym)
       end
 
-      def fallback?
-        translation_options[:fallback]
+      # # 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
+
+      #-
+      # # fetch the fallbacks from the i18n backend
+      # def fallbacks
+      #   fallbacks? ? I18n.fallbacks : nil
+      # end
+
     end
   end
 end

data/lib/embedded_localization/active_record/instance_methods.rb

@@ -2,19 +2,22 @@ module EmbeddedLocalization
   module ActiveRecord
     module InstanceMethods
 
-      # maybe a better way to do this is to use a special class LocalizedAttribute < HashWithIndifferentAccess
-      # and use the [] , []= operators... hmm... thinking...
-
+      # we only support fallbacks to I18n.default_locale for now
+      #
       def get_localized_attribute(attr_name, locale)
-        if ! self.i18n.has_key?(locale)
-          return self.i18n[ I18n.default_locale ][attr_name] if ActsAsI18n.fallback?
-          return nil
-        else
+        if self.i18n.has_key?(locale)
           self.i18n[locale][attr_name]
+        else
+          if self.class.fallbacks? && self.i18n[ I18n.default_locale ]
+            return self.i18n[ I18n.default_locale ][attr_name] 
+          else
+            return nil
+          end
         end
       end
-        
+      
       def set_localized_attribute(attr_name, locale, new_translation)
+        self.i18n_will_change!     # for ActiveModel Dirty tracking
         self.i18n[locale] ||= HashWithIndifferentAccess.new
         self.i18n[locale][attr_name] = new_translation
       end

data/lib/embedded_localization/version.rb

@@ -1,3 +1,3 @@
 module EmbeddedLocalization
-  VERSION = '0.1.3'
+  VERSION = '0.1.4'
 end

data/lib/embedded_localization.rb

@@ -3,15 +3,30 @@ require 'extensions/hash'
 
 module EmbeddedLocalization
   autoload :ActiveRecord, 'embedded_localization/active_record'
-
-  class << self
-    class_attribute :fallback
-
-    def fallback?
-      fallback == true
-    end
-  end
 end
 
 # we're assuming for now only to be used with ActiveRecord 3, which is auto-required above
 ActiveRecord::Base.extend(EmbeddedLocalization::ActiveRecord::ActMacro)
+
+#-
+# ------------------------------------------------------------------------------------------------------
+# probably a good idea to keep our own implementation of fallbacks,
+# because we only want to fallback to I18n.default_locale .. nothing more complicated for now.
+# ------------------------------------------------------------------------------------------------------
+#
+# Fallbacks:  https://github.com/svenfuchs/i18n/wiki/Fallbacks
+#
+# The problem is that the I18n backends are meant for static strings in the views, helpers, etc.; not for model data.
+# Switching on the current I18n backend's fallbacks will allow us to use that backend's mappings from one locale to the fallbacks, 
+# but we still need to search for the translated module data in our serialized i18n attribute hash ourselves.
+
+# to enable I18n fallbacks:
+# require "i18n/backend/fallbacks" 
+# I18n.backend.class.send(:include, I18n::Backend::Fallbacks)
+
+# Thread.current[:i18n_config].backend
+# ?? I18n.fallbacks.map('es' => 'en') ?? doesn't seem to work as expected..
+
+# not as general:
+# I18n::Backend::Simple.send(:include, I18n::Backend::Fallbacks)
+

metadata

@@ -2,7 +2,7 @@
 name: embedded_localization
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors: 
 - Tilo Sloboda
@@ -10,13 +10,10 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2012-01-27 00:00:00 Z
+date: 2012-01-31 00:00:00 Z
 dependencies: []
 
-description: |-
-  Rails I18n: Embedded_Localization for ActiveRecord 3 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!
+description: "Rails I18n: Embedded_Localization for ActiveRecord 3 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!"
 email: 
 - tilo.sloboda@gmail.com
 executables: []