Mercurial > gemma
changeset 4327:b372fbe15300
client: refactor dev documentation
* Split out general considerations with rationales for decisions
into a file on its own, the same with how to handle translations.
* Add an overview document.
| author | Bernhard Reiter <bernhard@intevation.de> |
|---|---|
| date | Wed, 04 Sep 2019 16:45:32 +0200 |
| parents | 124a5a7fe8d6 |
| children | ff21b742b106 |
| files | client/docs/dev-generalconsiderations.md client/docs/dev-translations.md client/docs/developer.md client/docs/developers.md |
| diffstat | 4 files changed, 135 insertions(+), 128 deletions(-) [+] |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/client/docs/dev-generalconsiderations.md Wed Sep 04 16:45:32 2019 +0200 @@ -0,0 +1,67 @@ +# 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) +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/client/docs/dev-translations.md Wed Sep 04 16:45:32 2019 +0200 @@ -0,0 +1,64 @@ +# 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. + +## 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. +- +
--- a/client/docs/developer.md Wed Sep 04 15:30:08 2019 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,128 +0,0 @@ -# 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`) - -## 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.