feat(h3,hono): add getDetectorLocale util

packages/h3/README.md

@@ -149,11 +149,11 @@ export default defineNitroPlugin(nitroApp => {
 
 You can detect locale with your custom logic from current `H3Event`.
 
-example for detecting locale from url query:
+example for detecting locale from url query, and get locale with `getDetectorLocale` util:
 
 ```ts
 import { H3 } from 'h3'
-import { intlify, getQueryLocale } from '@intlify/h3'
+import { intlify, getQueryLocale, getDetectorLocale } from '@intlify/h3'
 
 import type { H3Event } from 'h3'
 
@@ -172,6 +172,11 @@ const app = new H3({
     })
   ]
 })
+
+app.get('/', async event => {
+  const locale = await getDetectorLocale(event)
+  console.log(`Current Locale: ${locale.language}`)
+})
 ```
 
 You can make that function asynchronous. This is useful when loading resources along with locale detection.

packages/h3/docs/functions/getDetectorLocale.md

@@ -0,0 +1,41 @@
+[**@intlify/h3**](../index.md)
+
+***
+
+[@intlify/h3](../index.md) / getDetectorLocale
+
+# Function: getDetectorLocale()
+
+```ts
+function getDetectorLocale(event): Promise<Locale>;
+```
+
+get a locale which is detected with locale detector.
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `event` | `H3Event` | A H3 event |
+
+## Returns
+
+`Promise`\<`Locale`\>
+
+Return an `Intl.Locale` instance representing the detected locale
+
+## Description
+
+The locale obtainable via this function comes from the locale detector specified in the `locale` option of the [intlify](../variables/intlify.md) plugin.
+
+## Example
+
+```js
+app.get(
+  '/',
+  async (event) => {
+    const locale = await getDetectorLocale(event)
+    return `Current Locale: ${locale.language}`
+  },
+)
+```

packages/h3/docs/index.md

@@ -18,6 +18,7 @@ Internationalization middleware & utilities for h3
 | ------ | ------ |
 | [detectLocaleFromAcceptLanguageHeader](functions/detectLocaleFromAcceptLanguageHeader.md) | Locale detection with `Accept-Language` header |
 | [getCookieLocale](functions/getCookieLocale.md) | get locale from cookie |
+| [getDetectorLocale](functions/getDetectorLocale.md) | get a locale which is detected with locale detector. |
 | [getHeaderLanguage](functions/getHeaderLanguage.md) | get language from header |
 | [getHeaderLanguages](functions/getHeaderLanguages.md) | get languages from header |
 | [getHeaderLocale](functions/getHeaderLocale.md) | get locale from header |

packages/h3/src/index.test.ts

@@ -5,6 +5,7 @@ import { SYMBOL_I18N, SYMBOL_I18N_LOCALE } from './symbols.ts'
 import {
   defineI18nMiddleware,
   detectLocaleFromAcceptLanguageHeader,
+  getDetectorLocale,
   useTranslation
 } from './index.ts'
 
@@ -88,3 +89,27 @@ describe('useTranslation', () => {
     await expect(() => useTranslation(eventMock)).rejects.toThrowError()
   })
 })
+
+test('getDetectorLocale', async () => {
+  const context = createCoreContext({
+    locale: detectLocaleFromAcceptLanguageHeader
+  })
+  const eventMock = {
+    req: {
+      headers: {
+        get: _name => (_name === 'accept-language' ? 'ja;q=0.9,en;q=0.8' : '')
+      }
+    },
+    context: {
+      [SYMBOL_I18N]: context as CoreContext
+    }
+  } as H3Event
+  const _locale = context.locale as unknown
+  const bindLocaleDetector = (_locale as LocaleDetector).bind(null, eventMock)
+  // @ts-ignore ignore type error because this is test
+  context.locale = bindLocaleDetector
+  eventMock.context[SYMBOL_I18N_LOCALE] = bindLocaleDetector
+
+  const locale = await getDetectorLocale(eventMock)
+  expect(locale.language).toEqual('ja')
+})

packages/h3/src/index.ts

@@ -261,6 +261,21 @@ export const detectLocaleFromAcceptLanguageHeader = (event: H3Event): Locale =>
  */
 export interface DefineLocaleMessage extends LocaleMessage<string> {}
 
+async function getLocaleAndEventContext(event: H3Event): Promise<[string, H3EventContext]> {
+  const context = getEventContext<H3EventContext>(event)
+  if (context[SYMBOL_I18N] == null) {
+    throw new Error(
+      'plugin has not been initialized. Please check that the `intlify` plugin is installed correctly.'
+    )
+  }
+
+  const localeDetector = context[SYMBOL_I18N_LOCALE] as unknown as LocaleDetector
+  // Always await detector call - works for both sync and async detectors
+  // (awaiting a non-promise value returns it immediately)
+  const locale = await localeDetector(event)
+  return [locale, context]
+}
+
 /**
  * Use translation function in event handler
  *
@@ -283,19 +298,8 @@ export async function useTranslation<
   Schema extends Record<string, any> = {}, // eslint-disable-line @typescript-eslint/no-explicit-any -- NOTE(kazupon): generic type
   Event extends H3Event = H3Event
 >(event: Event): Promise<TranslationFunction<Schema, DefineLocaleMessage>> {
-  const context = getEventContext<H3EventContext>(event)
-  if (context[SYMBOL_I18N] == null) {
-    throw new Error(
-      'middleware not initialized, please setup `onRequest` and `onResponse` options of `H3` with the middleware obtained with `defineI18nMiddleware`'
-    )
-  }
-
-  const localeDetector = context[SYMBOL_I18N_LOCALE] as unknown as LocaleDetector
-  // Always await detector call - works for both sync and async detectors
-  // (awaiting a non-promise value returns it immediately)
-  const locale = await localeDetector(event)
-  context[SYMBOL_I18N].locale = locale
-
+  const [locale, context] = await getLocaleAndEventContext(event)
+  context[SYMBOL_I18N]!.locale = locale
   function translate(key: string, ...args: unknown[]): string {
     // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call -- NOTE(kazupon): generic type
     const [_, options] = parseTranslateArgs(key, ...args)
@@ -317,3 +321,27 @@ export async function useTranslation<
 
   return translate as TranslationFunction<Schema, DefineLocaleMessage>
 }
+
+/**
+ * get a locale which is detected with locale detector.
+ *
+ * @description The locale obtainable via this function comes from the locale detector specified in the `locale` option of the {@link intlify} plugin.
+ *
+ * @example
+ * ```js
+ * app.get(
+ *   '/',
+ *   async (event) => {
+ *     const locale = await getDetectorLocale(event)
+ *     return `Current Locale: ${locale.language}`
+ *   },
+ * )
+ * ```
+ * @param event - A H3 event
+ *
+ * @returns Return an {@linkcode Intl.Locale} instance representing the detected locale
+ */
+export async function getDetectorLocale(event: H3Event): Promise<Intl.Locale> {
+  const result = await getLocaleAndEventContext(event)
+  return new Intl.Locale(result[0])
+}

packages/hono/README.md

@@ -117,10 +117,11 @@ export default app
 
 You can detect locale with your custom logic from current `Context`.
 
-example for detecting locale from url query:
+example for detecting locale from url query, and get locale with `getDetectorLocale` util:
 
 ```ts
-import { defineI18nMiddleware, getQueryLocale } from '@intlify/hono'
+import { Hono } from 'hono'
+import { defineI18nMiddleware, getQueryLocale, getDetectorLocale } from '@intlify/hono'
 import type { Context } from 'hono'
 
 const DEFAULT_LOCALE = 'en'
@@ -134,12 +135,19 @@ const localeDetector = (ctx: Context): string => {
   }
 }
 
-const middleware = defineI18nMiddleware({
+const i18nMiddleware = defineI18nMiddleware({
   // set your custom locale detector
   locale: localeDetector
   // something options
   // ...
 })
+
+const app = new Hono()
+app.use('*', i18nMiddleware)
+app.get('/', async ctx => {
+  const locale = await getDetectorLocale(ctx)
+  return ctx.text(`Current Locale: ${locale.language}`)
+})
 ```
 
 You can make that function asynchronous. This is useful when loading resources along with locale detection.

packages/hono/docs/functions/getDetectorLocale.md

@@ -0,0 +1,41 @@
+[**@intlify/hono**](../index.md)
+
+***
+
+[@intlify/hono](../index.md) / getDetectorLocale
+
+# Function: getDetectorLocale()
+
+```ts
+function getDetectorLocale(ctx): Promise<Intl.Locale>;
+```
+
+get a locale which is detected with locale detector.
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `ctx` | `Context` | A Hono context |
+
+## Returns
+
+`Promise`\<`Intl.Locale`\>
+
+Return an `Intl.Locale` instance representing the detected locale
+
+## Description
+
+The locale obtainable via this function comes from the locale detector specified in the `locale` option of the [defineI18nMiddleware](defineI18nMiddleware.md).
+
+## Example
+
+```js
+app.get(
+  '/',
+  async ctx => {
+    const locale = await getDetectorLocale(ctx)
+    return ctx.text(`Current Locale: ${locale.language}`)
+  },
+)
+```

packages/hono/docs/functions/useTranslation.md

@@ -25,7 +25,7 @@ function useTranslation<Schema, HonoContext>(ctx): Promise<TranslationFunction<S
 }>>>>;
 ```
 
-use translation function in event handler
+use translation function in handler
 
 ## Type Parameters
 

packages/hono/docs/index.md

@@ -13,6 +13,7 @@ Internationalization middleware & utilities for Hono
 | [defineI18nMiddleware](functions/defineI18nMiddleware.md) | define i18n middleware for Hono |
 | [detectLocaleFromAcceptLanguageHeader](functions/detectLocaleFromAcceptLanguageHeader.md) | locale detection with `Accept-Language` header |
 | [getCookieLocale](functions/getCookieLocale.md) | get locale from cookie |
+| [getDetectorLocale](functions/getDetectorLocale.md) | get a locale which is detected with locale detector. |
 | [getHeaderLanguage](functions/getHeaderLanguage.md) | get language from header |
 | [getHeaderLanguages](functions/getHeaderLanguages.md) | get languages from header |
 | [getHeaderLocale](functions/getHeaderLocale.md) | get locale from header |
@@ -25,7 +26,7 @@ Internationalization middleware & utilities for Hono
 | [tryHeaderLocales](functions/tryHeaderLocales.md) | try to get locales from header |
 | [tryPathLocale](functions/tryPathLocale.md) | try to get the locale from the path |
 | [tryQueryLocale](functions/tryQueryLocale.md) | try to get the locale from the query |
-| [useTranslation](functions/useTranslation.md) | use translation function in event handler |
+| [useTranslation](functions/useTranslation.md) | use translation function in handler |
 
 ## Interfaces
 

packages/hono/src/index.test.ts

@@ -7,6 +7,7 @@ import type { Context } from 'hono'
 import {
   defineI18nMiddleware,
   detectLocaleFromAcceptLanguageHeader,
+  getDetectorLocale,
   useTranslation
 } from './index.ts'
 
@@ -93,3 +94,33 @@ describe('useTranslation', () => {
     await expect(() => useTranslation(mockContext)).rejects.toThrowError()
   })
 })
+
+test('getDetectorLocale', async () => {
+  /**
+   * setup `defineI18nMiddleware` emulates
+   */
+  const context = createCoreContext({
+    locale: detectLocaleFromAcceptLanguageHeader
+  })
+  const mockContext = {
+    req: {
+      raw: {
+        headers: {
+          get: _name => (_name === 'accept-language' ? 'ja;q=0.9,en;q=0.8' : '')
+        }
+      }
+    },
+    get: (key: string) => {
+      if (key === 'i18n') {
+        return context
+      } else if (key === 'i18nLocaleDetector') {
+        const locale = context.locale as unknown
+        return (locale as LocaleDetector).bind(null, mockContext)
+      }
+    }
+  } as Context
+
+  // test `getDetectorLocale`
+  const locale = await getDetectorLocale(mockContext)
+  expect(locale.language).toEqual('ja')
+})