i18n.md

Internationalization

Hammer uses fast gettext for string translations. Most of the localization magic is done for you in hammer already. If you want your plugin to support i18n it needs to register it's translation domain at hammer's i18n module:

require 'hammer_cli/i18n'

# namespace your i18n module
module HammerCLIAwesome
  module I18n

    # create a locale domain for your plugin
    class LocaleDomain < HammerCLI::I18n::LocaleDomain

      # lists all your source files that use _()
      def translated_files
        Dir.glob(File.join(File.dirname(__FILE__), '../**/*.rb'))
      end

      # returns path to your locale directory
      # it's typically "locale" in the root of your plugin
      def locale_dir
        File.join(File.dirname(__FILE__), '../../locale')
      end

      # name for your language domain
      def domain_name
        'hammer-cli-awesome'
      end

      # type of the translation files, 'mo' files are default
      # you can also use 'po' and 'yaml' files for testing purposes
      def type
        :mo
      end

    end

  end
end

# register the domain
HammerCLI::I18n.add_domain(HammerCLIAwesomePlugin::I18n::LocaleDomain.new)

Then you have to export strings, translate them and place the files in a directory structure.

Typical directory structure for translation files look like this:

locale
├── de
│   ├── hammer-cli-awesome.po
│   └── LC_MESSAGES
│       └── hammer-cli-awesome.mo
├── en
│   ├── hammer-cli-awesome.po
│   └── LC_MESSAGES
│       └── hammer-cli-awesome.mo
└── hammer-cli-awesome.pot

You can re-use Rake tasks and Makefile targets for extracting translations and integration with transifex that hammer provides. To do that, add following lines to the plugin's Rakefile:

require "hammer_cli_awesome/version"
require "hammer_cli_awesome/i18n"
require "hammer_cli/i18n/find_task"
HammerCLI::I18n::FindTask.define(HammerCLIAwesome::I18n::LocaleDomain.new, HammerCLIAwesome.version)

and create locale/Makefile with following content:

DOMAIN = hammer-cli-awesome
VERSION = $(shell bundle exec ruby -C ../ -e 'require "rubygems"; spec = Gem::Specification::load("../hammer_cli_awesome.gemspec"); puts spec.version')
MAIN_MAKEFILE = $(shell bundle exec ruby -C ../ -e 'require "hammer_cli"; puts HammerCLI::I18n.main_makefile')

include $(MAIN_MAKEFILE)

Make sure you have a project created in transifex and correct configuration stored in your plugins repository (example config file).

Calling make -C ./locale tx-update will then extract new strings, update .po and .mo files and commit the changes.

Translation tips

When writing code with translations make sure you keep two following rules:

1. Don't use variables directly in the strings and make formatting substitutions outside the gettext function _("...").

# WRONG
puts _("Hello #{name}")
puts _("Hello %s" % name)
# CORRECT
puts _("Hello %s") % name

2. Use named placeholders when there is more than one replacement. Languages differ in their word order.

# WRONG
puts _("Hello %s, it is %s" % [name, day])
# CORRECT
puts _("Hello %{name}, it is %{day}") % {:name => name, :day => day}

3. Don't use newlines in the gettext function. Strings with newlines are not extracted correctly.

# WRONG
puts _("TODO: \n - make dishes\n - do shopping")
# CORRECT
puts _("TODO:") +
     "\n - " + _("make dishes") +
     "\n - " + _("do shopping")

4. It's recommended to use punctuation at the end of sentences.

# CORRECT
puts _("Hello %s") % name
# RECOMMENDED
puts _("Hello %s.") % name

5. Try setting :mark_translated: true to identify gaps in your translations. This will wrap all translated strings with angle brackets '>message<'.