Mercurial > gemma
annotate client/docs/dev-translations.md @ 4389:5e38667f740c stretches-for-responsibility
Use stretches as areas of responsibility.
This is heavily based on a patch by Tom Gottfried
(read: >90% of the work was done by Tom).
author | Sascha Wilde <wilde@intevation.de> |
---|---|
date | Thu, 12 Sep 2019 18:13:47 +0200 |
parents | b372fbe15300 |
children | 6ebd2d7756d5 |
rev | line source |
---|---|
4327
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
1 # Translation |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
2 |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
3 ## Workflow |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
4 |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
5 Application -> .po files -> Weblate -> .po files -> Application |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
6 |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
7 ### Depencencies |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
8 |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
9 * `gettext` (e.g. from Debian gettext 0.19.8.1-9) |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
10 * `vue-gettext` and `easygettext` (e.g. via yarn or npm) |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
11 |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
12 In order to extract the messages from the templates call `make makemessages`. |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
13 After that you have the `.po`-file which could be translated. |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
14 |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
15 After translation, `make translations` has to be called to generate the `translations.json`, that is being done automatically via yarn serve/build. |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
16 which is consumed by `vue-gettext`. |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
17 |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
18 The workflow is as follows: |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
19 |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
20 `component.vue ---> /tmp/template.pot ---> app/locale/fr_FR/LC_MESSAGES/app.po ---> app/translations.json` |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
21 |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
22 (taken from the documentation of `vue-gettext`) |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
23 |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
24 ### Some rules to marking strings for translations |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
25 |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
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 |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
27 - passing a value with \`\` to `gettext` leads to break up the translation process (e.g. gettext(\` text to translate ${value} \`)) |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
28 - passing html element (e.g. `<div>`) to gettext is interpreted as string. |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
29 - The strings to translate have to be included in the source code and not directly in `.po` files. |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
30 |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
31 ## Why was gettext chosen? |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
32 |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
33 The goal was to internationalize our application for the following |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
34 languages: |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
35 |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
36 - EN |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
37 - DE |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
38 - SK |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
39 - HU |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
40 - HR |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
41 - BG |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
42 - RO |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
43 |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
44 |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
45 ## We chose [vue-gettext](https://github.com/Polyconseil/vue-gettext) |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
46 |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
47 Rationale: |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
48 * No other framework supports our preferred translation cycle fully |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
49 * The original string can be seen in the source code at the right place. |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
50 * Relies in parts on well known utilities (xgettext) |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
51 * Allows phrases as parameters instead of Variables |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
52 $gettext("Dear Sir") opposed to $("greeting") |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
53 |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
54 Downsides: |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
55 |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
56 - At present (July 2018) there are some annoying issues, which demand quirky solutions: |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
57 |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
58 - [xgettext fails with some .vue files](https://github.com/Polyconseil/vue-gettext/issues/28) which forces us to use `(`, `)` around templates |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
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). |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
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`). |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
61 |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
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. |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
63 - |
b372fbe15300
client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff
changeset
|
64 |