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: “`ruby 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: ruby 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: “`make
DOMAIN = hammer-cli-awesome VERSION = $(shell bundle exec ruby -e
'require “rubygems”; spec =
Gem::Specification::load(“../hammer_cli_awesome.gemspec”); puts
spec.version') MAIN_MAKEFILE = $(shell bundle exec ruby -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 _("...")
.
ruby # 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. ruby # 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. ruby # 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.
ruby # 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<'.