Mercurial > gemma
comparison client/docs/dev-translations.md @ 4327:b372fbe15300
client: refactor dev documentation
* Split out general considerations with rationales for decisions
into a file on its own, the same with how to handle translations.
* Add an overview document.
author | Bernhard Reiter <bernhard@intevation.de> |
---|---|
date | Wed, 04 Sep 2019 16:45:32 +0200 |
parents | |
children | 6ebd2d7756d5 |
comparison
equal
deleted
inserted
replaced
4325:124a5a7fe8d6 | 4327:b372fbe15300 |
---|---|
1 # Translation | |
2 | |
3 ## Workflow | |
4 | |
5 Application -> .po files -> Weblate -> .po files -> Application | |
6 | |
7 ### Depencencies | |
8 | |
9 * `gettext` (e.g. from Debian gettext 0.19.8.1-9) | |
10 * `vue-gettext` and `easygettext` (e.g. via yarn or npm) | |
11 | |
12 In order to extract the messages from the templates call `make makemessages`. | |
13 After that you have the `.po`-file which could be translated. | |
14 | |
15 After translation, `make translations` has to be called to generate the `translations.json`, that is being done automatically via yarn serve/build. | |
16 which is consumed by `vue-gettext`. | |
17 | |
18 The workflow is as follows: | |
19 | |
20 `component.vue ---> /tmp/template.pot ---> app/locale/fr_FR/LC_MESSAGES/app.po ---> app/translations.json` | |
21 | |
22 (taken from the documentation of `vue-gettext`) | |
23 | |
24 ### Some rules to marking strings for translations | |
25 | |
26 - `gettext` must be called only in javascript part. For html part we use `<translate>` and `<v-translate>` to make sure that `makemessages` marks the strings correctly | |
27 - passing a value with \`\` to `gettext` leads to break up the translation process (e.g. gettext(\` text to translate ${value} \`)) | |
28 - passing html element (e.g. `<div>`) to gettext is interpreted as string. | |
29 - The strings to translate have to be included in the source code and not directly in `.po` files. | |
30 | |
31 ## Why was gettext chosen? | |
32 | |
33 The goal was to internationalize our application for the following | |
34 languages: | |
35 | |
36 - EN | |
37 - DE | |
38 - SK | |
39 - HU | |
40 - HR | |
41 - BG | |
42 - RO | |
43 | |
44 | |
45 ## We chose [vue-gettext](https://github.com/Polyconseil/vue-gettext) | |
46 | |
47 Rationale: | |
48 * No other framework supports our preferred translation cycle fully | |
49 * The original string can be seen in the source code at the right place. | |
50 * Relies in parts on well known utilities (xgettext) | |
51 * Allows phrases as parameters instead of Variables | |
52 $gettext("Dear Sir") opposed to $("greeting") | |
53 | |
54 Downsides: | |
55 | |
56 - At present (July 2018) there are some annoying issues, which demand quirky solutions: | |
57 | |
58 - [xgettext fails with some .vue files](https://github.com/Polyconseil/vue-gettext/issues/28) which forces us to use `(`, `)` around templates | |
59 - [translations in attributes](https://github.com/Polyconseil/vue-gettext/issues/9) which leaves us with either interpolating in templates with `<translate></translate>` or use computed properties in Vue components (cf. Login component). | |
60 - [inconsistent white space handling](https://github.com/Polyconseil/vue-gettext/issues/80) if you need a white space preserved before the translated tag, use `<span v-translate class="fix-trans-space">to be translated</a>` (see `src/assets/application.sass`). | |
61 | |
62 - Is dependent on external (=non JS) tools (`xgettext`) which are not able to consume `.vue`-files directly, which in turn leads to unexpected behaviour. | |
63 - | |
64 |