Project

General

Profile

Translating » History » Version 29

Lukas Zapletal, 04/24/2013 08:44 AM

1 6 Lukas Zapletal
h1. Translating for contributors
2 1 Lukas Zapletal
3 7 Lukas Zapletal
h2. General tips
4
5
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
There are model names in the translation strings, you can get the full list here: https://github.com/lzap/foreman/blob/develop/locale/model_attributes.rb
8
9
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
11
 _('Compute resource') -> "Compute Resource"
12
13
 _('ComputeResource|Description') -> "Description"
14
15
Several models have prefixes in the form something/ or Something:: - you can ignore these. Example:
16
17
 _('Audited/adapters/active record/audit') -> "Audit"
18
19
 _('Audited::Adapters::ActiveRecord::Audit|Associated name') -> "Associated Name"
20
21 6 Lukas Zapletal
h2. Using Transifex
22
23
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
25
Read the tips bellow if you want to start translating now.
26 1 Lukas Zapletal
27 2 Lukas Zapletal
h2. Manually
28
29
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
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
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
41
More info about contributing your translation directly is on our [[Contribute]] wiki page. 
42
43 6 Lukas Zapletal
h1. Translating for developers
44 1 Lukas Zapletal
45 15 Lukas Zapletal
h2. Extracting strings
46
47
There are several rules to follow when marking strings for translations with _("") and similar functions:
48
49
 * To translate a string use _("My string")
50
 * To translate string with a parameter use _("String with param: %25s") %25 param
51
 * To translate string with more than one parameters do not use _("Params: %25s and %25s") %25 [param1, param2] which is translator-unfriendly
52
 * Therefore for more than one parameters use _("Params: %25{a} and %25{b}") %25 {:a => foo, :b => bar}
53
 * To mark something for translation (but not translate) use N_("String")
54 26 Lukas Zapletal
 * 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.
55 1 Lukas Zapletal
 * Plural forms are usually used with one parameter, do not forget to add trailing parameter to it: n_("%25s minute", "%25s minutes", @param) %25 @param
56 26 Lukas Zapletal
 * To render name from model use s_("Modelname|Fieldname") - check ./locale/model_attributes.rb for all models/fields which are accepted.
57 15 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.
58
 * 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
59
 * 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).
60
 * Strings get extracted into ./locale/foreman.pot file, model and column names are in ./locale/model_attributes.rb
61 25 Lukas Zapletal
 * 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")
62 15 Lukas Zapletal
 * Additional Rails strings are in ./config/locale - there is a script to update those from Rails I18N git (branch 3-x).
63
 * For more info go here: http://www.yotabanana.com/hiki/ruby-gettext-howto.html
64
65
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
66
67
  foreman# rake locale:find
68
69 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:
70
71
  foreman# make -C locale check -j4
72
  foreman# make -C locale clean
73 15 Lukas Zapletal
74
h2. Generating gettext translate tables
75
76
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.
77
78
To generate gettext MO files, you can do either
79
80
  foreman# rake gettext:pack
81
82
or
83
84
  foreman# make -C locale
85
86
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.
87
88 8 Lukas Zapletal
h2. Adding new language
89 6 Lukas Zapletal
90 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):
91 12 Lukas Zapletal
92 3 Lukas Zapletal
  # cp locale/foreman.pot locale/xx/foreman.po
93 6 Lukas Zapletal
  # vim locale/xx/foreman.po
94
95 12 Lukas Zapletal
Then pull Rails translation strings from upstream 3-x branch:
96
97 26 Lukas Zapletal
  # touch config/locale/xx.yml
98
  # script/update-rails-locales.sh
99 12 Lukas Zapletal
100
And add the language to Transifex and Zanata using their web interfaces.
101 2 Lukas Zapletal
102 6 Lukas Zapletal
h2. How to pull translations
103 1 Lukas Zapletal
104 4 Lukas Zapletal
To get updated translations from Transifex you will need account there (https://www.transifex.com) and the tx cli tool.
105
106
On Fedora:
107
108
  # yum -y install transifex-client gettext make intltool
109
110
On Debian:
111
112
  # apt-get install transifex-client gettext make intltool-debian
113
114
Then configure your account:
115
116
  $ cat ~/.transifexrc
117
  [https://www.transifex.net]
118
  hostname = https://www.transifex.net
119
  username = <your_username>
120
  password = <your_password>
121
  token = <should be empty>
122
123
And then prepare new topic branch (because the following command will make new commits to your git repo):
124
125
  git checkout -b update-translations
126
127
Finally do the translation pull
128
129
  make -C locale tx-update
130
131
And then you can push changes.
132
133
  git push ...
134 9 Lukas Zapletal
135
h2. Not translated
136
137
Some parts are (yet) not translated. These include:
138
139 27 Dominic Cleal
 * all JavaScript resources (components etc), #2420
140 9 Lukas Zapletal
 * permission names
141
 * predefined role names
142
 * predefined user names
143 20 Dominic Cleal
 * names of settings?
144 11 Dominic Cleal
 * default bookmark names (active, disabled etc)
145
 * INTERNAL auth method
146 13 Lukas Zapletal
 * audit entries
147 14 Dominic Cleal
 * will_paginate (Dom working on this)
148 16 Dominic Cleal
 * reorder the More submenus alphabetically?
149 18 Dominic Cleal
 * predefined install media names ("mirror")
150
 * predefined partition table names
151 19 Dominic Cleal
 * template types/kinds
152 1 Lukas Zapletal
 * predefined template names
153 20 Dominic Cleal
 * "Clear" tooltip in scoped_search
154 22 Dominic Cleal
 * any external assert gems, e.g. SPICE HTML 5 console, noVNC?
155 23 Dominic Cleal
 * Puppet log messages, log levels
156
 * column names used in scoped_search
157 10 Lukas Zapletal
158
Some items from the list above will never be translated due to technical reasons or to avoid confusion.