Awesome Hstore Translate

This gem uses PostgreSQLs hstore datatype and ActiveRecord models to translate model data. It is based on the gem hstore_translate by Rob Worely.

• It's ready for Rails 5
• No extra columns or tables needed to operate
• Clean naming in the database model
• Everything is well tested

Features

• [x] Attributes override / Raw attributes
• [x] Fallbacks
• [x] Language specific accessors
• [ ] Support instance selection (e. g. where, find_by)
• [ ] Support friendly_id

Requirements

• ActiveRecord >= 5
• I18n

Installation

Add this line to your application's Gemfile:

gem 'awesome_hstore_translate'

And then execute:

$ bundle

Or install it yourself as:

$ gem install awesome_hstore_translate

Usage

Use translates in your models, to define the attributes, which should be translateable:

class Page < ActiveRecord::Base
  translates :title, :content
end

Make sure that the datatype of this columns is hstore:

class CreatePages < ActiveRecord::Migration
  def change
    create_table :pages do |t|
      t.column :title, :hstore
      t.column :content, :hstore
      t.timestamps
    end
  end
end

Use the model attributes per locale:

p = Page.first

I18n.locale = :en
p.title # => English title

I18n.locale = :de
p.title # => Deutscher Titel

I18n.with_locale :en do
  p.title # => English title
end

The raw data is available via the suffix _raw:

p = Page.new(:title_raw => {'en' => 'English title', 'de' => 'Deutscher Titel'})

p.title_raw # => {'en' => 'English title', 'de' => 'Deutscher Titel'}

Fallbacks

To enable fallbacks you can set I18n.fallbacks to true or enable it manually in the model:

class Page < ActiveRecord::Base
  translates :title, :content, fallbacks: true
end

Set I18n.default_locale or I18n.fallbacks to define the fallback:

I18n.fallbacks.map(:en => :de) # => if :en is nil or empty, it will use :de

p = Page.new(:title_raw => {'de' => 'Deutscher Titel'})

I18n.with_locale :en do
  p.title # => Deutscher Titel
end

It's possible to activate (with_fallbacks) or deactivate (without_fallbacks) fallbacks for a block execution:

p = PageWithoutFallbacks.new(:title_raw => {'de' => 'Deutscher Titel'})

I18n.with_locale(:en) do
  PageWithoutFallbacks.with_fallbacks do
    assert_equal('Deutscher Titel', p.title)
  end
end

Accessors

Convenience accessors can be enabled via the model descriptor:

class Page < ActiveRecord::Base
  translates :title, :content, accessors: [:de, :en]
end

It's also make sense to activate the accessors for all available locales:

class Page < ActiveRecord::Base
  translates :title, :content, accessors: I18n.available_locales
end

Now locale-suffixed accessors can be used:

p = Page.create!(:title_en => 'English title', :title_de => 'Deutscher Titel')

p.title_en # => English title
p.title_de # => Deutscher Titel

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.