embedded_localization 0.1.3

data/.gitignore

@@ -0,0 +1,6 @@
+*~
+*.bak
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in embedded_localization.gemspec
+gemspec

data/README.textile

@@ -0,0 +1,214 @@
+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
+
+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.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>
+class CreateGenres < ActiveRecord::Migration
+  def self.up
+    create_table :genres do |t|
+      t.text   :i18n    # this will be deprecated in 0.2.0
+      t.timestamps
+    end
+  end
+  def self.down
+    drop_table :posts
+  end
+end
+</code></pre>
+
+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
+
+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.
+
+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>
+
+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
+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.fallback?
+</ul> 
+
+e.g.: 
+
+<pre><code>
+   Genre.translated_attributes # => [:name,:description]
+   Genre.translated?  # => true
+   Genre.fallback?  # => 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>
+
+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. Changes
+
+This is the initial version.
+
+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>
+

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/embedded_localization.gemspec

@@ -0,0 +1,29 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "embedded_localization/version"
+
+Gem::Specification.new do |s|
+  s.name        = "embedded_localization"
+  s.version     = EmbeddedLocalization::VERSION
+  s.authors     = ["Tilo Sloboda"]
+  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.rubyforge_project = "embedded_localization"
+  s.rubyforge_project = "[none]"
+
+  # s.platform = Gem::Platform::RUBY
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  # specify any dependencies here; for example:
+  # s.add_development_dependency "rspec"
+  # s.add_runtime_dependency "rest-client"
+end

data/lib/embedded_localization.rb

@@ -0,0 +1,17 @@
+require "embedded_localization/version"
+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)

data/lib/embedded_localization/active_record.rb

@@ -0,0 +1,7 @@
+module EmbeddedLocalization
+  module ActiveRecord
+    autoload :ActMacro ,        'embedded_localization/active_record/act_macro'
+    autoload :ClassMethods ,    'embedded_localization/active_record/class_methods'
+    autoload :InstanceMethods , 'embedded_localization/active_record/instance_methods'
+  end
+end

data/lib/embedded_localization/active_record/act_macro.rb

@@ -0,0 +1,65 @@
+module EmbeddedLocalization
+  module ActiveRecord
+    module ActMacro
+      def translates(*attr_names)
+        return if translates?  # cludge to make sure we don't set this up twice..
+
+        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
+        self.translation_options        = options
+
+        include InstanceMethods
+        extend  ClassMethods
+
+        # if ActiveRecord::Base is in the parent-chain of the class where we are included into:
+        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:
+        #    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
+        #   - 
+
+        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
+              end
+              self.i18n[ locale ][attr_name]
+            end
+
+          # define the setter method
+            define_method(attr_name.to_s+ '=') do |new_translation|
+              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
+    end
+  end
+end
+

data/lib/embedded_localization/active_record/class_methods.rb

@@ -0,0 +1,24 @@
+module EmbeddedLocalization
+  module ActiveRecord
+    module ClassMethods
+
+      # Returns Array of Symbols for all attributes of this class, 
+      #   which have translations through acts_as_i18n.
+      # returns an Array of Symbols
+      def translated_attributes
+        translated_attribute_names
+      end
+
+      # Checks whether field with given name is translated field.
+      # Param String or Symbol
+      # Returns true or false
+      def translated?(name)
+        translated_attribute_names.include?(name.to_sym)
+      end
+
+      def fallback?
+        translation_options[:fallback]
+      end
+    end
+  end
+end

data/lib/embedded_localization/active_record/instance_methods.rb

@@ -0,0 +1,102 @@
+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...
+
+      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
+          self.i18n[locale][attr_name]
+        end
+      end
+        
+      def set_localized_attribute(attr_name, locale, new_translation)
+        self.i18n[locale] ||= HashWithIndifferentAccess.new
+        self.i18n[locale][attr_name] = new_translation
+      end
+
+      # Returns all locales used for translation of all documents of this class.
+      # returns an Array of Symbols
+      #
+      def translated_locales
+        self.i18n.keys
+      end
+      
+      # Returns Array of Symbols for all attributes of this class, 
+      #   which have translations through acts_as_i18n.
+      # returns an Array of Symbols
+      #
+      def translated_attributes
+        self.class.translated_attributes
+      end
+        
+      # Checks whether field with given name is translated field.
+      # Param String or Symbol
+      # Returns true or false
+      #
+      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
+      # Returns a Hash of all translated attributes, each with a Hash of the locales it has translations for
+      #
+      def translation_coverage( attribute = nil )
+        attrs = {}
+        self.i18n.each do |lang,hash|
+          hash.keys.each do |attr|
+            attrs[attr.to_sym] ||= []
+            attrs[attr.to_sym] << lang
+          end
+        end
+        if attribute.nil?
+          return attrs
+        else
+          return attrs[attribute.to_sym]
+        end
+      end
+
+      # Purpose: to quickly see if attribute translations are missing
+      # Returns a Hash of attributes, each with a Hash of the locales that are missing translations
+      # If an attribute has complete translation coverage, it will not be listed
+      # If the result is an empty Hash, then no attributes are missing translations
+      #
+      # Needs all the desired locales to be present in 'translated_locales' 
+      # e.g. each locale must be present in at least one of the translated attributes
+      #
+      def translation_missing( attribute = nil )
+        missing = {}
+        current_locales_used = translated_locales  # ... across all attributes
+
+        translated_attributes.each do |attr|
+          missing_locales = current_locales_used - translation_coverage(attr.to_sym)
+          if missing_locales.size > 0
+            missing[attr.to_sym] = missing_locales
+          end
+        end
+        if attribute.nil?
+          return missing
+        else
+          return missing[attribute.to_sym]
+        end
+      end
+
+      private
+      # initialized the serialized 'i18n' attribute with Hash of Hashes,
+      #   containing all pre-defined translated attributes with nil value
+      def initialize_i18n_hashes
+        self.i18n ||= HashWithIndifferentAccess.new
+        self.i18n[ I18n.locale ] ||= HashWithIndifferentAccess.new(Hash.zip(translated_attribute_names,[]))
+        if I18n.locale != I18n.default_locale
+          self.i18n[ I18n.default_locale ] ||= HashWithIndifferentAccess.new(Hash.zip(translated_attribute_names,[]))
+        end
+      end
+
+    end
+  end
+end

data/lib/embedded_localization/version.rb

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

data/lib/extensions/hash.rb

@@ -0,0 +1,7 @@
+class Hash
+  def self.zip(keys,values) # from Facets of Ruby library
+    h = {}
+    keys.size.times{ |i| h[ keys[i] ] = values[i] }
+    h
+  end
+end

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification 
+name: embedded_localization
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 0.1.3
+platform: ruby
+authors: 
+- Tilo Sloboda
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2012-01-27 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!
+email: 
+- tilo.sloboda@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- Gemfile
+- README.textile
+- Rakefile
+- embedded_localization.gemspec
+- lib/embedded_localization.rb
+- lib/embedded_localization/active_record.rb
+- lib/embedded_localization/active_record/act_macro.rb
+- lib/embedded_localization/active_record/class_methods.rb
+- lib/embedded_localization/active_record/instance_methods.rb
+- lib/embedded_localization/version.rb
+- lib/extensions/hash.rb
+homepage: http://www.unixgods.org/~tilo/Ruby/embedded_localization
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+requirements: []
+
+rubyforge_project: "[none]"
+rubygems_version: 1.8.13
+signing_key: 
+specification_version: 3
+summary: "Rails I18n: library for embedded ActiveRecord 3 model/data translation"
+test_files: []
+