Skip to content

Commit

Permalink
docs: Update information for 4.0 release
Browse files Browse the repository at this point in the history 
- includes the new version in various places
- adding new v3 -> v4 migration guide
- more removal badges
- fixing typos/reformatting
  • Loading branch information
@kkuegler
kkuegler committed Jan 19, 2024
1 parent 6005f65 commit fa04a85
Show file tree
Hide file tree
Showing 8 changed files with 116 additions and 154 deletions.
6 changes: 5 additions & 1 deletion docs/.vitepress/config.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ export default defineConfig({
link: '/guide/started',
},
{
text: 'v2.x/3.x (Vue 3)',
text: 'v2.x - 4.x (Vue 3)',
items: [
{ text: 'v1.x (Vue 2)', link: 'https://i18next.github.io/i18next-vue/vue-2/introduction' }
]
Expand Down Expand Up @@ -82,6 +82,10 @@ export default defineConfig({
text: 'Migration from <br>i18next-vue v2.x',
link: '/migration-v3.md',
},
{
text: 'Migration from <br>i18next-vue v3.x',
link: '/migration-v4.md',
},
]
},
],
Expand Down
9 changes: 4 additions & 5 deletions docs/guide/component.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ const locales = {
en: {
hello: 'Hello!',
loadbundle: 'Load bundle language: {{lang}}',
}
},
};

i18next.init({
Expand All @@ -33,15 +33,14 @@ const Component1 = {
return {
lang: 'DE',
};
}
},
};
app.component('component1', Component1);
app.mount('#app')
app.mount('#app');
```

Template:


```html
<div id="app">
<p>{{ $t("message.hello") }}</p>
Expand All @@ -60,4 +59,4 @@ Outputs the following:
</div>
```

The `$t` function ususlly uses the language set in i18next.
The `$t` function usually uses the language set in i18next.
68 changes: 41 additions & 27 deletions docs/guide/i18n-options.md
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# i18nOptions <Badge type="warning" text="Deprecated since 3.0" /><Badge type="danger" text="For removal in 4.0" />
# i18nOptions <Badge type="warning" text="Deprecated since 3.0" /><Badge type="danger" text="Removed in 4.0" />

::: warning Deprecated
`i18nOptions` are now deprecated and **will be removed in v4**. They can be replaced with `useTranslation()` using its [new parameters in v3](/guide/composition-api#customize-t) for most use-cases.
::: danger Removed in 4.0
`i18nOptions` support has been removed in v4. They can be replaced with `useTranslation()` using its [new parameters in v3](/guide/composition-api#customize-t) for most use-cases.

In version 3 you need to enable the [`legacyI18nOptionsSupport` plugin option](/guide/started.html#plugin-options) for the `i18nOptions` to apply. Even with that enabled, v3 no longer supports [`messages`](#messages) in `i18nOptions`.
:::
Expand All @@ -10,38 +10,42 @@ You can set some translation options on a per-component basis using the `i18nOpt

## `namespaces` <Badge type="warning" text="Deprecated since 3.0" />

::: danger NOTE
This and all other `i18nOptions` are no longer supported in `i18next-vue` v4.
:::

The namespace(s) to lookup translations in. These will be loaded automatically.

FIXME: example still uses v2's `<i18next>`

```javascript
const locales = {
en: {
tos: "the Terms of Service",
term: "I accept {{0}}. {{1}}.",
promise: "I promise"
}
tos: 'the Terms of Service',
term: 'I accept {{0}}. {{1}}.',
promise: 'I promise',
},
};

i18next.init({
lng: "en",
fallbackLng: "en",
lng: 'en',
fallbackLng: 'en',
resources: {
en: { common: locales.en }
}
en: { common: locales.en },
},
});
const app = createApp(/* ... */);
app.use(I18NextVue, { i18next });

app.component("app", {
i18nOptions: { namespaces: "common" },
app.component('app', {
i18nOptions: { namespaces: 'common' },
template: `
<div>
<i18next path="term" tag="label">
<a href="#" target="_blank">{{ $t("tos") }}</a>
<strong>{{ $t("promise") }}</strong>
</i18next>
</div>`
</div>`,
});
```

Expand All @@ -50,33 +54,37 @@ Namespaces can also be an array, sorted by priority.
```javascript
const commonResources = {
en: {
promise: "I promise"
}
promise: 'I promise',
},
};

const appResources = {
en: {
promise: "The app promise"
}
promise: 'The app promise',
},
};

i18next.init({
lng: "en",
fallbackLng: "en",
lng: 'en',
fallbackLng: 'en',
resources: {
en: { common: commonResources.en, app: appResources.en }
}
en: { common: commonResources.en, app: appResources.en },
},
});
app.use(I18NextVue, { i18next });

app.component("app", {
i18nOptions: { namespaces: ["app", "common"] },
template: `<strong>{{ $t("promise") }}</strong>`
app.component('app', {
i18nOptions: { namespaces: ['app', 'common'] },
template: `<strong>{{ $t("promise") }}</strong>`,
});
```

## `keyPrefix` <Badge type="warning" text="Deprecated since 3.0" />

::: danger NOTE
This and all other `i18nOptions` are no longer supported in `i18next-vue` v4.
:::

You can prefix all keys used for translations in a component. This way you can use shorter keys in `$t()`.

```javascript
Expand Down Expand Up @@ -105,7 +113,8 @@ app.component('app', {
});
```

This is easier to read and write than
This is easier to read and write than

```js
app.component('app', {
template: `
Expand All @@ -115,7 +124,8 @@ app.component('app', {
});
```

## `messages` <Badge type="danger" text="Removed in 3.0" />
## `messages`

::: danger NOTE
`messages` is no longer supported in `i18next-vue` v3.
:::
Expand Down Expand Up @@ -147,6 +157,10 @@ Another way of doing this is [using an `<i18n>` block](./single-file-component.m

## `lng` <Badge type="warning" text="Deprecated since 3.0" />

::: danger NOTE
This and all other `i18nOptions` are no longer supported in `i18next-vue` v4.
:::

Set a fixed language for a component.

```javascript
Expand Down
90 changes: 4 additions & 86 deletions docs/guide/single-file-component.md
View file
Original file line number Diff line number Diff line change
@@ -1,90 +1,8 @@
# Single file components: `<i18n>` <Badge type="danger" text="Removed in 3.0" />

::: danger NOTE
`<i18n>` blocks are no longer supported in `i18next-vue` v3. This is probably already not working in v2, because there are no Vue 3 loaders producing the right format.
`<i18n>` blocks are no longer supported since `i18next-vue` v3. This is probably already not working in v2,
because there are no Vue 3 loaders producing the right format.
:::


by [@kazupon](https://github.com/kazupon)

Single File Components can have an `<i18n>` block for defining translations locally in the component.

```vue
<i18n> { "en": { "hello": "hello world!" } } </i18n>
<template>
<div id="app"><p>message: {{ $t('hello') }}</p></div>
</template>
<script>
export default {
name: "app"
};
</script>
```

## i18n tag

To use the `<i18>` tag you need to use vue-loader:

```
npm install @kazupon/vue-i18n-loader --save-dev
```

For detailed documentation check the [original docs](https://github.com/kazupon/vue-i18n-loader).

```
// vue-loader (~v14.x):
module.exports = {
// ...
module: {
rules: [
{
test: /\.vue$/,
loader: 'vue-loader',
options: {
loaders: {
// you need to specify `i18n` loaders key with `vue-i18n-loader` (https://github.com/kazupon/vue-i18n-loader)
i18n: '@kazupon/vue-i18n-loader'
}
}
},
// ...
]
},
// ...
}
```

## Use it with YAML:

```
npm install yaml-loader --save-dev
```

```html
<i18n> en: hello: "hello world!" </i18n>
```

```javascript
module.exports = {
// ...
module: {
rules: [
{
test: /\.vue$/,
loader: "vue-loader",
options: {
preLoaders: {
i18n: "yaml-loader"
},
loaders: {
i18n: "@kazupon/vue-i18n-loader"
}
}
}
// ...
]
}
// ...
};
```
Single File Components could have an `<i18n>` block for defining translations locally in the component before the removal.
41 changes: 23 additions & 18 deletions docs/guide/started.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,21 +3,25 @@
Install the package via

::: code-group

```bash[npm]
npm install i18next-vue
```
```

```bash[yarn]
yarn add i18next-vue
```

```bash[pnpm]
pnpm add i18next-vue
```

:::

## Requirements

- Vue.js `3.x`
- there is a separate [Vue 2 version](https://github.com/i18next/i18next-vue/tree/vue-2) of this library
- there is a separate [Vue 2 version](https://github.com/i18next/i18next-vue/tree/vue-2) of this library
- i18next: `23.x` or newer (`19.x` or newer for version 2)

## Setup
Expand Down Expand Up @@ -54,31 +58,32 @@ app.mount('#app')
```

## Simple usage

Use the instance function `$t` in your Vue components to translate. See [Component-based localization](component.md) for more details.
The [i18next documentation](https://www.i18next.com/) details all the translation options available through `$t()` (also known as [`t()` in the i18next docs](https://www.i18next.com/overview/api#t)).

```vue
<template>
<div class="container">
{{ $t("greeter.hello-world") }}
</div>
<div class="container">
{{ $t('greeter.hello-world') }}
</div>
</template>
<script>
export default({
export default {
// ...
methods: {
logSomething() {
console.log(this.$t("common.hello"))
}
}
});
console.log(this.$t('common.hello'));
},
},
};
</script>
```

## Plugin options

You can use these options during plugin registration:
You can use these options during plugin registration:

```js
app.use(I18NextVue, {
Expand All @@ -87,10 +92,10 @@ app.use(I18NextVue, {
});
```

| Option | | Description |
| --- | --- | --- |
| **`18next`** | Required | The 'i18next' instance to use. |
| **`rerenderOn`** | Optional<hr>Default: Refresh on all relevant events. | Listen for 'i18next' events and refreshes components that use translations.<br>This is a string array. Supported values include: `'initialized'`, `'languageChanged'`, `'loaded'`, `'added'` and `'removed'`.<br>Check the [i18next events documentation](https://www.i18next.com/overview/api#events) for more information. For `'added'` and `'removed'` see the [i18next store documentation](https://www.i18next.com/overview/api#store-events) |
| **`slotStart`**<Badge type="info" text="Since 2.2.0" /> | Optional<hr>Default: `{` | Beginning of a slot in the translation component. |
| **`slotEnd`**<Badge type="info" text="Since 2.2.0" /> | Optional<hr>Default: `}` | End of a slot in the translation component. |
| **`legacyI18nOptionsSupport`**<Badge type="info" text="Since 3.0" /> | Optional<hr>Default: `false` | Enables [`i18nOptions`](/guide/i18n-options) support in v3.<br>This support **will be removed in v4**.<br>v2 supports `i18nOptions` by default. |
| Option | | Description |
| -------------------------------------------------------------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`18next`** | Required | The 'i18next' instance to use. |
| **`rerenderOn`** | Optional<hr>Default: Refresh on all relevant events. | Listen for 'i18next' events and refreshes components that use translations.<br>This is a string array. Supported values include: `'initialized'`, `'languageChanged'`, `'loaded'`, `'added'` and `'removed'`.<br>Check the [i18next events documentation](https://www.i18next.com/overview/api#events) for more information. For `'added'` and `'removed'` see the [i18next store documentation](https://www.i18next.com/overview/api#store-events) |
| **`slotStart`**<Badge type="info" text="Since 2.2.0" /> | Optional<hr>Default: `{` | Beginning of a slot in the translation component. |
| **`slotEnd`**<Badge type="info" text="Since 2.2.0" /> | Optional<hr>Default: `}` | End of a slot in the translation component. |
| **`legacyI18nOptionsSupport`**<Badge type="info" text="Since 3.0" /> | Optional<hr>Default: `false` | Enables [`i18nOptions`](/guide/i18n-options) support in v3.<br>This support **is removed in v4**.<br>v2 supports `i18nOptions` by default. |
Loading

0 comments on commit fa04a85

Please sign in to comment.