# Internationalization

To make the application multi lingual it uses internationalization through the [vue-i18n](https://github.com/kazupon/vue-i18n) module.

For each language specific files exists containing the translated phrases based on structured keys.
Quasar components already include translations which will be used automatically and have not to be translated again.

## File Structure

Under `src/i18n` each language is added with it's translations. The values are split into logical groups which are located in individual files for better readability. They all are put together in the `index.js` files:

    src/
    └── i18n/
        ├── index,js        # loading all languages
        ├── en-US/
        │   ├── index.js    # combining english translations
        │   ├── layout.js   # layout translations
        │   └── core.js     # core group translation
        └── de/
            ├── index.js    # combining german translations
            ├── layout.js   # layout translations
            └── core.js     # core group translation

All the JavaScript files listed above will evaluate to a big translation object.

But it is also possible to put some local translations, which are only for the specific page or component, within the '.vue' file. But this should not be done because it will later not be updated and forgotten for new languages.

## Use of translations

The general `$t` (translate) function registered in Vue is used therefore.
To specify the translation element we use the above defined structure with it's readable short path names to access in templates:

```vue
<template>
  <q-page>
    <q-btn :label="$t('mykey2')">
    {{ $t('mykey1') }}
    <span v-html="content"></span>
  </q-page>
</template>

<script>
export default {
  data() {
    return {
      content: this.$t('mykey3')
    }
  }
}
</script>
```

- `mykey1` in HTML body
- `mykey2` in attribute
- `mykey3` programmatically

### Variables

Variables may be used in different forms. As named parameters by using a data object:

```js
// Message
const messages = { en: { hello: "{msg} world" } };
// Template
<p>{{ $t('hello', { msg: 'hello' }) }}</p>
// Output
<p>hello world</p>
```

Or with an data array:

```js
// Message
const messages = { en: { message: { hello: '{0} world' } } }
// Template
<p>{{ $t('message.hello', ['hello']) }}</p>
// Output
<p>hello world</p>
```

### HTML Content

This should only be used in limited form, because it can destroy layouts:

```js
// Message
const messages = { en: { message: { hello: 'hello <br> world' } } }
// Template
<p v-html="$t('message.hello')"></p>
// Output
<p>hello <br> world</p>
```

### Pluralization

You can translate with pluralization. You must define the locale that have a pipe | separator, and define plurals in pipe separator.

Your template will need to use `$tc()` instead of `$t()`.

```js
// Message
const messages = {
    en: {
        car: 'car | cars',
        apple: 'no apples | one apple | {count} apples'
    }
}
// Template
<p>{{ $tc('car', 1) }}</p>
<p>{{ $tc('car', 2) }}</p>
<p>{{ $tc('apple', 0) }}</p>
<p>{{ $tc('apple', 1) }}</p>
<p>{{ $tc('apple', 10, { count: 10 }) }}</p>
// Output
<p>car</p>
<p>cars</p>
<p>no apples</p>
<p>one apple</p>
<p>10 apples</p>
```

You don't need to explicitly give the number for pluralization. The number can be accessed within locale messages via pre-defined named arguments `{count}` and/or `{n}`.

```js
// Message
const messages = {
  en: {
    apple: 'no apples | one apple | {count} apples',
    banana: 'no bananas | {n} banana | {n} bananas'
  }
}
// Template
<p>{{ $tc('apple', 10, { count: 10 }) }}</p>
<p>{{ $tc('apple', 10) }}</p>
<p>{{ $tc('banana', 1, { n: 1 }) }}</p>
<p>{{ $tc('banana', 1) }}</p>
<p>{{ $tc('banana', 100, { n: 'too many' }) }}</p>
// Output
<p>10 apples</p>
<p>10 apples</p>
<p>1 banana</p>
<p>1 banana</p>
<p>too many bananas</p>
```

### Date

```html
<!-- Template -->
<p>{{ $d(new Date(), 'short') }}</p>
<p>{{ $d(new Date(), 'long', 'ja-JP') }}</p>
<!-- Output -->
<p>Apr 19, 2017</p>
<p>2017年4月19日(水) 午前2:19</p>
```

### Number

```html
<!-- Template -->
<p>{{ $n(100, 'currency') }}</p>
<p>{{ $n(100, 'currency', 'ja-JP') }}</p>
<!-- Output -->
<p>$100.00</p>
<p>￥100</p>
```

### Linked locale messages

If there's a translation key that will always have the same concrete text as another one you can just link to it. To link to another translation key, all you have to do is to prefix its contents with an @: sign followed by the full name of the translation key including the namespace you want to link to.

```js
const messages = {
  en: {
    message: {
      the_world: "the world",
      dio: "DIO:",
      linked: "@:message.dio @:message.the_world !!!!"
    }
  }
};
```

## Management

With the help of the VSCode Plugin [i18n-ally](https://github.com/antfu/i18n-ally/blob/master/README.md) it is easy to work with translations. It lets you:

- show translation values in code
- show all translations as hover
- calculate translation progress
- show missing or unused translations
- extract text into i18n files

An other possibility is to use [BabelEdit](https://www.codeandweb.com/babeledit) which is a downloadable standalone application which can load the json files and translate them within it's dialogs. This allows to give the translation files to external translators.
Afterwards the translated files has to be imported into the code.

The base configuration is done in the `boot/i18n.js`. Here you may also change the base language used, if the translated is not available.

### Add new language

To add a new language copy an existing language folder within `src/i18n/...` and change it's text values.

You also have to add it within `src/i18n/index.ts` to be exported like `en-us` or the others.

{!docs/assets/abbreviations.md!}
