Mercurial > gemma

annotate client/docs/dev-translations.md @ 5560:f2204f91d286

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Join the log lines of imports to the log exports to recover data from them. Used in SR export to extract information that where in the meta json but now are only found in the log.
author Sascha L. Teichmann <sascha.teichmann@intevation.de>
date Wed, 09 Feb 2022 18:34:40 +0100
parents 3184210f50e9
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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.
4375
6ebd2d7756d5 client: docs: add hints for translations
Fadi Abbud <fadi.abbud@intevation.de>
parents: 4327
diff changeset
29 - The strings to translate have to be included in the source code and not directly in `.po` files.
4395
3184210f50e9 client: docs: add hint for translation about whitespace
Fadi Abbud <fadi.abbud@intevation.de>
parents: 4377
diff changeset
30 - Use the central defined class `<span class="fix-trans-space"> text<span>` to fix leading and trailing whitespace problem.see:[https://github.com/Polyconseil/vue-gettext/issues/80](https://github.com/Polyconseil/vue-gettext/issues/80).
4375
6ebd2d7756d5 client: docs: add hints for translations
Fadi Abbud <fadi.abbud@intevation.de>
parents: 4327
diff changeset
31 - Check if the development work does not ruin the translation process:
4377
4707fa47284a client:docs: fix typo
Fadi Abbud <fadi.abbud@intevation.de>
parents: 4375
diff changeset
32 Call `make makemessages` --> if `.po` files were generated --> everything is ok.
4375
6ebd2d7756d5 client: docs: add hints for translations
Fadi Abbud <fadi.abbud@intevation.de>
parents: 4327
diff changeset
33 **Notice**: To avoid merge conflicts we push `.po` files into the repository after we synchronize it with the new translations on `weblate`.
4377
4707fa47284a client:docs: fix typo
Fadi Abbud <fadi.abbud@intevation.de>
parents: 4375
diff changeset
34 We do this one time weekly, so you do not have to do this yourself.
4707fa47284a client:docs: fix typo
Fadi Abbud <fadi.abbud@intevation.de>
parents: 4375
diff changeset
35 If it is required to merge the new strings instantly please contact one of the translation managers.
4327
b372fbe15300 client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff changeset
36
b372fbe15300 client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff changeset
37 ## Why was gettext chosen?
b372fbe15300 client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff changeset
38
b372fbe15300 client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff changeset
39 The goal was to internationalize our application for the following
b372fbe15300 client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff changeset
40 languages:
b372fbe15300 client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff changeset
41
b372fbe15300 client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff changeset
42 - EN
b372fbe15300 client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff changeset
43 - DE
b372fbe15300 client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff changeset
44 - SK
b372fbe15300 client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff changeset
45 - HU
b372fbe15300 client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff changeset
46 - HR
b372fbe15300 client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff changeset
47 - BG
b372fbe15300 client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff changeset
48 - RO
b372fbe15300 client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff changeset
49
b372fbe15300 client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff changeset
50
b372fbe15300 client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff changeset
51 ## We chose [vue-gettext](https://github.com/Polyconseil/vue-gettext)
b372fbe15300 client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff changeset
52
b372fbe15300 client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff changeset
53 Rationale:
b372fbe15300 client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff changeset
54 * No other framework supports our preferred translation cycle fully
b372fbe15300 client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff changeset
55 * 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
56 * Relies in parts on well known utilities (xgettext)
b372fbe15300 client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff changeset
57 * Allows phrases as parameters instead of Variables
b372fbe15300 client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff changeset
58 $gettext("Dear Sir") opposed to $("greeting")
b372fbe15300 client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff changeset
59
b372fbe15300 client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff changeset
60 Downsides:
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 - 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
63
b372fbe15300 client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff changeset
64 - [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
65 - [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
66 - [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
67
b372fbe15300 client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff changeset
68 - 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
69 -
b372fbe15300 client: refactor dev documentation
Bernhard Reiter <bernhard@intevation.de>
parents:
diff changeset
70