docs: rework for 3.x

There are still some rough edges.

- removing <script> tag use, as that's untested and probably not common
- v2 -> v3 migration information
- adding relevant version information to various documentation

docs/.vuepress/config.js

@@ -26,7 +26,7 @@ module.exports = ctx => ({
             link: '/guide/started.md',
           },
           {
-            text: 'v2.x (Vue 3)',
+            text: 'v2.x/3.x (Vue 3)',
             ariaLabel: 'Version Menu',
             items: [
               { text: 'v1.x (Vue 2)', link: 'https://i18next.github.io/i18next-vue/vue-2/introduction' }
@@ -46,19 +46,20 @@ module.exports = ctx => ({
             children: [
               '/guide/started.md',
               '/guide/component.md',
+              '/guide/composition-api.md',
               '/guide/component-interpolation.md',
-              '/guide/i18n-options.md',
               '/guide/i18n.md',
-              '/guide/composition-api.md',
-              '/guide/single-file-component.md',
               '/guide/ssr.md',
+              '/guide/i18n-options.md',
+              '/guide/single-file-component.md',
             ]
           },
           {
             title: 'Migration',
             collapsable: false,
             children: [
               '/migration.md',
+              '/migration-v3.md',
             ]
           }
         ]

docs/guide/component-interpolation.md

@@ -92,4 +92,14 @@ This will render
 <label>
   <strong>Greetings</strong> 42 people being amazing
 </label>
-```
+```
+
+## Custom start/end markers
+
+::: tip Version info
+Since `i18next-vue` v2.2.0.
+:::
+
+Custom slot values may be useful when the default braces (`{` and `}`) are wrongly treated by the Locize service or don't satisfy other needs.
+
+See [the README](https://github.com/i18next/i18next-vue/tree/main#custom-slot-values) for details.

docs/guide/component.md

@@ -1,6 +1,6 @@
 # Component-based localization
 
-In general, locale info (e.g. `locale`,`messages`, etc) is set in the `i18next` instance and passed to the i18next-vue Vue plugin during [initialization](./started.md#setup).
+In general, locale info (e.g. `lng`,`resources`, etc) is set in the `i18next` instance and passed to the i18next-vue Vue plugin during [initialization](./started.md#setup).
 
 After that you can translate using `$t` or `this.$t` in Vue components. You can also manage locale info for each component separately, which might be more convenient due to Vue's component oriented design.
 
@@ -60,4 +60,4 @@ Outputs the following:
 </div>
 ```
 
-As in the example above, if the component doesn't have the locale message, it falls back to globally defined localization info. The component uses the language set in i18next.
+The `$t` function ususlly uses the language set in i18next.

docs/guide/composition-api.md

@@ -15,4 +15,47 @@ const { t, i18next } = useTranslation();
 
 Make sure to [set up i18next-vue](./started.md#setup) for your app beforehand.
 
-In the `<template>` part just use `$t` and `$i18next`. `useTranslation()` does not change that.
+Even without calling `useTranslation()` you can use `$t` and `$i18next` in your `<template>` part.
+
+## Customize `t`
+::: tip Version info
+Since `i18next-vue` v3.
+:::
+
+`useTranslation()` can be used to get a custom `t` function with a specific namespace, language and/or key prefix:
+
+`useTranslation()` supports passing in a single name space or an array of namespaces to use. These namespaces will be loaded, if they are not available yet.
+
+As a second argument, you can pass an object setting the `keyPrefix` (i.e. a prefix to put before all translation keys passed to this `t`) or a fixed translation language using `lng`.
+
+```vue
+<script setup>
+    const { t } = useTranslation("adminNamespace", { keyPrefix: 'system', lng: 'de' });
+</script>
+```
+
+Both this special `t` and the default `$t` (unaffected by the options) can be used alongside each other in the template.
+
+You can call `useTranslation` multiple times, to e.g. create multiple translation functions for different namespaces.
+
+::: tip 
+If you use certain namespaces/key prefixes a lot, it might make sense to extract composition functions for those to a separate JS module and use these in your components.
+```js
+// t-functions.js
+export function useAdminTranslations() {
+     const { t } = useTranslation("adminNamespace");
+     return t;
+}
+```
+```vue
+<!-- my-component.vue -->
+<script setup>
+    // import { useAdminTranslations } from ...
+    const tAdmin = useAdminTranslations();
+</script>
+<template>
+    <h1 v-if="!isAdmin">{{ $t('not-allowed-warning')}}</h1>
+    <button v-else>{{ tAdmin('shutdown-button-label') }}</button>
+</template>
+```
+:::

docs/guide/i18n-options.md

@@ -1,5 +1,11 @@
 # i18nOptions
 
+::: warning Deprecated
+`i18nOptions` is deprecated in `i18next-vue` v3 and **will be removed in v4**.  
+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` in `i18nOptions`.
+:::
+
 You can set some translation options on a per-component basis using the `i18nOptions` option object.
 
 ## `namespaces`
@@ -111,6 +117,9 @@ app.component('app', {
 ```
 
 ## `messages`
+::: danger Removed in v3
+`messages` is no longer supported in `i18next-vue` v3.
+:::
 
 Translations can not only be defined in translation files but also in the `i18nOptions`.
 

docs/guide/single-file-component.md

@@ -1,4 +1,8 @@
 # Single file components: `<i18n>`
+::: danger Removed in v3
+`<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.
+:::
+
 
 by [@kazupon](https://github.com/kazupon)
 

docs/guide/ssr.md

@@ -1,5 +1,9 @@
 # SSR
 
+::: warning
+This is mostly theoretical information. If you have feedback about `i18next-vue` in a SSR context, please let us know via a GitHub issue :heart:.
+:::
+
 When using Server Side Rendering (SSR), i18next-vue makes sure to not introduce memory leaks. To do that, two i18next-vue features are not available on the server.
 
 ## No component-specific messages

docs/guide/started.md

@@ -26,7 +26,7 @@ pnpm add i18next-vue
 
 - Vue.js `3.x`
     - there is a separate [Vue 2 version](https://github.com/i18next/i18next-vue/tree/vue-2) of this library
-- i18next `19.x` or newer
+- i18next: `23.x` or newer (`19.x` or newer for version 2)
 
 ## Setup
 
@@ -85,8 +85,10 @@ app.use(I18NextVue, {
 });
 ```
 
-| Name | | Description |
+| Option | | Description |
 | --- | --- | --- |
-| **i18next** | 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) |
-
+| **`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`**<br>since v2.2.0 | Optional<hr>Default: `{` | Beginning of a slot in the translation component. |
+| **`slotEnd`**<br>since v2.2.0 | Optional<hr>Default: `}` | End of a slot in the translation component. |
+| **`legacyI18nOptionsSupport`**<br>since v3 | Optional<hr>Default: `false` | Enables `i18nOptions` support in v3.<br>This support will be removed in v4.<br>v2 supports `i18nOptions` by default. |

docs/installation.md

@@ -36,21 +36,6 @@ i18next.init({/* ... */});
 app.use(I18NextVue, { i18next });
 ```
 
-## Direct Download / CDN
-
-<https://unpkg.com/i18next-vue/dist/index.js>
-
-[unpkg.com](https://unpkg.com) provides NPM-based CDN links. The above link will always point to the latest release on NPM. You can also use a specific version/tag via URLs like <https://unpkg.com/i18next-vue@2.0.0/dist/index.js>
-
-
-```html    
-<script src="https://unpkg.com/vue@2/dist/vue.js"></script>
-<script src="https://unpkg.com/i18next@21/i18next.js"></script>
-<script src="https://unpkg.com/i18next-vue/dist/index.js"></script>
-```
-
-You need to explicitly install the `i18next-vue` plugin via `app.use(I18NextVue, { i18next });`
-
 ## Dev Build
 
 You can clone directly from GitHub and build `i18next-vue` yourself if you want to use the latest dev build.

docs/introduction.md

@@ -12,7 +12,7 @@ i18next-vue brings Vue support for i18next and provides:
 Let's [Get Started](./guide/started.md)!
 
 ::: tip Note
-This documentation is for `i18next-vue` v2.x, the Vue 3 version.
+This documentation is for `i18next-vue` v2.x and v3.x, the Vue 3 versions.
 
-There is separate [docs for the Vue 2 version](https://i18next.github.io/i18next-vue/vue-2/introduction).
+There is separate [documentation for the Vue 2 version](https://i18next.github.io/i18next-vue/vue-2/introduction).
 :::

docs/migration-v3.md

@@ -0,0 +1,23 @@
+# Migration from `i18next-vue` v2.x
+Version 3 has some breaking changes coming from v2.x
+
+## Breaking changes
+- requires `i18next` >=23
+    - Consult the [`i18next` Migration Guide](https://www.i18next.com/misc/migration-guide) for updating.
+- the 3.x package is ESM-only
+    - Relevant only for [CommonJS users](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c), i. e. when using `require()` imports
+- deprecated support for [`i18nOptions`](../guide/i18n-options.md) (Options API)
+    - You can use `useTranslation()` with its [new parameters for most of these use-cases](../guide/composition-api.md#customize-t).
+    - Legacy support for `i18nOptions` needs to be explcitly enabled via the [`legacyI18nOptionsSupport: true` plugin option](/guide/started.html#plugin-options)
+    - This allows component-by-component migration to `useTranslation()` using the 3.x version.
+- removed support for `<i18n>` blocks in SFCs and `messages` in `i18nOptions` 
+    - i.e. no more  per-component translations
+    - There is no replacement for this, as this seems to be a rarely used feature.
+
+## New/changed functionality
+- new `useTranslation()` parameters to [specify a fixed language, namespace(s) and a keyprefix](../guide/composition-api.md#customize-t) (all optional)
+- `$t`/`t` functions will return an empty string while i18next is loading
+    - v2 returned the untranslated translation key, which is usually uglier
+- support for [TypeScript auto-completion of translation keys](https://www.i18next.com/overview/typescript)
+    - via `i18next`'s support for this
+    - Your milage may vary (dev performance, ...). If it works for you, it can be quite useful.

docs/migration.md

@@ -1,6 +1,10 @@
 # Migration from [@panter/vue-i18next](https://panter.github.io/vue-i18next/)
 This package has some breaking changes compared to the @panter version.
 
+::: warning Versions
+These migration notes are for `i18next-vue` v2.x. When updating to 3.x, also consider the [3.x migration information](./migration-v3.md).
+:::
+
 ## Features no longer supported
 - The `v-t` directive has been removed. Please use `$t` instead.
 - The `v-waitForT` directive has been removed. Use `v-if="$i18next.isInitialized"` or hold off mounting Vue until i18next has been initialized: