feat!: support async locale detector (#19)

* feat!: support async locale detector

* fix: update docs

Author: kazupon

README.md

@@ -67,9 +67,9 @@ const app = createApp({ ...middleware })
 const router = createRouter()
 router.get(
   '/',
-  eventHandler((event) => {
+  eventHandler(async (event) => {
     // use `useTranslation` in event handler
-    const t = useTranslation(event)
+    const t = await useTranslation(event)
     return t('hello', { name: 'h3' })
   }),
 )
@@ -88,15 +88,48 @@ example for detecting locale from url query:
 import { defineI18nMiddleware, getQueryLocale } from '@intlify/h3'
 import type { H3Event } from 'h3'
 
-const DEFAULT_LOCALE = 'en'
-
 // define custom locale detector
 const localeDetector = (event: H3Event): string => {
-  try {
-    return getQueryLocale(event).toString()
-  } catch () {
-    return DEFAULT_LOCALE
+  return getQueryLocale(event).toString()
+}
+
+const middleware = defineI18nMiddleware({
+  // set your custom locale detector
+  locale: localeDetector,
+  // something options
+  // ...
+})
+```
+
+You can make that function asynchronous. This is useful when loading resources along with locale detection.
+
+> [!NOTE]
+> The case which a synchronous function returns a promise is not supported. you need to use `async function`.
+
+```ts
+import { defineI18nMiddleware, getQueryLocale } from '@intlify/h3'
+import type { DefineLocaleMessage } from '@intlify/h3'
+import type { H3Event } from 'h3'
+
+const loader = (path: string) => import(path).then((m) => m.default || m)
+const messages: Record<string, () => ReturnType<typeof loader>> = {
+  en: () => loader('./locales/en.json'),
+  ja: () => loader('./locales/ja.json'),
+}
+
+// define custom locale detector and lazy loading
+const localeDetector = async (event: H3Event, i18n: CoreContext<string, DefineLocaleMessage>): Promise<string> => {
+  // detect locale
+  const locale = getCookieLocale(event).toString()
+
+  // resource lazy loading
+  const loader = messages[locale]
+  if (loader && !i18n.messages[locale]) {
+    const message = await loader()
+    i18n.messages[locale] = message
   }
+
+  return locale
 }
 
 const middleware = defineI18nMiddleware({
@@ -107,9 +140,10 @@ const middleware = defineI18nMiddleware({
 })
 ```
 
+
 ## 🧩 Type-safe resources
 
-> [!WARNING]  
+> [!WARNING]
 > **This is experimental feature (inspired from [vue-i18n](https://vue-i18n.intlify.dev/guide/advanced/typescript.html#typescript-support)).**
 > We would like to get feedback from you 🙂.
 
@@ -174,7 +208,7 @@ If you are using [Visual Studio Code](https://code.visualstudio.com/) as an edit
 
 ## 🖌️ Resource keys completion
 
-> [!WARNING]  
+> [!WARNING]
 > **This is experimental feature (inspired from [vue-i18n](https://vue-i18n.intlify.dev/guide/advanced/typescript.html#typescript-support)).**
 > We would like to get feedback from you 🙂.
 
@@ -199,12 +233,12 @@ the part of example:
 const router = createRouter()
 router.get(
   '/',
-  eventHandler((event) => {
+  eventHandler(async (event) => {
     type ResourceSchema = {
       hello: string
     }
     // set resource schema as type parameter
-    const t = useTranslation<ResourceSchema>(event)
+    const t = await useTranslation<ResourceSchema>(event)
     // you can completion when you type `t('`
     return t('hello', { name: 'h3' })
   }),
@@ -234,8 +268,8 @@ declare module '@intlify/h3' {
 const router = createRouter()
 router.get(
   '/',
-  eventHandler((event) => {
-    const t = useTranslation(event)
+  eventHandler(async (event) => {
+    const t = await useTranslation(event)
     // you can completion when you type `t('`
     return t('hello', { name: 'h3' })
   }),
@@ -253,11 +287,11 @@ The advantage of this way is that it is not necessary to specify the resource sc
 ### Utilities
 
 `@intlify/h3` composable utilities accept event (from
-`eventHandler((event) => {})`) as their first argument. (Exclud `useTranslation`) return the [`Intl.Locale`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale)
+`eventHandler((event) => {})`) as their first argument. (Exclude `useTranslation`) return the [`Intl.Locale`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale)
 
 ### Translations
 
-- `useTranslation(event)`: use translation function
+- `useTranslation(event)`: use translation function, asynchronous
 
 ### Headers
 

bun.lockb

@@ -82,7 +82,7 @@
     "vitest": "^1.0.0-beta.4"
   },
   "dependencies": {
-    "@intlify/core": "^9.7.1",
+    "@intlify/core": "^9.8.0",
     "@intlify/utils": "^0.11.1"
   }
 }

package.json

@@ -23,8 +23,8 @@ const app = createApp({ ...middleware })
 const router = createRouter()
 router.get(
   '/',
-  eventHandler((event) => {
-    const t = useTranslation(event)
+  eventHandler(async (event) => {
+    const t = await useTranslation(event)
     return t('hello', { name: 'h3' })
   }),
 )

playground/basic/index.ts

@@ -29,8 +29,8 @@ const app = createApp({ ...middleware })
 const router = createRouter()
 router.get(
   '/',
-  eventHandler((event) => {
-    const t = useTranslation(event)
+  eventHandler(async (event) => {
+    const t = await useTranslation(event)
     return t('hello', { name: 'h3' })
   }),
 )

playground/global-schema/index.ts

@@ -22,11 +22,11 @@ const app = createApp({ ...middleware })
 const router = createRouter()
 router.get(
   '/',
-  eventHandler((event) => {
+  eventHandler(async (event) => {
     type ResourceSchema = {
       hello: string
     }
-    const t = useTranslation<ResourceSchema>(event)
+    const t = await useTranslation<ResourceSchema>(event)
     return t('hello', { name: 'h3' })
   }),
 )

playground/local-schema/index.ts

@@ -0,0 +1,3 @@
+{
+  "hello": "hello, {name}"
+}

spec/fixtures/en.json

@@ -0,0 +1,3 @@
+{
+  "hello": "こんにちは, {name}"
+}

spec/fixtures/ja.json

@@ -1,4 +1,4 @@
-import { afterEach, expect, test, vi } from 'vitest'
+import { afterEach, describe, expect, test, vi } from 'vitest'
 import { createApp, eventHandler, toNodeListener } from 'h3'
 import { getQueryLocale } from '@intlify/utils/h3'
 import supertest from 'supertest'
@@ -11,6 +11,8 @@ import {
 
 import type { App, H3Event } from 'h3'
 import type { SuperTest, Test } from 'supertest'
+import type { CoreContext } from '@intlify/core'
+import type { DefineLocaleMessage } from '../src/index.ts'
 
 let app: App
 let request: SuperTest<Test>
@@ -36,8 +38,8 @@ test('translation', async () => {
 
   app.use(
     '/',
-    eventHandler((event) => {
-      const t = useTranslation(event)
+    eventHandler(async (event) => {
+      const t = await useTranslation(event)
       return { message: t('hello', { name: 'h3' }) }
     }),
   )
@@ -49,40 +51,93 @@ test('translation', async () => {
   expect(res.body).toEqual({ message: 'hello, h3' })
 })
 
-test('custom locale detection', async () => {
-  const defaultLocale = 'en'
-
-  // define custom locale detector
-  const localeDetector = (event: H3Event): string => {
-    try {
+describe('custom locale detection', () => {
+  test('basic', async () => {
+    // define custom locale detector
+    const localeDetector = (event: H3Event): string => {
       return getQueryLocale(event).toString()
-    } catch (_e) {
-      return defaultLocale
     }
-  }
 
-  const middleware = defineI18nMiddleware({
-    locale: localeDetector,
-    messages: {
+    const middleware = defineI18nMiddleware({
+      locale: localeDetector,
+      messages: {
+        en: {
+          hello: 'hello, {name}',
+        },
+        ja: {
+          hello: 'こんにちは, {name}',
+        },
+      },
+    })
+    app = createApp({ ...middleware })
+    request = supertest(toNodeListener(app))
+
+    app.use(
+      '/',
+      eventHandler(async (event) => {
+        const t = await useTranslation(event)
+        return { message: t('hello', { name: 'h3' }) }
+      }),
+    )
+
+    const res = await request.get('/?locale=ja')
+    expect(res.body).toEqual({ message: 'こんにちは, h3' })
+  })
+
+  test('async', async () => {
+    const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))
+
+    const loader = (path: string) => import(path).then((m) => m.default || m)
+    const messages: Record<string, () => ReturnType<typeof loader>> = {
+      en: () => loader('./fixtures/en.json'),
+      ja: () => loader('./fixtures/ja.json'),
+    }
+
+    // async locale detector
+    const localeDetector = async (
+      event: H3Event,
+      i18n: CoreContext<string, DefineLocaleMessage>,
+    ) => {
+      const locale = getQueryLocale(event).toString()
+      await sleep(100)
+      const loader = messages[locale]
+      if (loader && !i18n.messages[locale]) {
+        const message = await loader()
+        i18n.messages[locale] = message
+      }
+      return locale
+    }
+
+    const middleware = defineI18nMiddleware({
+      locale: localeDetector,
+      messages: {
+        en: {
+          hello: 'hello, {name}',
+        },
+      },
+    })
+    app = createApp({ ...middleware })
+    request = supertest(toNodeListener(app))
+
+    app.use(
+      '/',
+      eventHandler(async (event) => {
+        const t = await useTranslation(event)
+        return { message: t('hello', { name: 'h3' }) }
+      }),
+    )
+
+    const translated: Record<string, { message: string }> = {
       en: {
-        hello: 'hello, {name}',
+        message: 'hello, h3',
       },
       ja: {
-        hello: 'こんにちは, {name}',
+        message: 'こんにちは, h3',
       },
-    },
+    }
+    for (const locale of ['en', 'ja']) {
+      const res = await request.get(`/?locale=${locale}`)
+      expect(res.body).toEqual(translated[locale])
+    }
   })
-  app = createApp({ ...middleware })
-  request = supertest(toNodeListener(app))
-
-  app.use(
-    '/',
-    eventHandler((event) => {
-      const t = useTranslation(event)
-      return { message: t('hello', { name: 'h3' }) }
-    }),
-  )
-
-  const res = await request.get('/?locale=ja')
-  expect(res.body).toEqual({ message: 'こんにちは, h3' })
 })

spec/integration.spec.ts

@@ -25,7 +25,7 @@ test('defineI18nMiddleware', () => {
   })
 })
 
-test('translation function', () => {
+test('translation function', async () => {
   const eventMock = {
     node: {
       req: {
@@ -44,7 +44,7 @@ test('translation function', () => {
     },
   }
 
-  const t = useTranslation<typeof resources>(eventMock)
+  const t = await useTranslation<typeof resources>(eventMock)
   expectTypeOf<string>(t('test')).toMatchTypeOf<string>()
   expectTypeOf<string>(t('foo')).toMatchTypeOf<string>()
   expectTypeOf<string>(t('bar.buz.baz')).toMatchTypeOf<string>()

src/index.test-d.ts

@@ -41,7 +41,7 @@ test('defineI18nMiddleware', () => {
 })
 
 describe('useTranslation', () => {
-  test('basic', () => {
+  test('basic', async () => {
     /**
      * setup `defineI18nMiddleware` emulates
      */
@@ -75,11 +75,11 @@ describe('useTranslation', () => {
     context.locale = bindLocaleDetector
 
     // test `useTranslation`
-    const t = useTranslation(eventMock)
+    const t = await useTranslation(eventMock)
     expect(t('hello', { name: 'h3' })).toEqual('こんにちは, h3')
   })
 
-  test('not initilize context', () => {
+  test('not initilize context', async () => {
     const eventMock = {
       node: {
         req: {
@@ -92,6 +92,6 @@ describe('useTranslation', () => {
       context: {},
     } as H3Event
 
-    expect(() => useTranslation(eventMock)).toThrowError()
+    await expect(() => useTranslation(eventMock)).rejects.toThrowError()
   })
 })