haml-magic-translations

== Magic Translations

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.

=== Installation

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

=== Gettings started with Gettext

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!

=== Examples

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.

=== Extracting strings and merging translations

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.

=== Copyrights

Kriss Kowalik ([e-mail])

potager.org ([e-mail])