# General considerations

## We chose [vuejs](https://vuejs.org/)

Vue is a modern framework for webdevelopment.
It offers a very homogenous ecosystem (vuejs, vuecli, vue-router vuex) combined with up to date fontend rendering techniques like virtual DOM.

## We chose [vue cli](https://cli.vuejs.org/)

Vue cli allows a good jumpstart for a vuejs project.
There is no manual boilerplate to write. Everything is in place and already wired. The skeleton is easy extendable and in contrast to
other frameworks (i.e. create-react-app) there is no "eject" for further customization necessary.

Configuration:

- Babel
- Router
- Vuex
- CSSPreprocessor
- Linter+Unit
- Testing+E2E
- Testing
- No Typescript (No advantages)
- No PWA (IE11 compatibility makes more modern approaches unavailable)

- SASS as CSS Preprocessor (widely used, allows programmatic CSS, familarity)
- Eslint + Prettier (Rationale below)
- Lint on Save
- Jest as Unittesting framework (zeroconf, ease of use) [productpage](https://jestjs.io/
- Nightwatch (Seleniumbased, familarity with selenium, Chromedriver ootB)

Everything in dedicated config files

## We chose [vuex](https://vuex.vuejs.org/guide/)

Vuex is the store component of vuejs. For medium to complex applications it is reasonable to centralize state globally, to make every possible interaction with state transparent. Interactions with state become traceable in contrast to chains built with components and properties.

Perhaps it is resonable to configure [strict mode](https://vuex.vuejs.org/api/#strict) in the future (for development). State changes should only be allowed through `actions` and `mutations`.

Besides traceability vuex allows to dumb down components.

## We chose [prettier](https://prettier.io/) in combination with [eslint](https://eslint.org/)

To enforce tight styling guidelines (e.g. avoidance of problems with [semicolons](https://eslint.org/docs/rules/no-unexpected-multiline)) and strict formatting rules, prettier was chosen. Prettier as a plugin is widey supported:

- [vim](https://github.com/prettier/vim-prettier)
- [emacs](https://github.com/prettier/prettier-emacs)
- [VSCode](https://github.com/prettier/prettier-vscode)

On top, there is [pretty quick](https://www.npmjs.com/package/pretty-quick) a tool, which allows autmatically solving linting issues for you.

Overall prettier makes styling issues a non-issue: You get achieve styled code as a result. Code which is automatically formatted is easier to read for humans (it is in every project the same guideline) and easier to read for machines (which offer help like `pretty-quick`).

Similar philosophy as behind [gofmt](https://golang.org/cmd/gofmt/)

## We chose [env](https://github.com/motdotla/dotenv) as configurtion file format

It is good practice to store configuration in the environment (see [12 factor app](https://12factor.net/config)).
From this idea evolved the practice to use `.env` files for configuring the environment.
`.env` is a standard widely supported, e.g.

- [go](https://github.com/joho/godotenv)
- [Node](https://www.npmjs.com/package/dotenv)
- [Webpack](https://www.npmjs.com/package/dotenv-webpack)

Last but not least: `.env` is the format, which is used by [vue-cli](https://cli.vuejs.org/guide/mode-and-env.html)

# Translation

We want to internationalize our application for the following
languages:

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

## 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).
  - [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 dependend on external (=non JS) tools (`xgettext`) which are not able to consume `.vue`-files directly, which in turn leads to unexpected behaviour.
-

## Commands
You need the following applications to run the process:
 * `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`)