snusnu-dm-is-localizable 0.0.5

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,23 @@
+test_log
+pkg
+pkg/*
+*/pkg/*
+bundle
+bundle/*
+doc
+*.log
+log
+!log*.rb
+*/log
+log/*
+*/log/*
+coverage
+*/coverage
+lib/dm-more.rb
+*.db
+nbproject
+.DS_Store
+rspec_report.html
+*.swp
+_Yardoc
+*/ri

data/CHANGELOG

@@ -0,0 +1,183 @@
+[e66cccc | Sat May 16 19:02:07 UTC 2009] snusnu <gamsnjaga@gmail.com>
+
+ * Version bump to 0.0.4
+
+[963611b | Sat May 16 19:00:47 UTC 2009] snusnu <gamsnjaga@gmail.com>
+
+ * README corrections to reflect the recently added uniqueness constraints
+
+[47c5e1e | Sat May 16 18:56:09 UTC 2009] snusnu <gamsnjaga@gmail.com>
+
+ * added passing specs for unique language translations
+
+[fd37d64 | Sat May 16 18:55:09 UTC 2009] snusnu <gamsnjaga@gmail.com>
+
+ * more comprehensive unique constraint violation checks for language
+
+[15a9626 | Sat May 16 18:34:13 UTC 2009] snusnu <gamsnjaga@gmail.com>
+
+ * added passing spec for unique language codes
+
+[20242b3 | Sat May 16 18:17:19 UTC 2009] snusnu <gamsnjaga@gmail.com>
+
+ * split spec files into better manageable chunks
+
+[f4b6d30 | Sat May 16 17:32:46 UTC 2009] snusnu <gamsnjaga@gmail.com>
+
+ * moved rspec_tmbundle_support from specs/shared to specs/lib
+
+[12fe27a | Sat May 16 17:26:30 UTC 2009] snusnu <gamsnjaga@gmail.com>
+
+ * added TODO file
+
+[c66d793 | Sat May 16 17:22:51 UTC 2009] snusnu <gamsnjaga@gmail.com>
+
+ * added more class and instance level API.
+
+    These API methods mainly target the support for a UI that allows
+    clients to enter localized versions of their textual data (and
+    find out if they already completed their translations for specific
+    resources).
+    
+    added class level API
+    
+      * available_languages
+      * nr_of_available_languages
+      * translations_complete?
+    
+    instance level API
+    
+      * available_languages
+      * nr_of_available_languages
+      * translations_complete?
+
+[cb462f4 | Sat May 16 17:13:57 UTC 2009] snusnu <gamsnjaga@gmail.com>
+
+ * added support for nice html output in rspec tmbundle.
+
+[f713c84 | Sat May 16 05:33:54 UTC 2009] snusnu <gamsnjaga@gmail.com>
+
+ * Version bump to 0.0.3
+
+[aa6188c | Sat May 16 05:33:44 UTC 2009] snusnu <gamsnjaga@gmail.com>
+
+ * added available_languages instance level API
+
+[d5f13e1 | Sat May 16 05:12:03 UTC 2009] snusnu <gamsnjaga@gmail.com>
+
+ * README correction (available_languages is a class method)
+
+[92bf341 | Sat May 16 05:06:05 UTC 2009] snusnu <gamsnjaga@gmail.com>
+
+ * Version bump to 0.0.2
+
+[8de6a08 | Sat May 16 05:00:33 UTC 2009] snusnu <gamsnjaga@gmail.com>
+
+ * added specs for the translations and languages association.
+
+    I wonder if available_languages should be implemeted on top of
+    has n, :languages, :through => :translations
+
+[dd4830f | Sat May 16 04:51:23 UTC 2009] snusnu <gamsnjaga@gmail.com>
+
+ * added available_languages class method API
+
+[3596021 | Sat May 16 04:37:45 UTC 2009] snusnu <gamsnjaga@gmail.com>
+
+ * use transactional fixtures and have the loggers handy
+
+[fa00b88 | Sat May 16 04:07:10 UTC 2009] snusnu <gamsnjaga@gmail.com>
+
+ * enforce unique language codes (locale strings)
+
+[b7b8221 | Sat May 16 04:01:59 UTC 2009] snusnu <gamsnjaga@gmail.com>
+
+ * added missing spec for translation_class reader
+
+[b0cd326 | Sat May 16 03:43:33 UTC 2009] snusnu <gamsnjaga@gmail.com>
+
+ * translation_class reader instead of translation_class_name
+
+[d34352b | Sat May 16 03:31:54 UTC 2009] snusnu <gamsnjaga@gmail.com>
+
+ * jeweler generated gemspec
+
+[0ddc194 | Sat May 16 03:28:33 UTC 2009] snusnu <gamsnjaga@gmail.com>
+
+ * Version bump to 0.0.1
+
+[5abddb9 | Sat May 16 03:28:06 UTC 2009] snusnu <gamsnjaga@gmail.com>
+
+ * Version bump to 0.0.0
+
+[25ace0a | Sat May 16 03:26:39 UTC 2009] snusnu <gamsnjaga@gmail.com>
+
+ * updated README to reflect validations for Language
+
+[8f78083 | Sat May 16 03:24:00 UTC 2009] snusnu <gamsnjaga@gmail.com>
+
+ * validations and specs for Language.
+
+    * Think about locale string validation.
+    * Currently this is only a regex
+    * Should THIS be checked against a full list of possible locales?
+
+[d1c0a25 | Sat May 16 03:23:01 UTC 2009] snusnu <gamsnjaga@gmail.com>
+
+ * proper namespace for module Translation
+
+[982e081 | Sat May 16 03:21:29 UTC 2009] snusnu <gamsnjaga@gmail.com>
+
+ * added gem dependencies to gem specification and spec_helper
+
+[8cf2113 | Sat May 16 00:57:17 UTC 2009] snusnu <gamsnjaga@gmail.com>
+
+ * README cosmetics
+
+[8507bab | Sat May 16 00:27:42 UTC 2009] snusnu <gamsnjaga@gmail.com>
+
+ * updated README with usage examples.
+
+[d277892 | Fri May 15 23:49:27 UTC 2009] snusnu <gamsnjaga@gmail.com>
+
+ * updated LICENSE information
+
+[f6655c8 | Fri May 15 21:42:44 UTC 2009] snusnu <gamsnjaga@gmail.com>
+
+ * basic storage layout functional and tested. now add useful API.
+
+    * one xxx_translations table for every translatable resource
+    * belongs_to the resource to translate
+    * belongs_to a language
+    * properties to be translated are defined in xxx_translations
+    
+    Example
+    
+      class Item
+        include DataMapper::Resource
+        property :id, Serial
+        is :localizable do
+          property :name, String, :nullable => false
+          property :desc, String, :nullable => false
+        end
+      end
+    
+    Advantages
+    
+      * Proper normalization and referential integrity
+      * Ease in adding a new language (add row to xxx_translations)
+      * Easy to query
+      * Columns keep there names
+    
+    Disadvantages (not really if you think about it)
+    
+      * one table for every tables resource that needs translations
+    
+    Inspired by
+    
+      option 4) at http://is.gd/Af0d
+
+[bebfb8d | Fri May 15 13:57:49 UTC 2009] snusnu <gamsnjaga@gmail.com>
+
+ * Initial commit to dm-is-localizable.
+

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Martin Gamsjaeger (snusnu)
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.textile

@@ -0,0 +1,177 @@
+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 localized model
+
+Currently, you need to define a @Language@ model yourself, to get @dm-is-localizable@ started.
+
+<pre>
+<code>
+class Language
+
+  include DataMapper::Resource
+
+  # properties
+
+  property :id, Serial
+
+  property :code, String, :nullable => false, :unique => true, :unique_index => true
+  property :name, String, :nullable => false
+  
+  # locale string like 'en-US'
+  validates_format :code, :with => /^[a-z]{2}-[A-Z]{2}$/
+
+end
+</code>
+</pre>
+
+Once you have this model in place, you can start defining your _localized models_.
+
+<pre>
+<code>
+class Item
+
+  include DataMapper::Resource
+  
+  property :id, Serial
+  
+  is :localizable 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 @:class_name@ option like so: @DataMapper::Model.is :localized, :class_name => 'ItemLocalization'@. However, this currently not yet specced.
+
+<pre>
+<code>
+class ItemTranslation
+
+  include DataMapper::Resource
+  
+  property :id,          Serial
+  
+  property :item_id,     Integer, :nullable => false, :unique_index => :unique_languages
+  property :language_id, Integer, :nullable => false, :unique_index => :unique_languages
+  
+  property :name,        String
+  property :desc,        String
+
+  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_class
+  
+  # -------------------
+  #   class level API
+  # -------------------
+  
+  # list all available languages for Items
+  def self.available_languages
+    Language.all :id => translation_class.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_class.all.size
+  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
+  
+  
+  # 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,77 @@
+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.9.11')
+    gem.add_dependency('dm-is-remixable', '>= 0.9.11')
+    gem.add_dependency('dm-validations',  '>= 0.9.11')
+  end
+
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+begin
+  gem 'rspec', '>=1.1.12'
+  require 'spec'
+  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.spec_files = Pathname.glob((ROOT + 'spec/**/*_spec.rb').to_s).map { |f| f.to_s }
+ 
+    begin
+      gem 'rcov', '~>0.8'
+      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
+    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 }