Puret¶ ↑

Puret is a minimal pure translation library for translating database values for Rails 3.

Puret is quiet like model_translations github.com/janne/model_translations (and borrowed much of its code), but comes with generators to help you get started.

Puret does not create the translation model dynamically (like model_translations does) but creates the file via generator. Puret wants to leave out as much magic as possible and want to allow customizing every part of your application.

Fork Details¶ ↑

This is a fork of the excellent original gem created by Johannes Jörg Schmidt [github.com/jo/puret].

This fork has been created for three reasons:

(1) to allow for the use of an enabled option, for an application providing a system setting to control whether model attribute translations are required;

(2) to cater for the parent model containing the standard/default text for translatable attributes;

(3) to provide the ability to maintain translations through a grand-parent model using accepts_nested_attributes_for eg. with a nested model hierarchy like a Post has_many Comments has_many Translations; with the original gem saving an existing Post with an existing Comment any updated Translations were not saved and a “Can’t mass-assign these protected attributes: id” was produced also when saving an existing Post with an unchanged Comment no Translations were saved due to the use of the before_save and internal array approach as the Comment was not being saved.

Using the Fork¶ ↑

To use this fork add the following to your application gemfile:

gem 'puret', :git => "git://github.com/insphire/userstamp.git"

Do not forget to run

bundle install

Basic Usage¶ ↑

This is a walkthrough with all steps you need to setup puret translated attributes, including model and migration. You MUST also check out the Generators section below to help you start.

We’re assuming here you want a Post model with some puret attributes, as outlined below:

class Post < ActiveRecord::Base
  puret :title, :description
end

The pure translations are stored in a different translation model for every model you need translations for:

class PostTranslation < ActiveRecord::Base
  puret_for :post
end

You now need to create a migration for the translations table:

create_table(:post_translations) do |t|
  t.references :post
  t.string :locale

  t.string :title
  t.text :description

  t.timestamps
end
add_index :post_translations, [:post_id, :locale], :unique => true

Thats it!

Now you are able to translate values for the attributes :title and :description per locale:

post.title = 'Puret rocks!'
I18n.locale = :en
post.translated_title = 'Puret really rocks!'
I18n.locale = :de
post.translated_title = 'Puret rockt wirklich!'

I18n.locale = :en
post.translated_title #=> Puret really rocks!
I18n.locale = :de
post.translated_title #=> Puret rockt wirklich!
I18n.locale = :fr
post.translated_title #=> Puret rocks!

Translation lookup fallback¶ ↑

If a translation is not available in your locale, puret looks

1. for an attribute method in the parent model for the standard/default text

2. for an instance method called default_locale and the corresponding translation

3. for a class method called default_locale and the corresponding translation

4. for a translation in I18n.default_locale

In case a translation is not available in the default locale, puret uses the first locale it could find. That order is specified by creation time, so the first created translation will be returned.

Puret also looks for the following to determine whether translations are enabled

1. for an instance method called translations_enabled?

2. for a class method called translations_enabled?

3. if neither exist then translations are considered enabled

If translations are disabled then the translated_ methods return the standard/default text if an equivalent attribute method exists in the parent model otherwise nil.

Generators¶ ↑

Puret comes with some generators to help you with your daily job:

rails generate puret:model Post title:string description:text

will setup all the code above and more, either you already have a Post model or not. In the latter case the Post model will be created for you.

In case you already have a translated model and want to add some more puret attributes, just run the puret:attribute generator:

rails generate puret:attribute Post body:text

This will create the appropriate migration and configure your Post model to translate the new attribute body.

Keep it simple! Relax.

Diggin deeper¶ ↑

Read the Rdoc documentation at rdoc.info/projects/jo/puret.