Mercurial > gemma

annotate client/docs/dev-translations.md @ 5736:55892008ec96 default tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Fixed a bunch of corner cases in WG import.
author Sascha Wilde <wilde@sha-bang.de>
date Wed, 29 May 2024 19:02:42 +0200
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