dm-is-localizable 0.10.1

data/README.textile

@@ -0,0 +1,260 @@
+h1. dm-is-localizable
+
+Datamapper support for localization of (user entered) content in multilanguage applications
+
+h3. Schema
+
+* one xxx_translations table for every translatable resource
+* xxx_translations belongs_to the resource to translate
+* xxx_translations belongs_to a language
+* properties to be translated are defined in xxx_translations
+
+
+h4. Advantages
+
+  * Proper normalization and referential integrity
+  * Ease in adding a new language (add row to xxx_translations)
+  * Easy to query
+  * Columns keep their names
+
+
+h4. Disadvantages (not really if you think about it)
+
+  * One table for every resource that needs translations
+
+
+h3. Example definition of a localizable model
+
+Currently, you need to define a @Language@ model yourself, to get @dm-is-localizable@ started. However, this is reasonably easy! If you do a @rake install@ after you cloned the repo (I guess it won't work if you do a simple @gem install@), it will print out the code for language.rb and will tell you where to put it.
+
+<pre>
+<code>
+class Language
+
+  include DataMapper::Resource
+
+  # properties
+
+  property :id, Serial
+
+  property :code, String, :required => true, :unique => true, :unique_index => true
+  property :name, String, :required => true
+
+  # locale string like 'en-US'
+  validates_format :code, :with => /^[a-z]{2}-[A-Z]{2}$/
+
+
+  def self.[](code)
+    return nil if code.nil?
+    first :code => code.to_s.gsub('_', '-')
+  end
+
+end
+</code>
+</pre>
+
+Once you have this model in place, you can start defining your _localizable models_.
+
+<pre>
+<code>
+class Item
+
+  include DataMapper::Resource
+  
+  property :id, Serial
+  
+  is :localizable do        # same as is :localizable, :accept_nested_attributes => true do
+    property :name, String
+    property :desc, String
+  end
+  
+end
+</code>
+</pre>
+
+The above @Item@ model will define and thus be able to @DataMapper.auto_migrate!@ the @ItemTranslation@ model. The _naming convention_ used here is @"#{ClassToBeLocalized.name}Translation"@.
+
+Preliminary support for changing this is available by using the @:model@ option like so (note that this isn't specced yet).
+
+<pre>
+<code>
+DataMapper::Model.is :localizable, :model => 'ItemLocalization'
+</code>
+</pre>
+
+Furthermore, the above @Item@ will automatically have the following instance methods defined.
+
+<pre>
+<code>
+#item_translations_attributes
+#item_translations_attributes=
+
+# and handy aliases for the above
+
+#translations_attributes
+#translations_attributes=
+</code>
+</pre>
+
+These are generated by "dm-accepts_nested_attributes":http://github.com/snusnu/dm-accepts_nested_attributes and allow for easy manipulation of the localizable properties from say forms in a web application. For more information on working with nested attributes, have a look at the documentation at the "README":http://github.com/snusnu/dm-accepts_nested_attributes for "dm-accepts_nested_attributes":http://github.com/snusnu/dm-accepts_nested_attributes
+
+Of course you can turn this behavior off by specifying the @is :localizable, :accept_nested_attributes => false do .. end@
+
+The resulting model you get when calling @Item.is(:localizable)@ looks like this: 
+
+<pre>
+<code>
+class ItemTranslation
+
+  include DataMapper::Resource
+  
+  property :id,          Serial
+  
+  property :item_id,     Integer, :required => true, :unique_index => :unique_languages
+  property :language_id, Integer, :required => true, :unique_index => :unique_languages
+  
+  property :name,        String
+  property :desc,        String
+  
+  validates_is_unique :language_id, :scope => :item_id
+
+  belongs_to :item
+  belongs_to :language
+  
+end
+</code>
+</pre>
+
+Furthermore, the following API gets defined on the @Item@ class:
+
+<pre>
+<code>
+class Item
+
+  include DataMapper::Resource
+  
+  property :id, Serial
+  
+  is :localizable do
+    property :name, String
+    property :desc, String
+  end
+  
+  # ----------------------------
+  #   added by is :localizable
+  # ----------------------------
+  
+  has n, :item_translations
+  has n, :languages, :through => :item_translations
+  
+  # and a handy alias
+  alias :translations :item_translations
+  
+  # helper to get at ItemTranslation
+  class_inheritable_reader :translation_model
+  
+  # -------------------
+  #   class level API
+  # -------------------
+  
+  # list all available languages for Items
+  def self.available_languages
+    Language.all :id => translation_model.all.map { |t| t.language_id }.uniq
+  end
+  
+  # the number of all available languages for the localizable model
+  def self.nr_of_available_languages
+    available_languages.size
+  end
+  
+  # checks if all localizable resources are translated in all available languages
+  def self.translations_complete?
+    nr_of_available_languages * all.size == translation_model.all.size
+  end
+  
+  # returns a list of symbols reflecting all localizable property names of this resource
+  def localizable_properties
+    translation_model.properties.map do |p|
+      p.name
+    end.select do |p|
+      # exclude properties that are'nt localizable
+      p != :id && p != :language_id && p != Extlib::Inflection.foreign_key(self.name).to_sym
+    end
+  end
+  
+  # ----------------------
+  #   instance level API
+  # ----------------------
+  
+  # list all available languages for this instance
+  def available_languages
+    Language.all :id => translations.map { |t| t.language_id }.uniq
+  end
+  
+  # the number of all available languages for this instance
+  def nr_of_available_languages
+    available_languages.size
+  end
+  
+  # checks if this instance is translated into all available languages for this model
+  def translations_complete?
+    self.class.nr_of_available_languages == translations.size
+  end
+  
+  # translates the given attribute to the language identified by the given language_code
+  def translate(attribute, language_code)
+    if language = Language[language_code]
+      t = translations.first(:language_id => language.id)
+      t.respond_to?(attribute) ? t.send(attribute) : nil
+    else
+      nil
+    end
+  end
+  
+  # translates the :name property to the given language
+  def name(language_code)
+    translate(:name, language_code)
+  end
+  
+  # translates the :desc property to the given language
+  def desc(language_code)
+    translate(:desc, language_code)
+  end
+
+
+  # ----------------------------------------
+  #   added by dm-accepts_nested_attributes
+  # ----------------------------------------
+  
+  
+  def item_translations_attributes
+    # ...
+  end
+  
+  def item_translations_attributes=(attributes_or_attributes_collection)
+    # ...
+  end
+
+  # and handy aliases for the above
+
+  alias :translations_attributes  :item_translations_attributes
+  alias :translations_attributes= :item_translations_attributes
+  
+  
+  # TODO
+  # more API to support common usecases (and i18n/l10n solutions)
+  
+end
+</code>
+</pre>
+
+h3. Inspired by (thx guys!)
+
+* Neil Barnwell's comment on the top voted answer to "Schema for a multilanguage database":http://stackoverflow.com/questions/316780/schema-for-a-multilanguage-database
+
+* Gabi Solomon's option (4) at this blog post on "Multilanguage database design approach":http://www.gsdesign.ro/blog/multilanguage-database-design-approach/
+
+
+h3. Copyright
+
+Copyright (c) 2009 Martin Gamsjaeger (snusnu). See "LICENSE":http://github.com/snusnu/dm-is-localizable/tree/master/LICENSE for details.

data/Rakefile

@@ -0,0 +1,86 @@
+require 'pathname'
+require 'rake'
+
+ROOT = Pathname(__FILE__).dirname.expand_path
+JRUBY = RUBY_PLATFORM =~ /java/
+
+begin
+
+  require 'jeweler'
+
+  Jeweler::Tasks.new do |gem|
+
+    gem.name = "dm-is-localizable"
+    gem.summary = %Q{Datamapper support for localization of content in multilanguage applications}
+    gem.email = "gamsnjaga@gmail.com"
+    gem.homepage = "http://github.com/snusnu/dm-is-localizable"
+    gem.authors = ["Martin Gamsjaeger (snusnu)"]
+
+    gem.add_dependency('dm-core',         '>= 0.10.2')
+    gem.add_dependency('dm-is-remixable', '>= 0.10.2')
+    gem.add_dependency('dm-validations',  '>= 0.10.2')
+
+    gem.add_development_dependency 'rspec', '~> 1.3'
+
+    Jeweler::GemcutterTasks.new
+
+  end
+
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+begin
+  require 'spec/rake/spectask'
+
+  task :default => [ :spec ]
+
+  desc 'Run specifications'
+  Spec::Rake::SpecTask.new(:spec) do |t|
+    t.spec_opts << '--options' << 'spec/spec.opts' if File.exists?('spec/spec.opts')
+    t.libs      << 'lib' << 'spec' # needed for CI rake spec task, duplicated in spec_helper
+
+    begin
+      require 'rcov'
+      t.rcov = JRUBY ? false : (ENV.has_key?('NO_RCOV') ? ENV['NO_RCOV'] != 'true' : true)
+      t.rcov_opts << '--exclude' << 'spec'
+      t.rcov_opts << '--text-summary'
+      t.rcov_opts << '--sort' << 'coverage' << '--sort-reverse'
+    rescue LoadError
+      # rcov not installed
+    rescue SyntaxError
+      # rcov syntax invalid
+    end
+  end
+rescue LoadError
+  # rspec not installed
+end
+
+begin
+  require 'cucumber/rake/task'
+  Cucumber::Rake::Task.new(:features)
+rescue LoadError
+  task :features do
+    abort "Cucumber is not available. In order to run features, you must: sudo gem install cucumber"
+  end
+end
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION.yml')
+    config = YAML.load(File.read('VERSION.yml'))
+    version = "#{config[:major]}.#{config[:minor]}.#{config[:patch]}"
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "dm-is-localizable #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+# require all tasks below tasks
+Pathname.glob(ROOT.join('tasks/**/*.rb').to_s).each { |f| require f }

data/TODO

@@ -0,0 +1,2 @@
+* Add accessors for the localized properties in the localizable resource
+* Think about validation and null constraints

data/VERSION

@@ -0,0 +1 @@
+0.10.1

data/dm-is-localizable.gemspec

@@ -0,0 +1,88 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{dm-is-localizable}
+  s.version = "0.10.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Martin Gamsjaeger (snusnu)"]
+  s.date = %q{2010-02-04}
+  s.email = %q{gamsnjaga@gmail.com}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.textile",
+     "TODO"
+  ]
+  s.files = [
+    ".document",
+     ".gitignore",
+     "CHANGELOG",
+     "LICENSE",
+     "README.textile",
+     "Rakefile",
+     "TODO",
+     "VERSION",
+     "dm-is-localizable.gemspec",
+     "lib/dm-is-localizable.rb",
+     "lib/dm-is-localizable/is/localizable.rb",
+     "lib/dm-is-localizable/storage/language.rb",
+     "lib/dm-is-localizable/storage/translation.rb",
+     "spec/fixtures/item.rb",
+     "spec/lib/rspec_tmbundle_support.rb",
+     "spec/shared/shared_examples_spec.rb",
+     "spec/spec.opts",
+     "spec/spec_helper.rb",
+     "spec/unit/auto_migrate_spec.rb",
+     "spec/unit/class_level_api_spec.rb",
+     "spec/unit/instance_level_api_spec.rb",
+     "spec/unit/is_localizable_spec.rb",
+     "spec/unit/language_spec.rb",
+     "spec/unit/translation_spec.rb",
+     "tasks/changelog.rb",
+     "tasks/install.rb",
+     "tasks/whitespace.rb"
+  ]
+  s.homepage = %q{http://github.com/snusnu/dm-is-localizable}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.5}
+  s.summary = %q{Datamapper support for localization of content in multilanguage applications}
+  s.test_files = [
+    "spec/fixtures/item.rb",
+     "spec/lib/rspec_tmbundle_support.rb",
+     "spec/shared/shared_examples_spec.rb",
+     "spec/spec_helper.rb",
+     "spec/unit/auto_migrate_spec.rb",
+     "spec/unit/class_level_api_spec.rb",
+     "spec/unit/instance_level_api_spec.rb",
+     "spec/unit/is_localizable_spec.rb",
+     "spec/unit/language_spec.rb",
+     "spec/unit/translation_spec.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<dm-core>, [">= 0.10.2"])
+      s.add_runtime_dependency(%q<dm-is-remixable>, [">= 0.10.2"])
+      s.add_runtime_dependency(%q<dm-validations>, [">= 0.10.2"])
+      s.add_development_dependency(%q<rspec>, ["~> 1.3"])
+    else
+      s.add_dependency(%q<dm-core>, [">= 0.10.2"])
+      s.add_dependency(%q<dm-is-remixable>, [">= 0.10.2"])
+      s.add_dependency(%q<dm-validations>, [">= 0.10.2"])
+      s.add_dependency(%q<rspec>, ["~> 1.3"])
+    end
+  else
+    s.add_dependency(%q<dm-core>, [">= 0.10.2"])
+    s.add_dependency(%q<dm-is-remixable>, [">= 0.10.2"])
+    s.add_dependency(%q<dm-validations>, [">= 0.10.2"])
+    s.add_dependency(%q<rspec>, ["~> 1.3"])
+  end
+end
+

data/lib/dm-is-localizable/is/localizable.rb

@@ -0,0 +1,135 @@
+module DataMapper
+  module Is
+
+    module Localizable
+
+
+      def is_localizable(options = {}, &block)
+
+        extend  ClassMethods
+        include InstanceMethods
+
+        options = {
+          :as                       => nil,
+          :model                    => "#{self}Translation",
+          :accept_nested_attributes => true
+        }.merge(options)
+
+        remixer_fk = Extlib::Inflection.foreign_key(self.name).to_sym
+        remixer    = remixer_fk.to_s.gsub('_id', '').to_sym
+        remixee    = Extlib::Inflection.tableize(options[:model]).to_sym
+
+        remix n, Translation, :as => options[:as], :model => options[:model]
+
+        @translation_model = Extlib::Inflection.constantize(options[:model])
+
+        enhance :translation, @translation_model do
+
+          property remixer_fk,   Integer, :min => 1, :required => true, :unique_index => :unique_languages
+          property :language_id, Integer, :min => 1, :required => true, :unique_index => :unique_languages
+
+          belongs_to remixer
+          belongs_to :language
+
+          class_eval &block
+
+          validates_is_unique :language_id, :scope => remixer_fk
+
+        end
+
+        has n, :languages, :through => remixee, :constraint => :destroy
+
+        self.class_eval(<<-RUBY, __FILE__, __LINE__ + 1)
+
+          alias :translations :#{remixee}
+
+          if options[:accept_nested_attributes]
+
+            # cannot accept_nested_attributes_for :translations
+            # since this is no valid relationship name, only an alias
+
+            accepts_nested_attributes_for :#{remixee}
+            alias :translations_attributes :#{remixee}_attributes
+
+          end
+
+        RUBY
+
+        localizable_properties.each do |property_name|
+          self.class_eval(<<-RUBY, __FILE__, __LINE__ + 1)
+
+            def #{property_name}(language_code)
+              translate(:#{property_name.to_sym}, language_code)
+            end
+
+          RUBY
+        end
+
+      end
+
+      module ClassMethods
+
+        def translation_model
+          @translation_model
+        end
+
+        # list all available languages for the localizable model
+        def available_languages
+          ids = translation_model.all.map { |t| t.language_id }.uniq
+          ids.empty? ? [] : Language.all(:id => ids)
+        end
+
+        # the number of all available languages for the localizable model
+        def nr_of_available_languages
+          available_languages.size
+        end
+
+        # checks if all localizable resources are translated in all available languages
+        def translations_complete?
+          available_languages.size * all.size == translation_model.all.size
+        end
+
+        # returns a list of symbols reflecting all localizable property names of this resource
+        def localizable_properties
+          translation_model.properties.map { |p| p.name }.select do |p|
+            # exclude properties that are'nt localizable
+            p != :id && p != :language_id && p != Extlib::Inflection.foreign_key(self.name).to_sym
+          end
+        end
+
+      end
+
+      module InstanceMethods
+
+        # list all available languages for this instance
+        def available_languages
+          ids = translations.map { |t| t.language_id }.uniq
+          ids.empty? ? [] : Language.all(:id => ids)
+        end
+
+        # the number of all available languages for this instance
+        def nr_of_available_languages
+          available_languages.size
+        end
+
+        # checks if this instance is translated into all available languages for this model
+        def translations_complete?
+          self.class.nr_of_available_languages == translations.size
+        end
+
+        # translates the given attribute to the language identified by the given language_code
+        def translate(attribute, language_code)
+          if language = Language[language_code]
+            t = translations.first(:language_id => language.id)
+            t.respond_to?(attribute) ? t.send(attribute) : nil
+          else
+            nil
+          end
+        end
+
+      end
+
+    end
+
+  end
+end

data/lib/dm-is-localizable/storage/language.rb

@@ -0,0 +1,21 @@
+class Language
+
+  include DataMapper::Resource
+
+  # properties
+
+  property :id, Serial
+
+  property :code, String, :required => true, :unique => true, :unique_index => true
+  property :name, String, :required => true
+
+  # locale string like 'en-US'
+  validates_format :code, :with => /^[a-z]{2}-[A-Z]{2}$/
+
+
+  def self.[](code)
+    return nil if code.nil?
+    first :code => code.to_s.gsub('_', '-')
+  end
+
+end

data/lib/dm-is-localizable/storage/translation.rb

@@ -0,0 +1,18 @@
+module DataMapper
+  module Is
+    module Localizable
+
+      module Translation
+
+        include DataMapper::Resource
+
+        is :remixable
+
+        property :id,          Serial
+        property :language_id, Integer, :min => 1, :required => false
+
+      end
+
+    end
+  end
+end

data/lib/dm-is-localizable.rb

@@ -0,0 +1,6 @@
+require 'dm-is-localizable/is/localizable'
+require 'dm-is-localizable/storage/language'
+require 'dm-is-localizable/storage/translation'
+
+# Include the plugin in Model
+DataMapper::Model.append_extensions DataMapper::Is::Localizable

data/spec/fixtures/item.rb

@@ -0,0 +1,12 @@
+class Item
+
+  include DataMapper::Resource
+
+  property :id, Serial
+
+  is :localizable do
+    property :name, String
+    property :desc, String
+  end
+
+end

data/spec/lib/rspec_tmbundle_support.rb

@@ -0,0 +1,35 @@
+# -----------------------------------------------
+# support for nice html output in rspec tmbundle
+# -----------------------------------------------
+
+module RSpecTmBundleHelpers
+
+  class TextmateRspecLogger < DataMapper::Logger
+    def prep_msg(message, level)
+      "#{super}<br />"
+    end
+  end
+
+  def with_dm_logger(level = :debug)
+    DataMapper.logger.level = level
+    yield
+  ensure
+    DataMapper.logger.level = :off
+  end
+
+  def print_call_stack(from = 2, to = nil, html = true)
+    (from..(to ? to : caller.length)).each do |idx|
+      p "[#{idx}]: #{caller[idx]}#{html ? '<br />' : ''}"
+    end
+  end
+
+  def puth(html = nil)
+    print "#{h(html)}<br />"
+  end
+
+  ESCAPE_TABLE = { '&' => '&amp;', '<' => '&lt;', '>' => '&gt;', '"' => '&quot;', "'" => '&#039;' }
+  def h(value)
+    value.to_s.gsub(/[&<>"]/) {|s| ESCAPE_TABLE[s] }
+  end
+
+end