fix!: correct finalizePendingLocaleChange signature to be synchronous (#3626)

Author: BobbieGoede

docs/content/docs/02.guide/08.lang-switcher.md

@@ -92,8 +92,8 @@ export default defineNuxtConfig({
 <script setup lang="ts">
 const { finalizePendingLocaleChange } = useI18n()
 
-const onBeforeEnter = async () => {
-  await finalizePendingLocaleChange()
+const onBeforeEnter = () => {
+  finalizePendingLocaleChange()
 }
 </script>
 
@@ -160,8 +160,8 @@ definePageMeta({
   }
 })
 
-route.meta.pageTransition.onBeforeEnter = async () => {
-  await finalizePendingLocaleChange()
+route.meta.pageTransition.onBeforeEnter = () => {
+  finalizePendingLocaleChange()
 }
 </script>
 

docs/content/docs/02.guide/90.migrating.md

@@ -13,6 +13,10 @@ Check the documentation detailing the breaking changes [here](https://vue-i18n.i
 ### Lazy load locale messages by default and removed `lazy` option
 The `lazy` option has been removed and lazy loading of locale messages is now the default behavior.
 
+### Function signature corrected for `finalizePendingLocaleChange()`{lang="ts"}
+The function signature for `finalizePendingLocaleChange()`{lang="ts"} has been corrected from `() => Promise<void>`{lang="ts-type"} to `() => void`{lang="ts-type"}.
+This change was made since the function does not rely on any async operations and should not be awaited, and should prevent unnecessary function coloring.
+
 ### Option default changed `useLocaleHead()`{lang="ts"} and `$localeHead()`{lang="ts"}
 The default value for the `key` property has been changed from `'hid'` to `'key'`.
 

docs/content/docs/04.api/04.vue-i18n.md

@@ -51,9 +51,9 @@ Returns browser locale code filtered against the ones defined in options.
 
 - **Arguments**:
   - no arguments
-- **Returns**: `Promise<void>`{lang="ts-type"}
+- **Returns**: `void`{lang="ts-type"}
 
-Switches to the pending locale that would have been set on navigate, but was prevented by the option [`skipSettingLocaleOnNavigate`](/docs/api/options#skipsettinglocaleonnavigate). See more information in [Wait for page transition](/docs/guide/lang-switcher#wait-for-page-transition).
+Switches locale to the pending locale, used when navigation locale switch is prevented by the [`skipSettingLocaleOnNavigate`](/docs/api/options#skipsettinglocaleonnavigate) option. See [Wait for page transition](/docs/guide/lang-switcher#wait-for-page-transition) for more information.
 
 ### `waitForPendingLocaleChange()`{lang="ts"}
 

specs/fixtures/basic_usage/app.vue

@@ -8,9 +8,7 @@ const skipSettingLocale = useRuntimeConfig().public.i18n.skipSettingLocaleOnNavi
 const pageTransition = {
   name: 'my',
   mode: 'out-in',
-  onBeforeEnter: async () => {
-    await finalizePendingLocaleChange()
-  }
+  onBeforeEnter: () => finalizePendingLocaleChange()
 }
 </script>
 

specs/fixtures/basic_usage/pages/index.vue

@@ -4,7 +4,7 @@ import { computed, navigateTo, ref, useAppConfig, useAsyncData, useHead, watch }
 import LangSwitcher from '../components/LangSwitcher.vue'
 import LocalScope from '../components/LocalScope.vue'
 
-const { t, locale, locales, localeProperties, finalizePendingLocaleChange } = useI18n()
+const { t, locale, locales, localeProperties } = useI18n()
 const localePath = useLocalePath()
 const switchLocalePath = useSwitchLocalePath()
 const localeRoute = useLocaleRoute()

specs/fixtures/basic_usage_compat_4/app/app.vue

@@ -8,9 +8,7 @@ const skipSettingLocale = useRuntimeConfig().public.i18n.skipSettingLocaleOnNavi
 const pageTransition = {
   name: 'my',
   mode: 'out-in',
-  onBeforeEnter: async () => {
-    await finalizePendingLocaleChange()
-  }
+  onBeforeEnter: () => finalizePendingLocaleChange()
 }
 </script>
 

specs/fixtures/basic_usage_compat_4/app/pages/index.vue

@@ -4,7 +4,7 @@ import { computed, navigateTo, ref, useAppConfig, useAsyncData, useHead, watch }
 import LangSwitcher from '../components/LangSwitcher.vue'
 import LocalScope from '../components/LocalScope.vue'
 
-const { t, locale, locales, localeProperties, finalizePendingLocaleChange } = useI18n()
+const { t, locale, locales, localeProperties } = useI18n()
 const localePath = useLocalePath()
 const switchLocalePath = useSwitchLocalePath()
 const localeRoute = useLocaleRoute()

src/runtime/plugins/i18n.ts

@@ -113,8 +113,7 @@ export default defineNuxtPlugin({
         composer.onLanguageSwitched = (oldLocale, newLocale) =>
           nuxt.callHook('i18n:localeSwitched', { oldLocale, newLocale }) as Promise<void>
 
-        // eslint-disable-next-line @typescript-eslint/require-await --- TODO: breaking - signature should be synchronous
-        composer.finalizePendingLocaleChange = async () => {
+        composer.finalizePendingLocaleChange = () => {
           if (!i18n.__pendingLocale) return
 
           ctx.setLocale(i18n.__pendingLocale)

src/runtime/types.ts

@@ -143,9 +143,9 @@ export interface ComposerCustomProperties<
    */
   onLanguageSwitched: LanguageSwitchedHandler
   /**
-   * Switches to the pending locale that would have been set on navigate, but was prevented by the `skipSettingLocaleOnNavigate` option.
+   * Switches locale to the pending locale, used when navigation locale switch is prevented by the `skipSettingLocaleOnNavigate` option.
    */
-  finalizePendingLocaleChange: () => Promise<void>
+  finalizePendingLocaleChange: () => void
   /**
    * Returns a promise that will be resolved once the pending locale is set.
    */
@@ -167,13 +167,6 @@ declare module 'vue-i18n' {
   interface I18n {
     /** @internal */ __pendingLocale?: string
     /** @internal */ __pendingLocalePromise?: Promise<void>
-    /**
-     * Sets the value of the locale property on VueI18n or Composer instance
-     *
-     * This differs from the instance `setLocale` method in that it sets the
-     * locale property directly without triggering other side effects
-     * @internal
-     */
-    __resolvePendingLocalePromise?: () => void
+    /** @internal */ __resolvePendingLocalePromise?: () => void
   }
 }

src/runtime/utils.ts

@@ -278,7 +278,7 @@ export async function navigate(redirectPath: string, routePath: string, locale:
     const vueI18n = ctx.getVueI18n()
     vueI18n.__pendingLocale = locale
     vueI18n.__pendingLocalePromise = new Promise(resolve => {
-      vueI18n.__resolvePendingLocalePromise = () => resolve()
+      vueI18n.__resolvePendingLocalePromise = resolve
     })
     if (!force) {
       return