Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Enables database-backed translation support.

branch: master
README.md

Overview

Gem Version Code Climate GPA Gemnasium Status Travis CI Status Coverage Status

Enables database-backed translation support for both views and models so you can authorize translators to translate your entire application via an admin interface or whatever you like.

While this gem moves all translations to the database, it does not make building migrations and admin controllers/views easier. That is a goal of this gem but for now, focus is primarily built around the database and models.

Features

  • Database-backed translation support with caching via Redis[http://redis.io].
  • Ability for translators to easily manage view and model translations.

Requirements

  1. Any of the following Ruby VMs:
  2. Ruby on Rails 4.x.x.
  3. Redis.
  4. Read the Rails Internationalization (I18n) API Guide.
  5. Read the Ruby I18n Wiki.
  6. An internet connection (as the generator installs some remote files).

Setup

Type the following to install Redis (assumes knowledge of Homebrew):

brew install redis

Ensure Redis is installed and running properly. Here are some helpful commands:

  • Manual Start: redis-server /usr/local/etc/redis.conf
  • Server Access: redis-cli

For a secure install, type the following from the command line (recommended):

gem cert --add <(curl -Ls http://www.redalchemist.com/gem-public.pem)
gem install linguist --trust-policy MediumSecurity

NOTE: A HighSecurity trust policy would be best but MediumSecurity enables signed gem verification while allowing the installation of unsigned dependencies since they are beyond the scope of this gem.

For an insecure install, type the following (not recommended):

gem install linguist

Add the following to your Gemfile:

gem "redis"
gem "linguist"

Add the following to each of your config/environments/*.rb files:

REDIS = Redis.new

Run the generator:

rails generate linguist:install

Usage

The following provides usage details, each broken down by section:

Routes

In order to manage routes by locale, you'll want to enclose all routes within a locale scope as follows:

scope "(:locale)" do
end

This will yield the following routing (as an example):

http://www.example.com/en-US/about
http://www.example.com/de/about
http://www.example.com/en-US/contact
http://www.example.com/de/contact

Controllers

To supplement the new routing, shown above, the ApplicationController should have the following settings:

class ApplicationController < ActionController::Base
  before_filter :set_locale

  def default_url_options options = {}
    options.reverse_merge! :locale => compute_locale
  end

  private

  def compute_locale
    case
    when current_user.present?
      current_user.language_code || I18n.default_locale
    when I18n.backend.available_locales.map {|locale| locale.to_s}.include?(params[:locale])
      params[:locale]
    else
      I18n.default_locale
    end
  end

  def set_locale
    I18n.locale = compute_locale
  end
end

Assumptions are made that you have a current_user method. All of the heavy lifting is done via the set_locale and default_url_options methods. Feel free to modify for your situation as needed.

Views

Views are the slightly more static data usually directly related to the design of your site. Normally, with view data, you can simply add translated text to the YAML files located in the config/locales directory. However, this is now moved into the database via these three models:

  • Language
    • id (integer) - The ID.
    • code (string) - Example: en-US.
    • label (string) - Example: English (United States).
    • enabled (boolean) - Useful for enabling or disabling a language.
    • timestamps (datetime) - The standard Rails created_at and updated_at attributes.
  • TranslationKey
    • id (integer) - The ID.
    • name (string) - The unique, namespaced key name as per I18n gem specifications. Example: navigation.home.
    • timestamps (datetime) - The standard Rails created_at and updated_at attributes.
  • Translation
    • id (integer) - The ID.
    • language_id (integer) - The foreign Language ID.
    • key_id (integer) - The foreign TranslationKey ID.
    • value (text) - The translated value for a given language and translation key.
    • timestamps (datetime) - The standard Rails created_at and updated_at attributes.

The Translation model is where you can add unique translations for all languages and translations keys.

Models

This is a bit of an overloaded term but, in this context, models represent the more dynamic data of your application. For example, lets say you have a CMS application where you have a Page model. The Page model might look as follows:

  • Page
    • id (integer) - The record ID.
    • user_id (integer) - The foreign User ID.
    • slug (string) - The URL slug.
    • label (string) - The page label/title.
    • content (text) - The main content of the page.
    • published_at (datetime) - The published time of the page.
    • timestamps - The standard Rails created_at and updated_at attributes.

The translatable parts of this model would be the label and the content. So we would want do two things. The first is to create a new model related to the page for translation purposes. For example:

  • PageTranslation
    • id (integer) - The record ID.
    • language_id (integer) - The foreign Language ID.
    • page_id (integer) - The foreign Page ID.
    • label (string) - The page label/title.
    • content (text) - The main content of the page.
    • timestamps - The standard Rails created_at and updated_at attributes.

Second, we would extract the attributes found in the original Page model so they are in the PageTranslation model for the language instead. Once this is done, you should have the following setup:

  • Page
    • id (integer) - The record ID.
    • user_id (integer) - The foreign User ID.
    • slug (string) - The URL slug.
    • published_at (datetime) - The published time of the page.
    • timestamps - The standard Rails created_at and updated_at attributes.
  • PageTranslation
    • id (integer) - The record ID.
    • language_id (integer) - The foreign Language ID.
    • page_id (integer) - The foreign Page ID.
    • label (string) - The page label/title.
    • content (text) - The main content of the page.
    • timestamps - The standard Rails created_at and updated_at attributes.

Finally, you would simply have to add the following behaviors to both of the models listed above:

class Page < ActiveRecord::Base
  is_translatable attributes: [:label, :content]
end

class PageTranslation < ActiveRecord::Base
  is_translation
end

The model associations, validations, and callbacks are automatically generated for you between the translatable and translation objects.

Tests

To test, do the following:

  1. cd to the gem root.
  2. bundle install
  3. bundle exec rspec spec

Versioning

Read Semantic Versioning for details. Briefly, it means:

  • Patch (x.y.Z) - Incremented for small, backwards compatible bug fixes.
  • Minor (x.Y.z) - Incremented for new, backwards compatible public API enhancements and/or bug fixes.
  • Major (X.y.z) - Incremented for any backwards incompatible public API changes.

Contributions

Read CONTRIBUTING for details.

Credits

Developed by Brooke Kuhlmann at Red Alchemist

License

Copyright (c) 2011 Red Alchemist. Read the LICENSE for details.

History

Read the CHANGELOG for details. Built with Gemsmith.

Something went wrong with that request. Please try again.