h1. Translating for contributors

h2. General tips

It is important not to change punctuation and whitespace. For example if the English string is "blah." it must be translated as "xyz." with the dot at the end. The same for an extra space - e.g. "blah " must be "xyz ". Although we try to eliminate all the extra spaces, there are rare cases where we need them. There is a checker (pofilter) which is executed regularly by developers to catch and fix all these types of mistakes. 

There are model names in the translation strings, you can get the full list here: https://github.com/theforeman/foreman/blob/develop/locale/model_attributes.rb

These model names are in two formats: "Model name" (name of the database table) and "Modelname|Column name" for column name. Here are few examples how to translate them:

 _('Compute resource') -> "Compute Resource"

 _('ComputeResource|Description') -> "Description"

Several models have prefixes in the form something/ or Something:: - you can ignore these. Example:

 _('Audited/adapters/active record/audit') -> "Audit"

 _('Audited::Adapters::ActiveRecord::Audit|Associated name') -> "Associated Name"

h2. Using Transifex

Go to https://www.transifex.com/projects/p/foreman and register/login. Then you can use the Transifex interface to do all translations. The project on Transifex automatically updates when we add new strings into git. Foreman team regularly downloads new translations to the develop branch in git as well, therefore there is no action needed when you finish with translations. It will be pulled eventually (e.g. before the next release).

Read the tips bellow if you want to start translating now.

h2. Manually

If you prefer, you can edit PO files directly using your preferred editor. Please make sure the encoding of the files is UTF-8. It is also recommended to test your translations before submitting a Pull Request on the github using either:

  foreman# rake locale:pack

or

  foreman# make -C locale check all-mo

Note that locale:pack is an alias for gettext:pack which is only avaiable in the development environment.

The above command should not print any error message. Also you should start Foreman UI and see if your translations do fit (sometimes longer strings can wrap or even break the UI). If you start Foreman in the production mode, you need to do one of the above commands every time you change your translation. In the development mode, you only need to restart Foreman to see the changes.

Note: For CentOS/RHEL6 systems, you need the following packages : 

  gettext make

More info about contributing your translation directly is on our [[Contribute]] wiki page. 

h2. Changing language

To change your language, to to User account page and change our language from Browser default to your preferred one. (This is work in progress)

To quickly change language without going to user settings add ?locale=XX to any Foreman URL. For example visit:

  http://localhost:3000/?locale=de

and Foreman will remember the language setting for the whole session. Note: The current user needs to have "Browser Locale" set in the account settings, otherwise this will not work.

h1. Translating for developers

h2. Extracting strings

There are several rules to follow when marking strings for translations with _("") and similar functions:

 * To translate a string use @_("My string")@

 * To translate string with a parameter use @_("String with param: %s") % param@

 * To translate string with more than one parameters do not use @_("Params: %s and %s") % [param1, param2]@ which is translator-unfriendly

 * Therefore for more than one parameters use @_("Params: %{a} and %{b}") % {:a => foo, :b => bar}@

 * Note that parameters are not translated. Variables should not contain text that needs translation.

 * To mark something for translation (but not translate) use @N_("String")@

 * To use plural form use @n_("One", "Two", number)@ - note this function always accepts three parameters as the base language is usually English but translators are able to define as many plural forms as they need.

 * Plural forms are usually used with one parameter, do not forget to add trailing parameter to it: @n_("%s minute", "%s minutes", @param) % @param@

 * When using strings with ERB (e.g. for deface gem), escape properly: n_('Test <%%= %{var1} %%>') % { :var1 => "xxx" }

 * Note that gettext does not extract from interpolation - this will not work: "blah #{_('key')} blah"

h3. Models and columns

 * To render name from model use @s_("Modelname|Fieldname")@ - check @./locale/model_attributes.rb@ for all models/fields which are accepted.

 * All our form helpers have been enriched and understand model and column names - if the field is in the model_attribute.rb (above), it does not need to be translated explicitly (e.g. text_f f, :name is enough and will be translated to "Modelname|Name")

h3. Exceptions

We have defined two exceptions `Foreman::Exception` and `Foreman::WrappedException`. Both are generic exceptions which are i18n-friendly. Use the following style to properly format messages:

<pre>

  raise ::Foreman::Exception.new(N_("Localized error message"))

  raise ::Foreman::Exception.new(N_("Localized error message: %s", substring_message))

  raise ::Foreman::Exception.new(N_("Localized error message %{a} and %{b}", {:a => a, :b => b}))

  raise ::Foreman::WrappedException.new(wrapped_exception, N_("Localized error message"))

</pre>

It is _very_ important to use `N_` and not the simple `_` (underscore) function and to avoid using Ruby string interpolation, because those exceptions prints out error code which are generated from exception class names and main (untranslated) messages. There is also a rake task that goes through our codebase and generates list of all possible error codes which we keep on the wiki page [[ErrorCodes]].

If an exception is needed to be untranslated, it can be used without underscore functions. Beware, that parameters can be also passed, but Ruby only support hash interpolation:

<pre>

  raise ::Foreman::Exception.new("This works fine")

  raise ::Foreman::Exception.new("This works fine %{foo}", {:foo => "too"})

  raise ::Foreman::Exception.new("But this %{s} will not work", 'example')

</pre>

Please note the difference between using Ruby interpolation (@%@) vs passing options into exception (@,@). In the first case, the ERF error code is miscalculated for different outputs, the latter is correct - any input leads to the same error code:

<pre>

> ::Foreman::Exception.new(N_("Localized error message: %s" % "Incorrect usage 1")).code

=> "ERF42-5336"

> ::Foreman::Exception.new(N_("Localized error message: %s" % "Incorrect usage 2")).code

=> "ERF42-1122"

> ::Foreman::Exception.new(N_("Localized error message: %s"), "Correct usage 1").code

=> "ERF42-6923"

> ::Foreman::Exception.new(N_("Localized error message: %s"), "Correct usage 2").code

=> "ERF42-6923"

</pre>

h3. Helping translators

 * Do not break strings with newlines because then the strings have many whitespace and it looks confusing for translators like "blah    \\n     blah". If you must separate string on several lines, you can use HEREDOC or you can contatenate strings like "line1" + "line2" because Ruby Gettext detects them both.

 * If you want to leave a note to the translator, just drop a comment before the string in the format of @# TRANSLATORS: your comment here@

 * Note that all HEREDOC strings are automatically extracted, when adding API documentation descriptions via HEREDOC, leave a message to translators not to translate these (API documentation will not be translated at the moment).

h3. JavaScript

 * Both @__@ and @n__@ functions are available and work in much the same way as in Ruby, with the following exceptions..

 * Interpolation of values uses @Jed.sprintf@ on the translated string, so for a single parameter: @Jed.sprintf(__("Foo: %s"), "bar")@

 * Multiple parameters must be named: @Jed.sprintf(__("Example: %(foo) %(bar)"), {foo: "a", bar: "b"})@

h3. Storing strings

 * Strings get extracted into ./locale/foreman.pot file, model and column names are in ./locale/model_attributes.rb

 * Additional Rails strings are provided by the rails-i18n gem

 * PO files are converted into JSON objects to be consumed by Jed, stored at @./app/assets/javascripts/locale/$LANG/app.js@

 * For more info go here: http://www.yotabanana.com/hiki/ruby-gettext-howto.html

From time to time it is good to extract strings and update translations with incoming strings, so translators are able to work on them. We usually do this before releases, but it is good idea to do this on a weekly/monthly basis. For string extractions, please *do not* use rake gettext:find but use

  foreman# rake locale:find

because it also extracts model names and columns and filters them plus it adds some notes to translators (see locale:find_model rake task). Although locale:find does some checks for malformed strings, it is good idea to run additional pofilter check which is able to find many mistakes like trailing whitespace and others:

  foreman# make -C locale check -j4

  foreman# make -C locale clean

h2. Generating gettext translate tables

For production environment, you need to compile PO files into binary translate tables (MO files). This is *not needed* for development or test environments as in these modes Foreman reads PO files directly.

To generate gettext MO files, you can do either

  foreman# rake gettext:pack

or

  foreman# make -C locale

Both tools generate the same result, the latter is a bit faster and allows additional checks (see locale/Makefile targets). If you install from distribution packages, you do not need to run this because everything has been pre-compiled already.

h2. Adding new language

Adding new language into Foreman is easy. You need to take two steps - first of all create new gettext PO file as a copy from POT and edit the header (at least set plural configuration):

  # cp locale/foreman.pot locale/xx/foreman.po

  # vim locale/xx/foreman.po

And add the language to Transifex using their web interface.

h2. How to pull translations

To get updated translations from Transifex you will need account there (https://www.transifex.com) and the tx cli tool.

On Fedora:

    # yum -y install transifex-client gettext make intltool

On Debian:

    # apt-get install transifex-client gettext make intltool-debian

Then configure your account:

    $ cat ~/.transifexrc

[https://www.transifex.com]

hostname = https://www.transifex.com

username = <your_username>

password = <your_password>

token =

Note that token is empty, should not be set. Then prepare new topic branch (because the following command will make new commits to your git repo):

    git checkout -b update-translations

Before you start check if there are new languages on the Transifex site that are worth adding into Foreman (are close to 100 %). You need to download all po files manually and create the proper directory structure. Make sure the PO file header is correct, specifically plural settings and when necessary edit .tx/config file to add a mapping there.

Now you can update translations from Transiflex and Rails i18n upstream, regenerate the JavaScript locale files, extract new strings (but throw away PO files merge - we do not need that when using Transifex.com):

    make -C locale tx-update

Note: run this command in the Foreman git root directory.

Check git log, you should have few new commits stacked, all with i18n prefix. Then you can push changes.

    git push

h2. Not extracted

Some parts are (yet) not extracted for translation. These include:

 * "Clear" tooltip in scoped_search

 * any external assert gems, e.g. SPICE HTML 5 console, noVNC?

 * column names used in scoped_search

A number of other items are "filed as bugs":http://projects.theforeman.org/projects/foreman/issues?utf8=%E2%9C%93&set_filter=1&f[]=status_id&op[status_id]=o&f[]=category_id&op[category_id]=%3D&v[category_id][]=57&f[]=&c[]=tracker&c[]=status&c[]=priority&c[]=subject&c[]=author&c[]=assigned_to&c[]=updated_on&c[]=category&c[]=fixed_version&c[]=position&group_by=.

Things that perhaps does not need to be translated:

 * rake tasks

 * logs?

Some parts live in external libraries or vendored assets:

 * will_paginate (Dom working on this)

 ** @page_entries_info .. :model@ has unextracted strings in places, but we can't change this easily without fixing will_paginate

 * jquery.dataTables (this has its own localisation method)

 * Puppet log messages, log levels

 * noVNC, spice-html5