# Translation

## Workflow

Application -> .po files -> Weblate -> .po files -> Application

### Depencencies

 * `gettext` (e.g. from Debian gettext 0.19.8.1-9)
 * `vue-gettext` and `easygettext` (e.g. via yarn or npm)

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, `make translations` has to be called to generate the `translations.json`, that is being done automatically via yarn serve/build.
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`)

### Some rules to marking strings for translations

- `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
- passing a value with \`\` to `gettext` leads to break up the translation process (e.g. gettext(\` text to translate ${value} \`))
- passing html element (e.g. `<div>`) to gettext is interpreted as string.
- The strings to translate have to be included in the source code and not directly in `.po` files.
- 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).
- Check if the development work does not ruin the translation process:
  Call `make makemessages` --> if `.po` files were generated --> everything is ok.
  **Notice**: To avoid merge conflicts we push `.po` files into the repository after we synchronize it with the new translations on `weblate`.
  We do this one time weekly, so you do not have to do this yourself.
  If it is required to merge the new strings instantly please contact one of the translation managers.

## Why was gettext chosen?

The goal was to internationalize our application for the following
languages:

- EN
- DE
- SK
- HU
- HR
- BG
- RO


## We chose [vue-gettext](https://github.com/Polyconseil/vue-gettext)

    Rationale:
    * No other framework supports our preferred translation cycle fully
    * The original string can be seen in the source code at the right place.
    * 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).
  - [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`).

- Is dependent on external (=non JS) tools (`xgettext`) which are not able to consume `.vue`-files directly, which in turn leads to unexpected behaviour.
-