Mercurial > gemma

changeset 168:e4e4a0e6338e

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
docs: Added a developer documentation Developer documentation was added. At present the rationale for why we chose vue-gettext is documented. Alongside comes the explanation of how to use it and what quirks vue-gettext has.
author Thomas Junk <thomas.junk@intevation.de>
date Fri, 06 Jul 2018 12:38:11 +0200
parents a6d7ee20fc96
children 9fcfccb18b16
files client/README.md client/docs/developer.md
diffstat 2 files changed, 53 insertions(+), 0 deletions(-) [+]
line wrap: on
line diff
--- a/client/README.md	Fri Jul 06 12:09:08 2018 +0200
+++ b/client/README.md	Fri Jul 06 12:38:11 2018 +0200
@@ -33,6 +33,8 @@
   * Extract Messages via `make makemessages`
   * Translations are converted via `make translations`
 
+  For more information see [developer documentation](./docs/developer.md)
+
 * Tests
   * Unit tests are started via `yarn test:unit`
   * e2e tests are started via `yarn test:e2e`
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/client/docs/developer.md	Fri Jul 06 12:38:11 2018 +0200
@@ -0,0 +1,51 @@
+# Translation
+
+We want to internationalize our application for the following
+languages:
+
+* EN
+* DE
+* SK
+* HU
+* HR
+* RS
+* BiH
+* BG
+* RO
+* UA
+
+## Our preferred translation cycle is as follows:
+
+Application -> .po files -> Weblate -> .po files -> Application
+
+There are several possibilities to achieve this goal.
+
+## We chose [vue-gettext](https://github.com/Polyconseil/vue-gettext)
+
+    Rationale:
+    * No other framework supports our preferred translation cycle fully
+    * Relies in parts on well known utilities (xgettext)
+    * Allows phrases as parameters instead of Variables
+      $gettext("Dear Sir") opposed to $("greeting")
+
+Downsides:
+* At present (July 2018) there are some annoying issues, which demand quirky solutions:
+
+  * [xgettext fails with some .vue files](https://github.com/Polyconseil/vue-gettext/issues/28) which forces us to use `(`, `)` around templates
+  *  [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).
+* Is dependend on external (=non JS) tools (`xgettext`) which are not able to consume `.vue`-files directly, which in turn leads to unexpected behaviour.
+*
+
+
+## Commands
+
+In order to extract the messages from the templates call `make makemessages`.
+After that you have the `.po`-file which could be translated.
+After translation, you have to call `make translations` to generate the `translations.json`
+which is consumed by `vue-gettext`.
+
+The workflow is as follows:
+
+`component.vue ---> /tmp/template.pot ---> app/locale/fr_FR/LC_MESSAGES/app.po ---> app/translations.json`
+
+(taken from the documentation of `vue-gettext`)