Project

General

Profile

Translating » History » Version 46

Dominic Cleal, 08/15/2013 09:40 AM
hyphens

1 6 Lukas Zapletal
h1. Translating for contributors
2 1 Lukas Zapletal
3 7 Lukas Zapletal
h2. General tips
4 7 Lukas Zapletal
5 7 Lukas Zapletal
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. 
6 7 Lukas Zapletal
7 32 Dominic Cleal
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
8 7 Lukas Zapletal
9 7 Lukas Zapletal
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:
10 7 Lukas Zapletal
11 7 Lukas Zapletal
 _('Compute resource') -> "Compute Resource"
12 7 Lukas Zapletal
13 7 Lukas Zapletal
 _('ComputeResource|Description') -> "Description"
14 7 Lukas Zapletal
15 7 Lukas Zapletal
Several models have prefixes in the form something/ or Something:: - you can ignore these. Example:
16 7 Lukas Zapletal
17 7 Lukas Zapletal
 _('Audited/adapters/active record/audit') -> "Audit"
18 7 Lukas Zapletal
19 7 Lukas Zapletal
 _('Audited::Adapters::ActiveRecord::Audit|Associated name') -> "Associated Name"
20 7 Lukas Zapletal
21 6 Lukas Zapletal
h2. Using Transifex
22 6 Lukas Zapletal
23 6 Lukas Zapletal
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).
24 6 Lukas Zapletal
25 6 Lukas Zapletal
Read the tips bellow if you want to start translating now.
26 1 Lukas Zapletal
27 2 Lukas Zapletal
h2. Manually
28 2 Lukas Zapletal
29 2 Lukas Zapletal
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:
30 2 Lukas Zapletal
31 28 Lukas Zapletal
  foreman# rake locale:pack
32 1 Lukas Zapletal
33 2 Lukas Zapletal
or
34 1 Lukas Zapletal
35 7 Lukas Zapletal
  foreman# make -C locale check all-mo
36 2 Lukas Zapletal
37 29 Lukas Zapletal
Note that locale:pack is an alias for gettext:pack which is only avaiable in the development environment.
38 29 Lukas Zapletal
39 1 Lukas Zapletal
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.
40 1 Lukas Zapletal
41 1 Lukas Zapletal
More info about contributing your translation directly is on our [[Contribute]] wiki page. 
42 1 Lukas Zapletal
43 33 Lukas Zapletal
h2. Changing language
44 33 Lukas Zapletal
45 33 Lukas Zapletal
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)
46 33 Lukas Zapletal
47 33 Lukas Zapletal
To quickly change language without going to user settings add ?locale=XX to any Foreman URL. For example visit:
48 33 Lukas Zapletal
49 33 Lukas Zapletal
  http://localhost:3000/?locale=de
50 33 Lukas Zapletal
51 39 Lukas Zapletal
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.
52 33 Lukas Zapletal
53 6 Lukas Zapletal
h1. Translating for developers
54 1 Lukas Zapletal
55 15 Lukas Zapletal
h2. Extracting strings
56 15 Lukas Zapletal
57 15 Lukas Zapletal
There are several rules to follow when marking strings for translations with _("") and similar functions:
58 15 Lukas Zapletal
59 30 Dominic Cleal
 * To translate a string use @_("My string")@
60 45 Lukas Zapletal
 * To translate string with a parameter use @_("String with param: %s") % param@
61 45 Lukas Zapletal
 * To translate string with more than one parameters do not use @_("Params: %s and %s") % [param1, param2]@ which is translator-unfriendly
62 45 Lukas Zapletal
 * Therefore for more than one parameters use @_("Params: %{a} and %{b}") % {:a => foo, :b => bar}@
63 30 Dominic Cleal
 * To mark something for translation (but not translate) use @N_("String")@
64 30 Dominic Cleal
 * 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.
65 45 Lukas Zapletal
 * Plural forms are usually used with one parameter, do not forget to add trailing parameter to it: @n_("%s minute", "%s minutes", @param) % @param@
66 45 Lukas Zapletal
 * When using strings with ERB (e.g. for deface gem), escape properly: n_('Test <%%= %{var1} %%>')
67 30 Dominic Cleal
68 30 Dominic Cleal
h3. Models and columns
69 30 Dominic Cleal
70 30 Dominic Cleal
 * To render name from model use @s_("Modelname|Fieldname")@ - check @./locale/model_attributes.rb@ for all models/fields which are accepted.
71 30 Dominic Cleal
 * 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")
72 30 Dominic Cleal
73 30 Dominic Cleal
h3. Helping translators
74 30 Dominic Cleal
75 1 Lukas Zapletal
 * 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.
76 30 Dominic Cleal
 * 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@
77 1 Lukas Zapletal
 * 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).
78 30 Dominic Cleal
79 31 Dominic Cleal
h3. JavaScript
80 31 Dominic Cleal
81 31 Dominic Cleal
 * Both @_@ and @n_@ functions are available and work in much the same way as in Ruby, with the following exceptions..
82 45 Lukas Zapletal
 * Interpolation of values uses @Jed.sprintf@ on the translated string, so for a single parameter: @Jed.sprintf(_("Foo: %s"), "bar")@
83 45 Lukas Zapletal
 * Multiple parameters must be named: @Jed.sprintf(_("Example: %(foo) %(bar)"), {foo: "a", bar: "b"})@
84 31 Dominic Cleal
85 30 Dominic Cleal
h3. Storing strings
86 30 Dominic Cleal
87 25 Lukas Zapletal
 * Strings get extracted into ./locale/foreman.pot file, model and column names are in ./locale/model_attributes.rb
88 15 Lukas Zapletal
 * Additional Rails strings are in ./config/locale - there is a script to update those from Rails I18N git (branch 3-x).
89 31 Dominic Cleal
 * PO files are converted into JSON objects to be consumed by Jed, stored at @./app/assets/javascripts/locale/$LANG/app.js@
90 15 Lukas Zapletal
 * For more info go here: http://www.yotabanana.com/hiki/ruby-gettext-howto.html
91 15 Lukas Zapletal
92 15 Lukas Zapletal
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
93 15 Lukas Zapletal
94 15 Lukas Zapletal
  foreman# rake locale:find
95 15 Lukas Zapletal
96 21 Lukas Zapletal
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:
97 21 Lukas Zapletal
98 21 Lukas Zapletal
  foreman# make -C locale check -j4
99 21 Lukas Zapletal
  foreman# make -C locale clean
100 15 Lukas Zapletal
101 15 Lukas Zapletal
h2. Generating gettext translate tables
102 15 Lukas Zapletal
103 15 Lukas Zapletal
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.
104 15 Lukas Zapletal
105 15 Lukas Zapletal
To generate gettext MO files, you can do either
106 15 Lukas Zapletal
107 15 Lukas Zapletal
  foreman# rake gettext:pack
108 15 Lukas Zapletal
109 15 Lukas Zapletal
or
110 15 Lukas Zapletal
111 15 Lukas Zapletal
  foreman# make -C locale
112 15 Lukas Zapletal
113 15 Lukas Zapletal
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.
114 15 Lukas Zapletal
115 8 Lukas Zapletal
h2. Adding new language
116 6 Lukas Zapletal
117 2 Lukas Zapletal
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):
118 12 Lukas Zapletal
119 3 Lukas Zapletal
  # cp locale/foreman.pot locale/xx/foreman.po
120 6 Lukas Zapletal
  # vim locale/xx/foreman.po
121 6 Lukas Zapletal
122 12 Lukas Zapletal
Then pull Rails translation strings from upstream 3-x branch:
123 12 Lukas Zapletal
124 46 Dominic Cleal
  # touch config/locales/xx.yml (replace underscores with hyphens)
125 26 Lukas Zapletal
  # script/update-rails-locales.sh
126 12 Lukas Zapletal
127 12 Lukas Zapletal
And add the language to Transifex and Zanata using their web interfaces.
128 2 Lukas Zapletal
129 6 Lukas Zapletal
h2. How to pull translations
130 1 Lukas Zapletal
131 4 Lukas Zapletal
To get updated translations from Transifex you will need account there (https://www.transifex.com) and the tx cli tool.
132 4 Lukas Zapletal
133 4 Lukas Zapletal
On Fedora:
134 4 Lukas Zapletal
135 4 Lukas Zapletal
  # yum -y install transifex-client gettext make intltool
136 4 Lukas Zapletal
137 4 Lukas Zapletal
On Debian:
138 4 Lukas Zapletal
139 4 Lukas Zapletal
  # apt-get install transifex-client gettext make intltool-debian
140 4 Lukas Zapletal
141 4 Lukas Zapletal
Then configure your account:
142 4 Lukas Zapletal
143 4 Lukas Zapletal
  $ cat ~/.transifexrc
144 4 Lukas Zapletal
  [https://www.transifex.net]
145 4 Lukas Zapletal
  hostname = https://www.transifex.net
146 4 Lukas Zapletal
  username = <your_username>
147 4 Lukas Zapletal
  password = <your_password>
148 4 Lukas Zapletal
  token = <should be empty>
149 4 Lukas Zapletal
150 4 Lukas Zapletal
And then prepare new topic branch (because the following command will make new commits to your git repo):
151 4 Lukas Zapletal
152 4 Lukas Zapletal
  git checkout -b update-translations
153 4 Lukas Zapletal
154 43 Dominic Cleal
Do the translation pull, or download the translations "for use" from the web site:
155 4 Lukas Zapletal
156 1 Lukas Zapletal
  make -C locale tx-update
157 43 Dominic Cleal
158 43 Dominic Cleal
Finally re-run the rake task, which will regenerate the JavaScript locale files:
159 43 Dominic Cleal
160 43 Dominic Cleal
  rake locale:find
161 4 Lukas Zapletal
162 4 Lukas Zapletal
And then you can push changes.
163 4 Lukas Zapletal
164 4 Lukas Zapletal
  git push ...
165 9 Lukas Zapletal
166 9 Lukas Zapletal
h2. Not translated
167 9 Lukas Zapletal
168 9 Lukas Zapletal
Some parts are (yet) not translated. These include:
169 9 Lukas Zapletal
170 9 Lukas Zapletal
 * permission names
171 9 Lukas Zapletal
 * predefined role names
172 9 Lukas Zapletal
 * predefined user names
173 20 Dominic Cleal
 * names of settings?
174 11 Dominic Cleal
 * default bookmark names (active, disabled etc)
175 11 Dominic Cleal
 * INTERNAL auth method
176 13 Lukas Zapletal
 * audit entries
177 16 Dominic Cleal
 * reorder the More submenus alphabetically?
178 18 Dominic Cleal
 * predefined install media names ("mirror")
179 18 Dominic Cleal
 * predefined partition table names
180 19 Dominic Cleal
 * template types/kinds
181 1 Lukas Zapletal
 * predefined template names
182 20 Dominic Cleal
 * "Clear" tooltip in scoped_search
183 22 Dominic Cleal
 * any external assert gems, e.g. SPICE HTML 5 console, noVNC?
184 1 Lukas Zapletal
 * column names used in scoped_search
185 1 Lukas Zapletal
 * smart variable/class parameter data and validator types
186 40 Dominic Cleal
 * email notifications/reports
187 41 Dominic Cleal
 * rake tasks
188 41 Dominic Cleal
 * logs?
189 35 Dominic Cleal
190 35 Dominic Cleal
Some parts live in external libraries or vendored assets:
191 36 Dominic Cleal
192 35 Dominic Cleal
 * will_paginate (Dom working on this)
193 38 Dominic Cleal
 ** @page_entries_info .. :model@ has unextracted strings in places, but we can't change this easily without fixing will_paginate
194 35 Dominic Cleal
 * jquery.dataTables (this has its own localisation method)
195 35 Dominic Cleal
 * Puppet log messages, log levels
196 35 Dominic Cleal
 * noVNC, spice-html5
197 10 Lukas Zapletal
198 10 Lukas Zapletal
Some items from the list above will never be translated due to technical reasons or to avoid confusion.