This plugin provides “magical translations” in your .haml files. What does it mean? It’s mean that all your raw texts in templates will be automatically translated by GetText, FastGettext or Gettext backend from I18n. No more complicated translation keys and ugly translation methods in views. Now you can only write in your language, nothing more. At the end of your work you can easy find all phrases to translate and generate .po files for it. This type of files are also more readable and easier to translate, thanks to it you save your time with translations.

You can install haml-magic-translations directly from rubygems:

gem install haml-magic-translations

…or as Ruby on Rails plugin:

script/plugin install https://github.com/potager/haml-magic-translations

or

rails plugin install https://github.com/potager/haml-magic-translations

To use automatical translations you have to using new I18n with Gettext backend, GetText or FastGettext, properly installed and configured. To enable plugin you have to do following things:

Haml::MagicTranslations.enable(:i18n) # this backend is used by default

Available backends are :i18n, :gettext and :fast_gettext

Now you have to add path to all your .po files with locales. Eg. for i18n backend it will be something like:

I18n.load_path += Dir["path/to/your/locales/*.{po}"]

And that’s all. Now you can enjoy automatically translations in your .haml files!

Now you can write what you want, and at the end of work you will easy found all phrases to translate. Check out following example:

%p This is my simple dummy text.
%p And more lorem ipsum...
%p= link_to _("This will be also translated"), "#"

Those translations are allso allowing you to use standard Haml interpolation. You can easy write:

%p This is my text with #{"interpolation".upcase}... Great, isn't it?
%p
  This multiline string
  Will be also translated

And text from codes above will be stored in .po files as:

# File test1.haml, line 1
msgid "This is my simple dummy text"
msgstr "This is my dummy translation of dummy text"

# File test2.haml, line 1
msgid "This is my text with %s... Great, isn't it?"
msgstr "Next one %s translation!"

# File test4.haml, line 3
msgid "This multiline string"
msgstr ""

# File test2.haml, line 4
msgid "Will be also translated"
msgstr ""

Notice that in multiline strings each line is translated separatelly.

Generator for .po files also includes information where your phrases are placed in filesystem. Thanks to it you don’t forget about any even small word to translate.

In order to extract translatable strings and merge with existing translation, this gem provides an Haml parser for GetText::Tools::XGetText. This requires gettext >= 2.3 to be available.

With gettext >= 3, Rake tasks can be defined as follow:

require 'gettext/tools/task'
require 'haml/magic_translations/xgettext/haml_parser'

GetText::Tools::XGetText.add_parser(Haml::MagicTranslations::XGetText::HamlParser)
GetText::Tools::Task.define do |task|
  task.spec = Gem::Specification.load('coquelicot.gemspec')
  task.files = Dir.glob('views/**/*.{rb,haml}') << 'lib/my_project.rb'
end

This will add a gettext:po:update task that will update PO files that can be found in the po directory.

Kriss Kowalik (kriss.kowalik@gmail.com)

potager.org (jardiniers@potager.org)