feat: add useI18nPreloadKeys composable

Author: BobbieGoede

src/prepare/auto-imports.ts

@@ -31,6 +31,7 @@ export function prepareAutoImports({ resolver, userOptions: options, runtimeDir
       'useBrowserLocale',
       'useCookieLocale',
       'useSetI18nParams',
+      'useI18nPreloadKeys',
       NUXT_I18N_COMPOSABLE_DEFINE_ROUTE,
       NUXT_I18N_COMPOSABLE_DEFINE_LOCALE,
       NUXT_I18N_COMPOSABLE_DEFINE_CONFIG

src/runtime/composables/index.ts

@@ -1,4 +1,4 @@
-import { useNuxtApp, useCookie, useRuntimeConfig } from '#imports'
+import { useNuxtApp, useCookie, useRuntimeConfig, useRequestEvent } from '#imports'
 import { ref } from 'vue'
 import { _useLocaleHead, _useSetI18nParams } from '../routing/head'
 import { useComposableContext } from '../utils'
@@ -257,3 +257,38 @@ export function defineI18nRoute(route: I18nRoute | false): void {
     warnRuntimeUsage('defineI18nRoute')
   }
 }
+
+/**
+ * Register translation keys for preloading
+ *
+ * This is used to track keys to include in the preloaded messages which
+ * otherwise would not be included during SSR.
+ *
+ * Examples of keys to register are dynamically or conditionally rendered translations (e.g. inside `v-if` or using computed keys).
+ *
+ * @param keys - The translation keys to preload
+ *
+ * @example
+ * ```ts
+ * useI18nPreloadKeys(['my-dynamic-key', 'nested.dynamic.key'])
+ * ```
+ */
+export function useI18nPreloadKeys(keys: string[]): void {
+  if (import.meta.server) {
+    const ctx = useRequestEvent()?.context?.nuxtI18n
+    if (ctx == null) {
+      console.warn('useI18nPreloadKeys(): `nuxtI18n` server context is accessible.')
+      return
+    }
+
+    const locale = useNuxtApp()._nuxtI18n.getLocale()
+    if (locale) {
+      console.warn('useI18nPreloadKeys(): Could not resolve locale during server-side render.')
+      return
+    }
+
+    for (const k of keys) {
+      ctx?.trackKey(k, locale)
+    }
+  }
+}

src/types.ts

@@ -98,13 +98,20 @@ export interface ExperimentalFeatures {
    */
   cacheLifetime?: number
   /**
-   * Strip unused locale messages from the server-side rendered HTML, reducing the size of the HTML payload.
-   * This might cause issues with conditional rendering of messages in templates.
+   * Preload locale messages and add them to the server-side rendered HTML.
+   * This increases the size of the initial HTML payload but prevents an addition client-side request to load the messages.
+   *
+   * Since locale messages can be a large collection, it is recommended to use this in combination with `stripMessagesPayload`.
    * @default false
    */
-  stripMessagesPayload?: boolean
-
   preload?: boolean
+  /**
+   * Strip unused locale messages from the server-side rendered HTML, reducing the size of the HTML payload.
+   *
+   * The `useI18nPreloadKeys` composable is used to prevent keys from being stripped, this is useful for conditionally rendered translations.
+   * @default false // or `true` if `experimental.preload` is enabled
+   */
+  stripMessagesPayload?: boolean
 }
 
 export interface BundleOptions