diff --git a/docs/content/en/api.md b/docs/content/en/api.md index e570280b6..acfe6b166 100644 --- a/docs/content/en/api.md +++ b/docs/content/en/api.md @@ -108,6 +108,22 @@ Instance of [VueI18n class](http://kazupon.github.io/vue-i18n/api/#vuei18n-class Switches locale of the app to specified locale code. If `useCookie` option is enabled, locale cookie will be updated with new value. If prefixes are enabled (`strategy` other than `no_prefix`), will navigate to new locale's route. +#### setPendingLocale + + - **Arguments**: + - no arguments + - **Returns**: `Promise` + + Switches to the pending locale that would have been set on navigate, but was prevented by the option [`skipSettingLocaleOnNavigate`](./options-reference#skipsettinglocaleonnavigate). See more information in [Wait for page transition](./lang-switcher#wait-for-page-transition). + +#### waitForPendingLocale + + - **Arguments**: + - no arguments + - **Returns**: `Promise` + + Returns a promise that will be resolved once the pending locale is set. + #### getBrowserLocale - **Arguments**: diff --git a/docs/content/en/lang-switcher.md b/docs/content/en/lang-switcher.md index 0602357bb..da769726c 100644 --- a/docs/content/en/lang-switcher.md +++ b/docs/content/en/lang-switcher.md @@ -98,3 +98,46 @@ export default { **nuxt-i18n** won't reset parameters translations for you, this means that if you use identical parameters for different routes, navigating between those routes might result in conflicting parameters. Make sure you always set params translations in such cases. + +## Wait for page transition + +By default, the locale will be changed right away when calling [`switchLocalePath(path)`](./api#switchlocalepath) which means that if you have a page transition, it will fade out the page with the text already switched to the new language and fade back in with the same content. + +To work around the issue, you can set the option [`skipSettingLocaleOnNavigate`](./options-reference#skipsettinglocaleonnavigate) to `true` and handle setting the locale yourself from a `beforeEnter` transition hook defined in a plugin. + +```js{}[nuxt.config.js] +export default { + plugins: ['~/plugins/router'], + + i18n: { + skipSettingLocaleOnNavigate: true, + } +} +``` + +```js{}[plugins/router.js] +export default ({ app }) => { + app.nuxt.defaultTransition.beforeEnter = () => { + app.i18n.setPendingLocale() + } + + // Optional: wait for locale before scrolling for a smoother transition + app.router.options.scrollBehavior = async (to, from, savedPosition) => { + // Make sure the route has changed + if (to.name !== from.name) await app.i18n.waitForPendingLocale() + return savedPosition || { x: 0, y: 0 } + } +} +``` + +If you have a specific transition defined in a page component, you would also need to call `setPendingLocale` from there. + +```js{}[pages/foo.vue] +export default { + transition: { + beforeEnter() { + this.$i18n.setPendingLocale() + } + } +} +``` diff --git a/docs/content/en/options-reference.md b/docs/content/en/options-reference.md index 70457dd34..c439a6b65 100644 --- a/docs/content/en/options-reference.md +++ b/docs/content/en/options-reference.md @@ -275,6 +275,13 @@ A listener called after app's locale has changed. Internal suffix added to generated route names for default locale, if strategy is `prefix_and_default`. You shouldn't need to change this. +## `skipSettingLocaleOnNavigate` + +- type: `boolean` +- default: `false` + +If true, the locale will not be set when navigating to a new locale. This is useful if you want to wait for the page transition to end before setting the locale yourself using [`setPendingLocale`](./api#skipsettinglocaleonnavigate). See more information in [Wait for page transition](./lang-switcher#wait-for-page-transition). + ## `routesNameSeparator` - type: `string` diff --git a/docs/content/es/api.md b/docs/content/es/api.md index bcd0acf40..c9caa5a22 100644 --- a/docs/content/es/api.md +++ b/docs/content/es/api.md @@ -108,6 +108,22 @@ Instance of [VueI18n class](http://kazupon.github.io/vue-i18n/api/#vuei18n-class Switches locale of the app to specified locale code. If `useCookie` option is enabled, locale cookie will be updated with new value. If prefixes are enabled (`strategy` other than `no_prefix`), will navigate to new locale's route. +#### setPendingLocale + + - **Arguments**: + - no arguments + - **Returns**: `Promise` + + Switches to the pending locale that would have been set on navigate, but was prevented by the option [`skipSettingLocaleOnNavigate`](./options-reference#skipsettinglocaleonnavigate). See more information in [Wait for page transition](./lang-switcher#wait-for-page-transition). + +#### waitForPendingLocale + + - **Arguments**: + - no arguments + - **Returns**: `Promise` + + Returns a promise that will be resolved once the pending locale is set. + #### getBrowserLocale - **Parámetros**: diff --git a/docs/content/es/lang-switcher.md b/docs/content/es/lang-switcher.md index 1f8814e0d..72ac22cd0 100644 --- a/docs/content/es/lang-switcher.md +++ b/docs/content/es/lang-switcher.md @@ -96,3 +96,46 @@ export default { **nuxt-i18n** no restablecerá las traducciones de parámetros por usted, esto significa que si utiliza parámetros idénticos para diferentes rutas, navegar entre esas rutas podría generar parámetros conflictivos. Asegúrese de establecer siempre traducciones de parámetros en tales casos. + +## Wait for page transition + +By default, the locale will be changed right away when calling [`switchLocalePath(path)`](./api#switchlocalepath) which means that if you have a page transition, it will fade out the page with the text already switched to the new language and fade back in with the same content. + +To work around the issue, you can set the option [`skipSettingLocaleOnNavigate`](./options-reference#skipsettinglocaleonnavigate) to `true` and handle setting the locale yourself from a `beforeEnter` transition hook defined in a plugin. + +```js{}[nuxt.config.js] +export default { + plugins: ['~/plugins/router'], + + i18n: { + skipSettingLocaleOnNavigate: true, + } +} +``` + +```js{}[plugins/router.js] +export default ({ app }) => { + app.nuxt.defaultTransition.beforeEnter = () => { + app.i18n.setPendingLocale() + } + + // Optional: wait for locale before scrolling for a smoother transition + app.router.options.scrollBehavior = async (to, from, savedPosition) => { + // Make sure the route has changed + if (to.name !== from.name) await app.i18n.waitForPendingLocale() + return savedPosition || { x: 0, y: 0 } + } +} +``` + +If you have a specific transition defined in a page component, you would also need to call `setPendingLocale` from there. + +```js{}[pages/foo.vue] +export default { + transition: { + beforeEnter() { + this.$i18n.setPendingLocale() + } + } +} +``` diff --git a/docs/content/es/options-reference.md b/docs/content/es/options-reference.md index f2bc1976e..9359e0bf5 100644 --- a/docs/content/es/options-reference.md +++ b/docs/content/es/options-reference.md @@ -273,6 +273,13 @@ A listener called after app's locale has changed. Internal suffix added to generated route names for default locale, if strategy is `prefix_and_default`. You shouldn't need to change this. +## `skipSettingLocaleOnNavigate` + +- type: `boolean` +- default: `false` + +If true, the locale will not be set when navigating to a new locale. This is useful if you want to wait for the page transition to end before setting the locale yourself using [`setPendingLocale`](./api#skipsettinglocaleonnavigate). See more information in [Wait for page transition](./lang-switcher#wait-for-page-transition). + ## `routesNameSeparator` - type: `string`