mongo_translatable¶ ↑

Rails specific I18n model localization meant to tie-in to existing ActiveRecord models, ala Globalize2, backed by MongoDB rather than an RDBMS. May include UI elements, too.

This is a Rails engine.

If you are interested in pure MongoDB localization (your model is MongoMapper::Document, for example), check out github.com/ahe/mongo_translation.

Dependencies¶ ↑

MongoMapper gem for interacting with MongoDB
routing-filter gem for setting up locale in your routes

So far this is only known to work with Rails 2.3.5. Feel free to fork and hack it to work with Rails 3 and let us know about it.

Installation¶ ↑

You need to have mongodb installed and running.

Installing Gem¶ ↑

gem install mongo_translatable

Installing from Source¶ ↑

Get source from git and checkout submodules:
  git clone http://github.com/kete/mongo_translatable.git
  cd mongo_translatable
  git submodule init
  git submodule update

Installing Gem:
  rake gemspec
  gem build {generated gemspec file}
  gem install {generated gem file}

  Running rake will check that you have the dependencies installed correctly.

Usage¶ ↑

In your model…

The MongoTranslatable module is for taking advantage of MongoDB for storing translations of ActiveRecord models. Here is how it works in practice:

class Item < ActiveRecord::Base
  mongo_translate :label
end

Then you can do stuff like this (though you don’t necessarily need to directly, see below)

I18n.locale = :en

item = Item.create(:label => "a label")
p item.locale
"en"

item = Item.find(1)
p item.label
"a label"

item.translate(:label => "etiketissä", :locale => :fi).save

or you could have set I18n.locale = :fi in calling env and dropped locale from args

I18n.locale = :fi
item = Item.find(1)
p item.label
"etiketissä"
p item.locale
"fi"

Mongo_translatable also provides a UI for translations and thus an accompanying controller (translations), views, and helpers that manage CRUD for your model’s translations.

You’ll need to set up the routes for the translations controller for each model in question.

config.routes.rb in your app’s code:

ActionController::Routing::Routes.draw do |map|

map.filter 'locale' # see routing-filter gem
map.resources :items, :has_many => :translations

end

You’ll probably want to add something like this to your application’s app/controllers/application_controller.rb

# borrowed from kete application (http://github.com/kete/kete)
# modified to not rely only on mongo_translatable helpers
before_filter :set_locale
# first take the locale in the url, then the session[:locale],
# then the users locale, finally the default site locale
def set_locale
  if params[:locale] && TranslationsHelper.available_locales.include?(params[:locale])
    I18n.locale = params[:locale]
  elsif session[:locale] && TranslationsHelper.available_locales.include?(session[:locale])
    I18n.locale = session[:locale]
  else
    I18n.locale = I18n.default_locale
  end
  session[:locale] = I18n.locale # need to make sure this persists
end

There are also helpers that you can use in your application for tying into the translations UI. Like so:

<%= available_in_locales_for(@item) %> <%= needed_in_locales_for(@item, :lightbox => true) %>

Finally, you’ll probably want to provide add translation key/values for the UI’s text to your config/locales/your_locale.yml (or .rb). See this gem’s config/locales/en.yml for what to translate. Feel free to contribute back your translations to us for your locale.

See the tests and example code in the included test Rails app under test/full_2_3_5_app_with_tests for more details.

TODOs¶ ↑

• add mongo_mapper “timestamps!” to …::Translation model set up by default

• add “key :user_id, String” to …::Translation model set up by default, probably with required method implemented in owning model

Holding off on these until there is an upgrade path for translation instances that don’t have these values

Note on Patches/Pull Requests¶ ↑

• Fork the project.

• Make your feature addition or bug fix to a branch following this convention: enhancement_[ticket #]_short_description or bugfix_[ticket #]_short_description replace [ticket #] with ticket number from kete.lighthouseapp.com/projects/61584-mongo_translatable

• Add tests for it. This is important so we don’t break it in a future version unintentionally.

• Commit, do not mess with rakefile, version, or history.

• Send me a pull request.

Thank you¶ ↑

Thanks go to Te Reo o Taranaki, Auckland City Libraries, and New Zealand Chinese Association Auckland Branch for funding the work for this project.

Copyright¶ ↑

Copyright © 2010 Horowhenua Library Trust. See LICENSE for details.