docs: add intlify/hono api docs

Author: kazupon

.prettierignore

@@ -1 +1,2 @@
 packages/h3/docs/**
+packages/hono/docs/**

eslint.config.ts

@@ -103,6 +103,7 @@ const config: ReturnType<typeof defineConfig> = defineConfig(
     '.github/FUNDING.yml',
     './**/playground/**',
     './packages/h3/docs/**',
+    './packages/hono/docs/**',
     'design/**'
   ]) as Linter.Config
 )

packages/h3/package.json

@@ -64,9 +64,9 @@
     "@types/supertest": "^6.0.3",
     "h3": "^1.15.4",
     "supertest": "^7.1.4",
-    "typedoc": "^0.28.14",
-    "typedoc-plugin-markdown": "^4.9.0",
-    "typescript": "^5.9.3",
+    "typedoc": "catalog:",
+    "typedoc-plugin-markdown": "catalog:",
+    "typescript": "catalog:",
     "unbuild": "catalog:"
   }
 }

packages/hono/README.md

@@ -90,28 +90,32 @@ const DEFAULT_LOCALE = 'en'
 const localeDetector = (ctx: Context): string => {
   try {
     return getQueryLocale(ctx).toString()
-  } catch () {
+  } catch {
     return DEFAULT_LOCALE
   }
 }
 
 const middleware = defineI18nMiddleware({
   // set your custom locale detector
-  locale: localeDetector,
+  locale: localeDetector
   // something options
   // ...
 })
 ```
 
 ## 🧩 Type-safe resources
 
+<!-- eslint-disable markdown/no-missing-label-refs -- NOTE(kazupon): ignore github alert -->
+
 > [!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 🙂.
 
 > [!NOTE]
 > The exeample code is [here](https://github.com/intlify/hono/tree/main/playground/typesafe-schema)
 
+<!-- eslint-enable markdown/no-missing-label-refs -- NOTE(kazupon): ignore github alert -->
+
 You can support the type-safe resources with schema using TypeScript on `defineI18nMiddleware` options.
 
 Locale messages resource:
@@ -167,13 +171,17 @@ If you are using [Visual Studio Code](https://code.visualstudio.com/) as an edit
 
 ## 🖌️ Resource keys completion
 
+<!-- eslint-disable markdown/no-missing-label-refs -- NOTE(kazupon): ignore github alert -->
+
 > [!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 🙂.
 
 > [!NOTE]
 > Resource Keys completion can be used if you are using [Visual Studio Code](https://code.visualstudio.com/)
 
+<!-- eslint-enable markdown/no-missing-label-refs -- NOTE(kazupon): ignore github alert -->
+
 You can completion resources key on translation function with `useTranslation`.
 
 ![Key Completion](assets/key-completion.gif)
@@ -182,9 +190,13 @@ resource keys completion has twe ways.
 
 ### Type parameter for `useTranslation`
 
+<!-- eslint-disable markdown/no-missing-label-refs -- NOTE(kazupon): ignore github alert -->
+
 > [!NOTE]
 > The exeample code is [here](https://github.com/intlify/hono/tree/main/playground/local-schema)
 
+<!-- eslint-enable markdown/no-missing-label-refs -- NOTE(kazupon): ignore github alert -->
+
 You can `useTranslation` set the type parameter to the resource schema you want to key completion of the translation function.
 
 the part of example:
@@ -198,14 +210,18 @@ app.get('/', c => {
   const t = useTranslation<ResourceSchema>(c)
   // you can completion when you type `t('`
   return c.json(t('hello', { name: 'hono' }))
-}),
+})
 ```
 
 ### global resource schema with `declare module '@intlify/hono'`
 
+<!-- eslint-disable markdown/no-missing-label-refs -- NOTE(kazupon): ignore github alert -->
+
 > [!NOTE]
 > The exeample code is [here](https://github.com/intlify/hono/tree/main/playground/global-schema)
 
+<!-- eslint-enable markdown/no-missing-label-refs -- NOTE(kazupon): ignore github alert -->
+
 You can do resource key completion with the translation function using the typescript `declare module`.
 
 the part of example:
@@ -226,8 +242,7 @@ app.get('/', c => {
   const t = useTranslation(c)
   // you can completion when you type `t('`
   return c.json(t('hello', { name: 'hono' }))
-}),
-
+})
 ```
 
 The advantage of this way is that it is not necessary to specify the resource schema in the `useTranslation` type parameter.
@@ -236,37 +251,11 @@ The advantage of this way is that it is not necessary to specify the resource sc
 
 `@intlify/hono` has a concept of composable utilities & helpers.
 
-### Utilities
-
-`@intlify/hono` composable utilities accept context (from
-`(context) => {})`) as their first argument. (Exclud `useTranslation`) return the [`Intl.Locale`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale)
-
-### Translations
-
-- `useTranslation(context)`: use translation function
-
-### Headers
-
-- `getHeaderLocale(context, options)`: get locale from `accept-language` header
-- `getHeaderLocales(context, options)`: get some locales from `accept-language` header
-
-### Cookies
-
-- `getCookieLocale(context, options)`: get locale from cookie
-- `setCookieLocale(context, options)`: set locale to cookie
-
-### Misc
-
-- `getPathLocale(context, options)`: get locale from path
-- `getQueryLocale(context, options)`: get locale from query
-
-## Helpers
-
-- `detectLocaleFromAcceptLanguageHeader(context)`: detect locale from `accept-language` header
+See the [API References](https://github.com/intlify/srvmid/blob/main/packages/hono/docs/index.md)
 
 ## 🙌 Contributing guidelines
 
-If you are interested in contributing to `@intlify/hono`, I highly recommend checking out [the contributing guidelines](/CONTRIBUTING.md) here. You'll find all the relevant information such as [how to make a PR](/CONTRIBUTING.md#pull-request-guidelines), [how to setup development](/CONTRIBUTING.md#development-setup)) etc., there.
+If you are interested in contributing to `@intlify/hono`, I highly recommend checking out [the contributing guidelines](https://github.com/intlify/srvmid/blob/main/CONTRIBUTING.md) here. You'll find all the relevant information such as [how to make a PR](https://github.com/intlify/srvmid/blob/main/CONTRIBUTING.md#pull-request-guidelines), [how to setup development](https://github.com/intlify/srvmid/blob/main/CONTRIBUTING.md#development-setup) etc., there.
 
 ## ©️ License
 
@@ -278,5 +267,5 @@ If you are interested in contributing to `@intlify/hono`, I highly recommend che
 [npm-version-href]: https://npmjs.com/package/@intlify/hono
 [npm-downloads-src]: https://img.shields.io/npm/dm/@intlify/hono?style=flat&colorA=18181B&colorB=FFAD33
 [npm-downloads-href]: https://npmjs.com/package/@intlify/hono
-[ci-src]: https://github.com/intlify/utils/actions/workflows/ci.yml/badge.svg
-[ci-href]: https://github.com/intlify/utils/actions/workflows/ci.yml
+[ci-src]: https://github.com/intlify/srvmid/actions/workflows/ci.yml/badge.svg
+[ci-href]: https://github.com/intlify/srvmid/actions/workflows/ci.yml

packages/hono/docs/functions/defineI18nMiddleware.md

@@ -0,0 +1,63 @@
+[**@intlify/hono**](../index.md)
+
+***
+
+[@intlify/hono](../index.md) / defineI18nMiddleware
+
+# Function: defineI18nMiddleware()
+
+```ts
+function defineI18nMiddleware<Schema, Locales, Message, Options>(options): MiddlewareHandler;
+```
+
+define i18n middleware for Hono
+
+## Type Parameters
+
+| Type Parameter | Default type |
+| ------ | ------ |
+| `Schema` | `RemoveIndexSignature`\<\{ \[`key`: `string`\]: `LocaleMessageValue`\<`string`\>; `hello`: `string`; `nest`: \{ `foo`: \{ `bar`: `string`; \}; \}; \}\> |
+| `Locales` | `string` |
+| `Message` | `string` |
+| `Options` *extends* `CoreOptions`\<`Message`, `SchemaParams`\<`Schema`, `Message`\>, `LocaleParams`\<`Locales`\>, `LocaleParams`\<`Locales`\> *extends* `object` ? `M` : `LocaleParams`\<`Locales`\> *extends* `string` ? `string` & `LocaleParams`\<`Locales`\> : `string`, `LocaleParams`\<`Locales`\> *extends* `object` ? `D` : `LocaleParams`\<`Locales`\> *extends* `string` ? `string` & `LocaleParams`\<`Locales`\> : `string`, `LocaleParams`\<`Locales`\> *extends* `object` ? `N` : `LocaleParams`\<`Locales`\> *extends* `string` ? `string` & `LocaleParams`\<`Locales`\> : `string`, `SchemaParams`\<`Schema`, `Message`\> *extends* `object` ? `M` : `LocaleMessage`\<`string`\>, `SchemaParams`\<`Schema`, `Message`\> *extends* `object` ? `D` : `DateTimeFormat`, `SchemaParams`\<`Schema`, `Message`\> *extends* `object` ? `N` : `NumberFormat`, `LocaleMessages`\<`SchemaParams`\<`Schema`, `Message`\> *extends* `object` ? `M` : `LocaleMessage`\<`string`\>, `LocaleParams`\<`Locales`\> *extends* `object` ? `M` : `LocaleParams`\<`Locales`\> *extends* `string` ? `string` & `LocaleParams`\<`Locales`\> : `string`, `Message`\>, `DateTimeFormats`\<`SchemaParams`\<`Schema`, `Message`\> *extends* `object` ? `D` : `DateTimeFormat`, `LocaleParams`\<`Locales`\> *extends* `object` ? `D` : `LocaleParams`\<`Locales`\> *extends* `string` ? `string` & `LocaleParams`\<`Locales`\> : `string`\>, `NumberFormats`\<`SchemaParams`\<`Schema`, `Message`\> *extends* `object` ? `N` : `NumberFormat`, `LocaleParams`\<`Locales`\> *extends* `object` ? `N` : `LocaleParams`\<`Locales`\> *extends* `string` ? `string` & `LocaleParams`\<`Locales`\> : `string`\>\> | `CoreOptions`\<`Message`, `SchemaParams`\<`Schema`, `Message`\>, `LocaleParams`\<`Locales`\>, `LocaleParams`\<`Locales`\> *extends* `object` ? `M` : `LocaleParams`\<`Locales`\> *extends* `string` ? `string` & `LocaleParams`\<`Locales`\> : `string`, `LocaleParams`\<`Locales`\> *extends* `object` ? `D` : `LocaleParams`\<`Locales`\> *extends* `string` ? `string` & `LocaleParams`\<`Locales`\> : `string`, `LocaleParams`\<`Locales`\> *extends* `object` ? `N` : `LocaleParams`\<`Locales`\> *extends* `string` ? `string` & `LocaleParams`\<`Locales`\> : `string`, `SchemaParams`\<`Schema`, `Message`\> *extends* `object` ? `M` : `LocaleMessage`\<`string`\>, `SchemaParams`\<`Schema`, `Message`\> *extends* `object` ? `D` : `DateTimeFormat`, `SchemaParams`\<`Schema`, `Message`\> *extends* `object` ? `N` : `NumberFormat`, `LocaleMessages`\<`SchemaParams`\<`Schema`, `Message`\> *extends* `object` ? `M` : `LocaleMessage`\<`string`\>, `LocaleParams`\<`Locales`\> *extends* `object` ? `M` : `LocaleParams`\<`Locales`\> *extends* `string` ? `string` & `LocaleParams`\<`Locales`\> : `string`, `Message`\>, `DateTimeFormats`\<`SchemaParams`\<`Schema`, `Message`\> *extends* `object` ? `D` : `DateTimeFormat`, `LocaleParams`\<`Locales`\> *extends* `object` ? `D` : `LocaleParams`\<`Locales`\> *extends* `string` ? `string` & `LocaleParams`\<`Locales`\> : `string`\>, `NumberFormats`\<`SchemaParams`\<`Schema`, `Message`\> *extends* `object` ? `N` : `NumberFormat`, `LocaleParams`\<`Locales`\> *extends* `object` ? `N` : `LocaleParams`\<`Locales`\> *extends* `string` ? `string` & `LocaleParams`\<`Locales`\> : `string`\>\> |
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `options` | `Options` | An i18n options like vue-i18n [`createI18n`]([https://vue-i18n.intlify.dev/guide/#javascript](https://vue-i18n.intlify.dev/guide/#javascript)), which are passed to `createCoreContext` of `@intlify/core`, see about details [`CoreOptions` of `@intlify/core`](https://github.com/intlify/vue-i18n-next/blob/6a9947dd3e0fe90de7be9c87ea876b8779998de5/packages/core-base/src/context.ts#L196-L216) |
+
+## Returns
+
+`MiddlewareHandler`
+
+A defined i18n middleware
+
+## Description
+
+Define the middleware to be specified for Hono [`app.use`]([https://hono.dev/guides/middleware](https://hono.dev/guides/middleware))
+
+## Example
+
+```js
+import { Hono } from 'hono'
+import { defineI18nMiddleware } from '@intlify/hono'
+
+const i18nMiddleware = defineI18nMiddleware({
+  messages: {
+    en: {
+      hello: 'Hello {name}!',
+    },
+    ja: {
+      hello: 'こんにちは、{name}！',
+    },
+  },
+  // your locale detection logic here
+  locale: (event) => {
+    // ...
+  },
+})
+
+const app = new Hono()
+app.use('*', i18nMiddleware)
+```

packages/hono/docs/functions/detectLocaleFromAcceptLanguageHeader.md

@@ -0,0 +1,47 @@
+[**@intlify/hono**](../index.md)
+
+***
+
+[@intlify/hono](../index.md) / detectLocaleFromAcceptLanguageHeader
+
+# Function: detectLocaleFromAcceptLanguageHeader()
+
+```ts
+function detectLocaleFromAcceptLanguageHeader(ctx): string;
+```
+
+locale detection with `Accept-Language` header
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `ctx` | `Context` | A Hono context |
+
+## Returns
+
+`string`
+
+A locale string, which will be detected of **first** from `Accept-Language` header
+
+## Example
+
+```js
+import { Hono } from 'hono'
+import { defineI18nMiddleware, detectLocaleWithAcceeptLanguageHeader } from '@intlify/hono'
+
+const i18nMiddleware = defineI18nMiddleware({
+  messages: {
+    en: {
+      hello: 'Hello {name}!',
+    },
+    ja: {
+      hello: 'こんにちは、{name}！',
+    },
+  },
+  locale: detectLocaleWithAcceeptLanguageHeader
+})
+
+const app = new Hono()
+app.use('*', i18nMiddleware)
+```

packages/hono/docs/functions/getCookieLocale.md

@@ -0,0 +1,48 @@
+[**@intlify/hono**](../index.md)
+
+***
+
+[@intlify/hono](../index.md) / getCookieLocale
+
+# Function: getCookieLocale()
+
+```ts
+function getCookieLocale(context, __namedParameters?): Locale;
+```
+
+get locale from cookie
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `context` | `Context` | A Context \| Hono context |
+| `__namedParameters?` | \{ `lang?`: `string`; `name?`: `string`; \} | - |
+| `__namedParameters.lang?` | `string` | - |
+| `__namedParameters.name?` | `string` | - |
+
+## Returns
+
+`Locale`
+
+The locale that resolved from cookie
+
+## Example
+
+example for Hono:
+
+```ts
+import { Hono } from 'hono'
+import { getCookieLocale } from '@intlify/utils/hono'
+
+const app = new Hono()
+app.use('/', c => {
+  const locale = getCookieLocale(c)
+  console.log(locale) // output `Intl.Locale` instance
+  // ...
+})
+```
+
+## Throws
+
+Throws a RangeError if `lang` option or cookie name value are not a well-formed BCP 47 language tag.

packages/hono/docs/functions/getHeaderLanguage.md

@@ -0,0 +1,46 @@
+[**@intlify/hono**](../index.md)
+
+***
+
+[@intlify/hono](../index.md) / getHeaderLanguage
+
+# Function: getHeaderLanguage()
+
+```ts
+function getHeaderLanguage(context, __namedParameters?): string;
+```
+
+get language from header
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `context` | `Context` | A Context \| Hono context |
+| `__namedParameters?` | `HeaderOptions` | - |
+
+## Returns
+
+`string`
+
+A **first language tag** of header, if header is not exists, or `*` (any language), return empty string.
+
+## Description
+
+parse header string, default `accept-language`. if you use `accept-language`, this function retuns the **first language tag** of `accept-language` header.
+
+## Example
+
+example for Hone:
+
+```ts
+import { Hono } from 'hono'
+import { getHeaderLanguage } from '@intlify/utils/hono'
+
+const app = new Hono()
+app.use('/', c => {
+  const langTag = getHeaderLanguage(c)
+  // ...
+  return c.text(`accepted language: ${langTag}`)
+})
+```