Doc: added help on translating Butaca
[butaca:butaca.git] / TRANSLATING.md
1 # Translating Butaca into your language #
2
3 The easiest way to translate Butaca is by using [Transifex][1]. The process
4 should be straight-forward:
5
6  * You will need a transifex account in order to collaborate:
7    create one at [https://www.transifex.net/plans/signup/free/][2].
8  * After that, you need to request the creation of a translation
9    team by going to [https://www.transifex.net/projects/p/butaca/teams/][3]
10    and clicking on *"Request a new team"*
11    * Alternatively, if a translation team for your language is already there,
12      you can request to join the team
13  * You will see that there are two *"resources"*. One of them contains all the
14    translatable strings used in the application, and the other one contains
15    the strings used in the description in the *Nokia Store*.
16  * After clicking on the resource, you will be able to start translating it
17    by clicking on the *"Translate now"* button.
18
19 All strings should have the original source, in English, and a comment explaining
20 in which content they are used (also warning you if there's a limited room for the
21 string). Anyway, if you are unsure about how to translate a string and the comment
22 doesn't help, file a bug in our [bug tracker][4], ensuring you use the *l10n* label
23 on it.
24
25 # Testing your translations #
26
27 If you want to test the translations you've provided, feel free to [contact me][5]
28 and request me a *deb* package. Or, if you prefer, you can do it yourself, as
29 explained in the next section.
30
31 ## Testing your translations. The DIY way ##
32
33 If you want to test the translations you've provided:
34
35  * Download the translation clicking on *"Download for use"*
36  * If it already exists, and you're modifying it, simply replace
37    the file `butaca.CODE.ts` (where `CODE` represents your language) with
38    the one you just downloaded from *Transifex*.
39  * If it didn't exist, you'll have to copy it following the same name convention,
40    and then instruct `qmake` to load it, by:
41    * Open `src.pro`, go to the `TRANSLATIONS` section, and add your language
42    * Run `lrelease` on it to get the `butaca.CODE.qm` file
43    * Open `res.qrc` and add `butaca.CODE.qm` (it will be updated by `qmake`)
44  * To manually test it on a device, build a package (as instructed in [HACKING](HACKING.md)),
45    and run Butaca with `$LANG=CODE /path/to/butaca`
46  * To test it under *Qt Creator*, go to the *Projects* tab, and in the *run* configuration
47    (either *Harmattan* or *Qt Simulator* targets), go to the *System Environment* section,
48    and set the *LANG* environment variable to your language.
49
50 ### Example: Testing an Italian translation ###
51
52 Download the translated `butaca.ts` resource. The suggested name is *for_use_butaca_butacats_it.ts*,
53 and move that file into `src/l10n/butaca.it.ts`, in the directory where you downloaded Butaca.
54 Run
55
56     $lrelease src/l10n/butaca.it.ts -qm src/l10n/butaca.it.qm
57
58 Add `butaca.it.ts` to `src.pro`. The patch would look like:
59
60       <file>l10n/butaca.pt.qm</file>
61     + <file>l10n/butaca.it.qm</file>
62       <file>qml/MovieView.qml</file>
63
64 Add `butaca.it.qm` to `res.qrc`. The patch for would look like:
65
66     -    l10n/butaca.pt.ts
67     +    l10n/butaca.pt.ts \
68     +    l10n/butaca.it.ts
69
70 If you created the package manually, copy it to the device and install it, and then launch Butaca from the command line:
71
72     $LANG=it /path/to/butaca
73
74 If you are using *Qt Creator*, set the *LANG* environment to *it* before running the app.
75
76 [1]: https://www.transifex.net
77 [2]: https://www.transifex.net/plans/signup/free/
78 [3]: https://www.transifex.net/projects/p/butaca/teams/
79 [4]: https://github.com/spenap/butaca/issues
80 [5]: mailto:spena@igalia.com