has_translations 0.3.0

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 [name of plugin creator]
+
+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.md

@@ -0,0 +1,147 @@
+HasTranslations v0.3.pre
+====================
+
+This simple plugin creates translations for your model.
+Uses delegation pattern: http://en.wikipedia.org/wiki/Delegation_pattern
+
+Installation
+============
+
+    gem install has_translations
+
+or as a plugin
+
+    script/plugin install git://github.com/dmitry/has_translations.git
+
+Example
+=======
+
+For example you have Article model and you want to have title and text to be translated.
+
+Create model named ArticleTranslation (Rule: [CamelCaseModelName]Translation)
+
+Migration should have `locale` as a string with two letters and `belongs_to associative id`, like:
+
+    class CreateArticleTranslations < ActiveRecord::Migration
+      def self.up
+        create_table :article_translations do |t|
+          t.integer :article_id, :null => false
+          t.string :locale, :null => false, :limit => 2
+          t.string :title, :null => false
+          t.text :text, :null => false
+        end
+
+        add_index :article_translations, [:article_id, :locale], :unique => true
+      end
+
+      def self.down
+        drop_table :article_translations
+      end
+    end
+
+Add to article model `translations :value1, :value2`:
+
+    class Article < ActiveRecord::Base
+      translations :title, :text
+    end
+
+And that's it. Now you can add your translations using:
+
+    article = Article.create
+
+    article.translations.create(:locale => 'en', :title => 'title', :text => 'text') # or ArticleTranslation.create(:article => article, :locale => 'en', :title => 'title', :text => 'text')
+    article.translations.create(:locale => 'ru', :title => 'заголовок', :text => 'текст')
+    article.reload # reload cached translations association array
+    I18n.locale = :en
+    article.text # text
+    I18n.locale = :ru
+    article.title # заголовок
+
+You can use text filtering plugins, like acts_as_sanitiled and validations, and anything else that is available to the ActiveRecord:
+
+    class ArticleTranslation < ActiveRecord::Base
+      acts_as_sanitiled :title, :text
+
+      validates_presence_of :title, :text
+      validates_length_of :title, :maximum => 100
+    end
+
+Options:
+
+* :fallback => true [default: false] - fallback 1) default locale; 2) first from translations;
+* :reader => false [default: true] - add reader to the model object
+* :writer => true [default: false] - add writer to the model object
+* :nil => nil [default: ''] - if no model found by default returns empty string, you can set it for example to `nil` (no `lambda` supported)
+
+It's better to use translations with `accepts_nested_attributes_for`:
+
+    accepts_nested_attributes_for :translations
+
+To create a form for this you can use `all_translations` method. It's have all
+the locales that you have added using the `I18n.available_locales=` method.
+If translation for one of the locale isn't exists, it will build it with :locale.
+So an example which I used in the production (using `formtastic` gem):
+
+    <% semantic_form_for [:admin, @article] do |f| %>
+      <%= f.error_messages %>
+
+      <% f.inputs :name => "Basic" do %>
+        <% object.all_translations.values.each do |translation| %>
+          <% f.semantic_fields_for :translations, translation do |ft| %>
+            <%= ft.input :title, :label => "Title #{ft.object.locale.to_s.upcase}" %>
+            <%= ft.input :text, :label => "Text #{ft.object.locale.to_s.upcase}" %>
+            <%= ft.input :locale, :as => :hidden %>
+          <% end %>
+        <% end %>
+      <% end %>
+    <% end %>
+
+Sometimes you have validations in the translation model, and if you want to skip
+the translations that you don't want to add to the database, you can use
+`:reject_if` option, which is available for the `accepts_nested_attributes_for`:
+
+    accepts_nested_attributes_for :translations, :reject_if => lambda { |attrs| attrs['title'].blank? && attrs['text'].blank? }
+
+named_scope `translated(locale)` - with that named_scope you can find only
+those models that is translated only to specific locale. For example if you will
+have 2 models, one is translated to english and the second one isn't, then it
+`Article.translated(:en)` will find only first one.
+
+PS
+==
+
+I suggest you to use latest i18n gem, include it in your rails 2 environment:
+
+    config.gem 'i18n', :version => '0.4.1' # change version to the latest
+
+TODO
+====
+
+* active record 3 (rails 3) support
+* add installation description to readme
+* model and migration generators
+* caching
+* write more examples: fallback feature
+* write blog post about comparison and benefits of this plugin between another translation model plugins
+
+
+Alternatives
+============
+
+I know three of them:
+
+* [puret](http://github.com/jo/puret) - special for Rails 3 and almost the same as this project.
+* [globalite2](http://github.com/joshmh/globalize2) - a lot of magic.
+* [model_translations](http://github.com/janne/model_translations) - almost the same as this project, but more with more code in lib.
+* [translatable_columns](http://github.com/iain/translatable_columns) - different approach: every column have own postfix "_#{locale}" in the same table (sometimes it could be fine).
+
+
+Used in
+=======
+
+* [noch.es](http://noch.es/)
+* [eten.es](http://www.eten.es))
+* [sem.ee](http://sem.ee/)
+
+
+Copyright (c) 2009-2010 [Dmitry Polushkin], released under the MIT license

data/Rakefile

@@ -0,0 +1,38 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the has_translations plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Generate documentation for the has_translations plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'HasTranslations'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = "has_translations"
+    gemspec.summary = "Create translations for your ActiveRecord models."
+    gemspec.description = "Create translations for your ActiveRecord models. Uses delegate pattern. Fully tested and used in a several production sites."
+    gemspec.email = "dmitry.polushkin@gmail.com"
+    gemspec.homepage = "http://github.com/dmitry/has_translations"
+    gemspec.authors = ["Dmitry Polushkin"]
+    gemspec.version = '0.3.0'
+  end
+rescue LoadError
+  puts "Jeweler not available. Install it with: gem install jeweler"
+end

data/generators/has_translations/USAGE

@@ -0,0 +1,8 @@
+Description:
+    Explain the generator
+
+Example:
+    ./script/generate has_translations Thing
+
+    This will create:
+        what/will/it/create

data/generators/has_translations/has_translations_generator.rb

@@ -0,0 +1,8 @@
+class HasTranslationsGenerator < Rails::Generator::NamedBase
+  def manifest
+    record do |m|
+      # m.directory "lib"
+      # m.template 'README', "README"
+    end
+  end
+end

data/init.rb

@@ -0,0 +1 @@
+require 'has_translations'

data/install.rb

@@ -0,0 +1 @@
+# Install hook code here

data/lib/has_translations.rb

@@ -0,0 +1,152 @@
+class ActiveRecord::Base
+  # Provides ability to add the translations for the model using delegate pattern.
+  # Uses has_many association to the ModelNameTranslation.
+  #
+  # For example you have model Article with attributes title and text.
+  # You want that attributes title and text to be translated.
+  # For this reason you need to generate new model ArticleTranslation.
+  # In migration you need to add:
+  #
+  #   create_table :article_translations do |t|
+  #     t.references :article, :null => false
+  #     t.string :locale, :length => 2, :null => false
+  #     t.string :name, :null => false
+  #   end
+  #
+  #   add_index :articles, [:article_id, :locale], :unique => true, :name => 'unique_locale_for_article_id'
+  #
+  # And in the Article model:
+  #
+  #   translations :title, :text
+  #
+  # This will adds:
+  #
+  # * named_scope (translated) and has_many association to the Article model
+  # * locale presence validation to the ArticleTranslation model.
+  #
+  # Notice: if you want to have validates_presence_of :article, you should use :inverse_of.
+  # Support this by yourself. Better is always to use artile.translations.build() method.
+  #
+  # For more information please read API. Feel free to write me an email to:
+  # dmitry.polushkin@gmail.com.
+  #
+  # ===
+  #
+  # You also can pass attributes and options to the translations class method:
+  #
+  #   translations :title, :text, :fallback => true, :writer => true, :nil => nil
+  #
+  # ===
+  #
+  # Configuration options:
+  # 
+  # * <tt>:fallback</tt> - if translation for the current locale not found.
+  #   By default false. Set to true if you want to use reader fallback.
+  #   Uses algorithm of fallback:
+  #   0) current translation (using I18n.locale);
+  #   1) default locale (using I18n.default_locale);
+  #   2) first from translations association;
+  #   3) :nil value (see <tt>:nil</tt> configuration option)
+  # * <tt>:reader</tt> - add reader attributes to the model and delegate them
+  #   to the translation model columns. Add's fallback if it is set to true.
+  # * <tt>:writer</tt> - add writer attributes to the model and assign them
+  #   to the translation model attributes.
+  # * <tt>:nil</tt> - when reader cant find string, it returns by default an
+  #   empty string. If you want to change this setting for example to nil,
+  #   add :nil => nil
+  #
+  # ===
+  #
+  # When you are using <tt>:writer</tt> option, you can create translations using
+  # update_attributes method. For example:
+  #
+  #   Article.create!
+  #   Article.update_attributes(:title => 'title', :text => 'text')
+  #
+  # ===
+  #
+  # <tt>translated</tt> named_scope is useful when you want to find only those
+  # records that are translated to a specific locale.
+  # For example if you want to find all Articles that is translated to an english
+  # language, you can write: Article.translated(:en)
+  #
+  # <tt>has_translation?(locale)</tt> method, that returns true if object's model
+  # have a translation for a specified locale
+  #
+  # <tt>translation(locale)</tt> method finds translation with specified locale.
+  #
+  # <tt>all_translations</tt> method that returns all possible translations in
+  # ordered hash (useful when creating forms with nested attributes).
+  def self.translations(*attrs)
+    options = {
+      :fallback => false,
+      :reader => true,
+      :writer => false,
+      :nil => ''
+    }.merge(attrs.extract_options!)
+
+    options.assert_valid_keys([:fallback, :reader, :writer, :nil])
+
+    translation_class_name = "#{self.model_name}Translation"
+    translation_class = translation_class_name.constantize
+    belongs_to = self.model_name.demodulize.singularize.underscore.to_sym
+
+    write_inheritable_attribute :has_translations_options, options
+    class_inheritable_reader :has_translations_options
+
+    send :define_method, :find_or_build_translation do |*args|
+      locale = args.first.to_s
+      build = args.second.present?
+      find_translation(locale) || (build ? self.translations.build(:locale => locale) : self.translations.new(:locale => locale))
+    end
+
+    def translation(locale, fallback=has_translations_options[:fallback])
+      locale = locale.to_s
+      find_translation(locale) || (fallback && !translations.blank? ? translations.detect { |t| t.locale == I18n.default_locale.to_s } || translations.first : nil)
+    end
+
+    def all_translations
+      t = I18n.available_locales.map do |locale|
+        [locale, find_or_build_translation(locale)]
+      end
+      ActiveSupport::OrderedHash[t]
+    end
+
+    def has_translation?(locale)
+      find_translation(locale).present?
+    end
+
+    if options[:reader]
+      attrs.each do |name|
+        send :define_method, name do
+          translation = self.translation(I18n.locale)
+          translation.nil? ? has_translations_options[:nil] : translation.send(name)
+        end
+      end
+    end
+
+    if options[:writer]
+      attrs.each do |name|
+        send :define_method, "#{name}=" do |value|
+          translation = find_or_build_translation(I18n.locale, true)
+          translation.send(:"#{name}=", value)
+        end
+      end
+    end
+
+    has_many :translations, :class_name => translation_class_name, :dependent => :destroy
+    
+    translation_class.belongs_to belongs_to
+    translation_class.validates_presence_of :locale
+    translation_class.validates_uniqueness_of :locale, :scope => :"#{belongs_to}_id"
+
+    named_scope :translated, lambda { |locale| {:conditions => ["#{translation_class.table_name}.locale = ?", locale.to_s], :joins => :translations} }
+
+    private
+
+    def find_translation(locale)
+      locale = locale.to_s
+      translations.detect { |t| t.locale == locale }
+    end
+  end
+end

data/tasks/has_translations_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :has_translations do
+#   # Task goes here
+# end

data/test/.gitignore

@@ -0,0 +1,2 @@
+has_translations_plugin.sqlite3.db
+debug.log

data/test/has_translations_test.rb

@@ -0,0 +1,113 @@
+require 'test_helper'
+
+class HasTranslationsTest < Test::Unit::TestCase
+  def setup
+    setup_db
+    
+    [Article, ArticleTranslation, Team, TeamTranslation].each do |k|
+      k.delete_all
+    end
+    I18n.available_locales = :ru, :en, :es
+    I18n.locale = :ru
+  end
+
+  def teardown
+    teardown_db
+  end
+
+  def test_schema_has_loaded_correctly
+    [Article, ArticleTranslation, Team, TeamTranslation].each do |k|
+      assert_equal [], k.all
+    end
+    assert_equal :ru, I18n.locale
+  end
+
+  def test_reader_text_for_a_given_locale
+    article = Article.create!
+    article_translation = ArticleTranslation.create!(:article => article, :locale => 'en', :description => 'desc', :text => 'text')
+    assert_not_equal article.text, article_translation.text
+    I18n.locale = :en
+    assert_equal article.text, article_translation.text
+  end
+
+  def test_writer_text_for_a_given_locale
+    article = Article.create!
+    article.text = 'text'
+    assert_equal 0, article.translations.count
+    article.save!
+    assert_equal 1, article.translations.length
+    assert_equal 1, article.translations.count
+    I18n.locale = :en
+    assert_equal '', article.text
+    article.update_attributes!(:text => 'text')
+    assert_equal 2, Article.first.translations.count
+  end
+
+  def test_translations_association_and_translations
+    article = Article.create!
+    assert_equal [], article.translations
+    article_translation = ArticleTranslation.create!(:article => article, :locale => 'ru', :description => 'описание', :text => 'текст')
+    assert_equal [], article.translations
+    assert_equal [article_translation], article.reload.translations
+    assert_equal 'текст', article.text
+    I18n.locale = :en
+    assert_equal '', article.text
+    assert_equal article_translation, article.translation('ru')
+    assert_equal article_translation, article.translation(:ru)
+    assert article.destroy
+    assert_equal [], ArticleTranslation.all
+  end
+
+  def test_translation_validations
+    article_translation = ArticleTranslation.create(:description => 'description', :text => 'text')
+    assert article_translation.errors[:locale].present?
+    # TODO may be add :inverse_of to has_many and add presence validation for the belongs_to
+  end
+
+  def test_fallback_and_nil_options
+    article = Article.create!
+    assert_equal '', article.text
+    team = Team.create!
+    assert_equal nil, team.text
+    first_translation = TeamTranslation.create!(:team => team, :locale => 'es', :text => 'text')
+    assert_equal first_translation.text, team.reload.text
+    default_translation = TeamTranslation.create!(:team => team, :locale => 'en', :text => 'text')
+    assert_equal default_translation.text, team.reload.text
+    real_translation = TeamTranslation.create!(:team => team, :locale => 'ru', :text => 'текст')
+    assert_equal real_translation.text, team.reload.text
+  end
+
+  def test_all_translations_sorted_build_or_translation_getted
+    team = Team.create!
+    team_translation = TeamTranslation.create!(:team => team, :locale => 'en', :text => 'text')
+    assert_equal team_translation, team.all_translations[:en]
+    assert_equal 'ru', team.all_translations[:ru].locale
+    team_translation_new = team.translations.build(:locale => :ru)
+    assert_equal team_translation_new.locale.to_s, team.all_translations[:ru].locale
+  end
+
+  def test_all_translations_should_not_have_build_translations
+    team = Team.create!
+    assert_equal 0, team.translations.length
+    team.all_translations
+    assert_equal 0, team.translations.length
+  end
+
+  def test_has_translation?
+    team = Team.create!
+    assert !team.has_translation?(:en)
+    team.translations.create!(:locale => 'en', :text => 'text')
+    assert team.has_translation?(:en)
+  end
+
+  def test_named_scope_translated
+    assert_equal 0, Team.translated(:en).count
+    assert_equal 0, Team.translated(:ru).count
+    team = Team.create!
+    team.translations.create!(:locale => 'en', :text => 'text')
+    assert_equal 0, Team.translated(:ru).count
+    assert_equal 1, Team.translated(:en).count
+    team.translations.create!(:locale => 'ru', :text => 'текст')
+    assert_equal 1, Team.translated(:ru).count
+  end
+end

data/test/schema.rb

@@ -0,0 +1,36 @@
+ActiveRecord::Schema.define(:version => 0) do
+  create_table :articles, :force => true do |t|
+    t.string :title
+  end
+
+  create_table :article_translations, :force => true do |t|
+    t.references :article, :null => false
+    t.string :locale, :null => false, :limit => 2
+    t.string :description
+    t.text :text
+  end
+
+  create_table :teams, :force => true do |t|
+    t.string :title
+  end
+
+  create_table :team_translations, :force => true do |t|
+    t.references :team, :null => false
+    t.string :locale, :null => false, :limit => 2
+    t.text :text
+  end
+end
+
+class ArticleTranslation < ActiveRecord::Base
+end
+
+class Article < ActiveRecord::Base
+  translations :description, :text, :writer => true
+end
+
+class TeamTranslation < ActiveRecord::Base
+end
+
+class Team < ActiveRecord::Base
+  translations :text, :fallback => true, :nil => nil
+end

data/test/test_helper.rb

@@ -0,0 +1,25 @@
+require 'rubygems'
+require 'test/unit'
+
+gem 'activerecord', '~> 2.3'
+gem 'i18n', '~> 0.4'
+
+require 'active_record'
+require 'logger'
+
+require 'has_translations'
+
+#ActiveRecord::Base.logger = Logger.new(STDOUT)
+ActiveRecord::Base.logger = nil
+ActiveRecord::Base.establish_connection(:adapter => "sqlite3", :database => ":memory:")
+
+def setup_db
+  ActiveRecord::Migration.verbose = false
+  load "schema.rb"
+end
+
+def teardown_db
+  ActiveRecord::Base.connection.tables.each do |table|
+    ActiveRecord::Base.connection.drop_table(table)
+  end
+end

data/uninstall.rb

@@ -0,0 +1 @@
+# Uninstall hook code here

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification 
+name: has_translations
+version: !ruby/object:Gem::Version 
+  hash: 19
+  prerelease: false
+  segments: 
+  - 0
+  - 3
+  - 0
+  version: 0.3.0
+platform: ruby
+authors: 
+- Dmitry Polushkin
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-08-25 00:00:00 +01:00
+default_executable: 
+dependencies: []
+
+description: Create translations for your ActiveRecord models. Uses delegate pattern. Fully tested and used in a several production sites.
+email: dmitry.polushkin@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.md
+files: 
+- MIT-LICENSE
+- README.md
+- Rakefile
+- generators/has_translations/USAGE
+- generators/has_translations/has_translations_generator.rb
+- init.rb
+- install.rb
+- lib/has_translations.rb
+- tasks/has_translations_tasks.rake
+- test/.gitignore
+- test/has_translations_test.rb
+- test/schema.rb
+- test/test_helper.rb
+- uninstall.rb
+has_rdoc: true
+homepage: http://github.com/dmitry/has_translations
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Create translations for your ActiveRecord models.
+test_files: 
+- test/has_translations_test.rb
+- test/schema.rb
+- test/test_helper.rb