feat: runtime logger formatting and debug verbose option

docs/content/docs/3.options/10.misc.md

@@ -47,10 +47,10 @@ If it can not detect Nuxt configuration changing, you may need to run `nuxi prep
 
 ## `debug`
 
-- type: `boolean`
+- type: `boolean | 'verbose'`
 - default: `false`
 
-Whether to use `@nuxtjs/i18n` debug mode. If `true`, logs will be output to the console.
+Whether to use `@nuxtjs/i18n` debug mode. If `true` or `'verbose'`, logs will be output to the console, setting this to `'verbose'` will also log loaded messages objects.
 
 ::callout{icon="i-heroicons-exclamation-triangle" color="amber"}
 The purpose of this option is to help identify any problems with `@nuxtjs/i18n`.

docs/content/docs/5.v9/3.options/10.misc.md

@@ -47,10 +47,10 @@ If it can not detect Nuxt configuration changing, you may need to run `nuxi prep
 
 ## `debug`
 
-- type: `boolean`
+- type: `boolean | 'verbose'`
 - default: `false`
 
-Whether to use `@nuxtjs/i18n` debug mode. If `true`, logs will be output to the console.
+Whether to use `@nuxtjs/i18n` debug mode. If `true` or `'verbose'`, logs will be output to the console, setting this to `'verbose'` will also log loaded messages objects.
 
 ::callout{icon="i-heroicons-exclamation-triangle" color="amber"}
 The purpose of this option is to help identify any problems with `@nuxtjs/i18n`.

src/bundler.ts

@@ -84,7 +84,8 @@ export async function extendBundler(nuxt: Nuxt, nuxtOptions: Required<NuxtI18nOp
               dropMessageCompiler: nuxtOptions.bundle.dropMessageCompiler
             }),
             {
-              __DEBUG__: String(nuxtOptions.debug)
+              __DEBUG__: String(!!nuxtOptions.debug),
+              __DEBUG_VERBOSE__: String(nuxtOptions.debug === 'verbose')
             }
           )
         )
@@ -125,10 +126,12 @@ export async function extendBundler(nuxt: Nuxt, nuxtOptions: Required<NuxtI18nOp
 
   extendViteConfig(config => {
     if (config.define) {
-      config.define['__DEBUG__'] = JSON.stringify(nuxtOptions.debug)
+      config.define['__DEBUG__'] = JSON.stringify(!!nuxtOptions.debug)
+      config.define['__DEBUG_VERBOSE__'] = JSON.stringify(nuxtOptions.debug === 'verbose')
     } else {
       config.define = {
-        __DEBUG__: JSON.stringify(nuxtOptions.debug)
+        __DEBUG__: JSON.stringify(!!nuxtOptions.debug),
+        __DEBUG_VERBOSE__: JSON.stringify(nuxtOptions.debug === 'verbose')
       }
     }
     debug('vite.config.define', config.define)

src/env.d.ts

@@ -5,3 +5,4 @@ declare namespace NodeJS {
 }
 
 declare let __DEBUG__: boolean
+declare let __DEBUG_VERBOSE__: boolean

src/nitro.ts

@@ -120,7 +120,8 @@ export { localeDetector }
     }
 
     // setup debug flag
-    nitroConfig.replace['__DEBUG__'] = String(nuxtOptions.debug)
+    nitroConfig.replace['__DEBUG__'] = String(!!nuxtOptions.debug)
+    nitroConfig.replace['__DEBUG_VERBOSE__'] = String(nuxtOptions.debug === 'verbose')
     debug('nitro.replace', nitroConfig.replace)
   })
 

src/runtime/internal.ts

@@ -49,20 +49,21 @@ export function parseAcceptLanguage(input: string): string[] {
 
 export function getBrowserLocale(): string | undefined {
   let ret: string | undefined
+  const logger = /*#__PURE__*/ createLogger('getBrowserLocale')
 
   if (import.meta.client) {
     if (navigator.languages) {
       // get browser language either from navigator if running on client side, or from the headers
       ret = findBrowserLocale(normalizedLocales, navigator.languages as string[])
-      __DEBUG__ && console.log('getBrowserLocale (navigator.languages, ret) -', navigator.languages, ret)
+      __DEBUG__ && logger.log('(navigator.languages, ret) -', navigator.languages, ret)
     }
   } else if (import.meta.server) {
     const header = useRequestHeaders(['accept-language'])
-    __DEBUG__ && console.log('getBrowserLocale accept-language', header)
+    __DEBUG__ && logger.log('accept-language', header)
     const accept = header['accept-language']
     if (accept) {
       ret = findBrowserLocale(normalizedLocales, parseAcceptLanguage(accept))
-      __DEBUG__ && console.log('getBrowserLocale ret', ret)
+      __DEBUG__ && logger.log('ret', ret)
     }
   }
 
@@ -92,8 +93,10 @@ export function getLocaleCookie(
   detect: false | DetectBrowserLanguageOptions,
   defaultLocale: string
 ): string | undefined {
+  const env = import.meta.client ? 'client' : 'server'
+  const logger = /*#__PURE__*/ createLogger(`getLocaleCookie:${env}`)
   __DEBUG__ &&
-    console.log('getLocaleCookie', {
+    logger.log({
       useCookie: detect && detect.useCookie,
       cookieKey: detect && detect.cookieKey,
       localeCodes
@@ -104,27 +107,23 @@ export function getLocaleCookie(
   }
 
   const localeCode: string | undefined = cookieRef.value ?? undefined
-  const env = import.meta.client ? 'client' : 'server'
   if (localeCode == null) {
-    __DEBUG__ && console.log(`getLocaleCookie (${env}) - none`)
+    __DEBUG__ && logger.log(`none`)
     return
   }
 
   if (localeCodes.includes(localeCode)) {
-    __DEBUG__ && console.log(`getLocaleCookie (${env}) - locale from cookie: `, localeCode)
+    __DEBUG__ && logger.log(`locale from cookie: `, localeCode)
     return localeCode
   }
 
   if (defaultLocale) {
-    __DEBUG__ &&
-      console.log(
-        `getLocaleCookie (${env}) - unknown locale cookie (${localeCode}), setting to defaultLocale (${defaultLocale})`
-      )
+    __DEBUG__ && logger.log(`unknown locale cookie (${localeCode}), setting to defaultLocale (${defaultLocale})`)
     cookieRef.value = defaultLocale
     return defaultLocale
   }
 
-  __DEBUG__ && console.log(`getLocaleCookie (${env}) - unknown locale cookie (${localeCode}), unsetting cookie`)
+  __DEBUG__ && logger.log(`unknown locale cookie (${localeCode}), unsetting cookie`)
   cookieRef.value = undefined
   return
 }
@@ -176,7 +175,7 @@ export function detectBrowserLanguage(
   detectLocaleContext: DetectLocaleContext,
   locale: Locale = ''
 ): DetectBrowserLanguageFromResult {
-  const logger = createLogger('detectBrowserLanguage')
+  const logger = /*#__PURE__*/ createLogger('detectBrowserLanguage')
   const _detect = runtimeDetectBrowserLanguage()
 
   // feature is disabled
@@ -271,15 +270,13 @@ export function getLocaleDomain(
   strategy: string,
   route: string | RouteLocationNormalized | RouteLocationNormalizedLoaded
 ): string {
+  const logger = /*#__PURE__*/ createLogger(`getLocaleDomain`)
   let host = getHost() || ''
+  const routePath = isObject(route) ? route.path : isString(route) ? route : ''
+
   if (host) {
-    __DEBUG__ &&
-      console.log(
-        `MultiDomainsMultiLocales: locating domain for host: `,
-        host,
-        strategy,
-        isObject(route) ? route.path : route
-      )
+    __DEBUG__ && logger.log(`locating domain for host`, { host, strategy, path: routePath })
+
     let matchingLocale: LocaleObject | undefined
     const matchingLocales = locales.filter(locale => {
       if (locale && locale.domain) {
@@ -296,8 +293,7 @@ export function getLocaleDomain(
 
     if (matchingLocales.length === 1) {
       matchingLocale = matchingLocales[0]
-      __DEBUG__ &&
-        console.log(`MultiDomainsMultiLocales: found only one matching domain: `, host, matchingLocales[0].code)
+      __DEBUG__ && logger.log(`found one matching domain`, { host, matchedLocale: matchingLocales[0].code })
     } else if (matchingLocales.length > 1) {
       if (strategy === 'no_prefix') {
         console.warn(
@@ -310,20 +306,13 @@ export function getLocaleDomain(
       } else {
         // get prefix from route
         if (route) {
-          const routePath = isObject(route) ? route.path : isString(route) ? route : ''
-
-          __DEBUG__ &&
-            console.log(`MultiDomainsMultiLocales: Check in matched domain for locale match in path: `, routePath, host)
+          __DEBUG__ && logger.log(`check matched domain for locale match`, { path: routePath, host })
 
           if (routePath && routePath !== '') {
             const matches = routePath.match(getLocalesRegex(matchingLocales.map(l => l.code)))
             if (matches && matches.length > 1) {
               matchingLocale = matchingLocales.find(l => l.code === matches[1])
-              __DEBUG__ &&
-                console.log(
-                  `MultiDomainsMultiLocales: Found matching locale from path. MatchingLocale is now`,
-                  matchingLocale?.code
-                )
+              __DEBUG__ && logger.log(`matched locale from path`, { matchedLocale: matchingLocale?.code })
             }
           }
         }
@@ -334,10 +323,7 @@ export function getLocaleDomain(
             Array.isArray(l.defaultForDomains) ? l.defaultForDomains.includes(host) : l.domainDefault
           )
           __DEBUG__ &&
-            console.log(
-              `MultiDomainsMultiLocales: matching locale not found - trying to get default for this domain. MatchingLocale is now`,
-              matchingLocale?.code
-            )
+            logger.log(`no locale matched - using default for this domain`, { matchedLocale: matchingLocale?.code })
         }
       }
     }

src/runtime/messages.ts

@@ -1,4 +1,5 @@
 import { deepCopy, isFunction, isArray, isObject, isString } from '@intlify/shared'
+import { createConsola } from 'consola'
 
 import type { I18nOptions, Locale, FallbackLocale, LocaleMessages, DefineLocaleMessage } from 'vue-i18n'
 import type { NuxtApp } from '#app'
@@ -14,6 +15,18 @@ export type LocaleLoader<T = LocaleMessages<DefineLocaleMessage>> = {
   load: () => Promise<MessageLoaderResult<T>>
   cache: boolean
 }
+
+/**
+ * Used for runtime debug logs only, cannot be imported due to
+ * this being a virtual file in both nuxt and nitro contexts
+ *
+ * NOTE: We could export the logger from a virtual file instead
+ */
+const debugLogger = /*#__PURE__*/ createConsola({ level: __DEBUG_VERBOSE__ ? 999 : 4 }).withTag('i18n')
+function createLogger(label: string) {
+  return /*#__PURE__*/ debugLogger.withTag(label)
+}
+
 const cacheMessages = new Map<string, LocaleMessages<DefineLocaleMessage>>()
 
 export async function loadVueI18nOptions(
@@ -75,19 +88,20 @@ export async function loadInitialMessages<Context extends NuxtApp = NuxtApp>(
 }
 
 async function loadMessage(locale: Locale, { key, load }: LocaleLoader) {
+  const logger = /*#__PURE__*/ createLogger('loadMessage')
   let message: LocaleMessages<DefineLocaleMessage> | null = null
   try {
-    __DEBUG__ && console.log('loadMessage: (locale) -', locale)
+    __DEBUG__ && logger.log({ locale })
     const getter = await load().then(r => ('default' in r ? r.default : r))
     if (isFunction(getter)) {
       message = await getter(locale)
-      __DEBUG__ && console.log('loadMessage: dynamic load', message)
+      __DEBUG__ && logger.log('dynamic load', logger.level > 999 ? message : '')
     } else {
       message = getter
       if (message != null && cacheMessages) {
         cacheMessages.set(key, message)
       }
-      __DEBUG__ && console.log('loadMessage: load', message)
+      __DEBUG__ && logger.log('loaded', logger.level > 999 ? message : '')
     }
   } catch (e: unknown) {
     console.error('Failed locale loading: ' + (e as Error).message)
@@ -100,6 +114,7 @@ export async function loadLocale(
   localeLoaders: Record<Locale, LocaleLoader[]>,
   setter: (locale: Locale, message: LocaleMessages<DefineLocaleMessage>) => void
 ) {
+  const logger = /*#__PURE__*/ createLogger('loadLocale')
   const loaders = localeLoaders[locale]
 
   if (loaders == null) {
@@ -112,11 +127,11 @@ export async function loadLocale(
     let message: LocaleMessages<DefineLocaleMessage> | undefined | null = null
 
     if (cacheMessages && cacheMessages.has(loader.key) && loader.cache) {
-      __DEBUG__ && console.log(loader.key + ' is already loaded')
+      __DEBUG__ && logger.log(loader.key + ' is already loaded')
       message = cacheMessages.get(loader.key)
     } else {
-      __DEBUG__ && !loader.cache && console.log(loader.key + ' bypassing cache!')
-      __DEBUG__ && console.log(loader.key + ' is loading ...')
+      __DEBUG__ && !loader.cache && logger.log(loader.key + ' bypassing cache!')
+      __DEBUG__ && logger.log(loader.key + ' is loading ...')
       message = await loadMessage(locale, loader)
     }