fix: add docs

Author: kazupon

.prettierignore

@@ -1 +1,2 @@
 pnpm-lock.yaml
+docs

README.md

@@ -333,38 +333,7 @@ The advantage of this way is that it is not necessary to specify the resource sc
 
 `@intlify/h3` has a concept of composable utilities & helpers.
 
-### Utilities
-
-`@intlify/h3` composable utilities accept event (from
-`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, asynchronous
-
-### Headers
-
-- `getHeaderLocale(event, options)`: get locale from `accept-language` header
-- `getHeaderLocales(event, options)`: get some locales from `accept-language` header
-- `tryHeaderLocale(event, options)`: try to get locale from `accept-language` header
-- `tryHeaderLocales(event, options)`: try to get some locales from `accept-language` header
-
-### Cookies
-
-- `getCookieLocale(event, options)`: get locale from cookie
-- `tryCookieLocale(event, options)`: try to get locale from cookie
-- `setCookieLocale(event, options)`: set locale to cookie
-
-### Misc
-
-- `getPathLocale(event, options)`: get locale from path
-- `tryPathLocale(event, options)`: try to get locale from path
-- `getQueryLocale(event, options)`: get locale from query
-- `tryQueryLocale(event, options)`: try to get locale from query
-
-## Helpers
-
-- `detectLocaleFromAcceptLanguageHeader(event)`: detect locale from `accept-language` header
+See the [API References](./docs/index.md)
 
 ## 🙌 Contributing guidelines
 

docs/functions/defineI18nMiddleware.md

@@ -0,0 +1,61 @@
+[**@intlify/h3**](../index.md)
+
+***
+
+[@intlify/h3](../index.md) / defineI18nMiddleware
+
+# Function: defineI18nMiddleware()
+
+```ts
+function defineI18nMiddleware<Schema, Locales, Message, Options>(options): I18nMiddleware;
+```
+
+define i18n middleware for h3
+
+## Type Parameters
+
+| Type Parameter | Default type |
+| ------ | ------ |
+| `Schema` | `RemoveIndexSignature`\<\{ \[`key`: `string`\]: `LocaleMessageValue`\<`string`\>; `hello`: `string`; `nest`: \{ `foo`: \{ `bar`: `string`; \}; \}; `test`: `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
+
+[`I18nMiddleware`](../interfaces/I18nMiddleware.md)
+
+A defined i18n middleware, which is included `onRequest` and `onAfterResponse` options of `createApp`
+
+## Example
+
+```js
+import { defineI18nMiddleware } from '@intlify/h3'
+
+const middleware = defineI18nMiddleware({
+  messages: {
+    en: {
+      hello: 'Hello {name}!',
+    },
+    ja: {
+      hello: 'こんにちは、{name}！',
+    },
+  },
+  // your locale detection logic here
+  locale: (event) => {
+    // ...
+  },
+})
+
+const app = createApp({ ...middleware })
+```
+
+## Description
+
+Define the middleware to be specified for h3 [`createApp`]([https://www.jsdocs.io/package/h3#createApp](https://www.jsdocs.io/package/h3#createApp))

docs/functions/detectLocaleFromAcceptLanguageHeader.md

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

docs/functions/getCookieLocale.md

@@ -0,0 +1,47 @@
+[**@intlify/h3**](../index.md)
+
+***
+
+[@intlify/h3](../index.md) / getCookieLocale
+
+# Function: getCookieLocale()
+
+```ts
+function getCookieLocale(event, __namedParameters?): Locale;
+```
+
+get locale from cookie
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `event` | `H3Event` | The H3Event \| H3 event |
+| `__namedParameters?` | \{ `lang?`: `string`; `name?`: `string`; \} | - |
+| `__namedParameters.lang?` | `string` | - |
+| `__namedParameters.name?` | `string` | - |
+
+## Returns
+
+`Locale`
+
+The locale that resolved from cookie
+
+## Example
+
+example for h3:
+
+```ts
+import { createApp, eventHandler } from 'h3'
+import { getCookieLocale } from '@intlify/utils/h3'
+
+app.use(eventHandler(event) => {
+  const locale = getCookieLocale(event)
+  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.

docs/functions/getHeaderLanguage.md

@@ -0,0 +1,46 @@
+[**@intlify/h3**](../index.md)
+
+***
+
+[@intlify/h3](../index.md) / getHeaderLanguage
+
+# Function: getHeaderLanguage()
+
+```ts
+function getHeaderLanguage(event, __namedParameters?): string;
+```
+
+get language from header
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `event` | `H3Event` | The H3Event \| H3 event |
+| `__namedParameters?` | `HeaderOptions` | - |
+
+## Returns
+
+`string`
+
+The **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 h3:
+
+```ts
+import { createApp, eventHandler } from 'h3'
+import { getAcceptLanguage } from '@intlify/utils/h3'
+
+const app = createApp()
+app.use(eventHandler(event) => {
+  const langTag = getHeaderLanguage(event)
+  // ...
+  return `accepted language: ${langTag}`
+})
+```

docs/functions/getHeaderLanguages.md

@@ -0,0 +1,46 @@
+[**@intlify/h3**](../index.md)
+
+***
+
+[@intlify/h3](../index.md) / getHeaderLanguages
+
+# Function: getHeaderLanguages()
+
+```ts
+function getHeaderLanguages(event, __namedParameters?): string[];
+```
+
+get languages from header
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `event` | `H3Event` | The H3Event \| H3 event |
+| `__namedParameters?` | `HeaderOptions` | - |
+
+## Returns
+
+`string`[]
+
+The array of language tags, if you use `accept-language` header and `*` (any language) or empty string is detected, return an empty array.
+
+## Description
+
+parse header string, default `accept-language` header
+
+## Example
+
+example for h3:
+
+```ts
+import { createApp, eventHandler } from 'h3'
+import { getHeaderLanguages } from '@intlify/utils/h3'
+
+const app = createApp()
+app.use(eventHandler(event) => {
+  const langTags = getHeaderLanguages(event)
+  // ...
+  return `accepted languages: ${acceptLanguages.join(', ')}`
+})
+```

docs/functions/getHeaderLocale.md

@@ -0,0 +1,49 @@
+[**@intlify/h3**](../index.md)
+
+***
+
+[@intlify/h3](../index.md) / getHeaderLocale
+
+# Function: getHeaderLocale()
+
+```ts
+function getHeaderLocale(event, __namedParameters?): Locale;
+```
+
+get locale from header
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `event` | `H3Event` | The H3Event \| H3 event |
+| `__namedParameters?` | `HeaderOptions` & `object` | - |
+
+## Returns
+
+`Locale`
+
+The first locale that resolved from header string. if you use `accept-language` header and `*` (any language) or empty string is detected, return `en-US`.
+
+## Description
+
+wrap language tag with Intl.Locale \| locale, languages tags will be parsed from `accept-language` header as default.
+
+## Example
+
+example for h3:
+
+```ts
+import { createApp, eventHandler } from 'h3'
+import { getHeaderLocale } from '@intlify/utils/h3'
+
+app.use(eventHandler(event) => {
+  const locale = getHeaderLocale(event)
+  // ...
+  return `accepted locale: ${locale.toString()}`
+})
+```
+
+## Throws
+
+Throws the RangeError if `lang` option or header are not a well-formed BCP 47 language tag.

docs/functions/getHeaderLocales.md

@@ -0,0 +1,49 @@
+[**@intlify/h3**](../index.md)
+
+***
+
+[@intlify/h3](../index.md) / getHeaderLocales
+
+# Function: getHeaderLocales()
+
+```ts
+function getHeaderLocales(event, __namedParameters?): Locale[];
+```
+
+get locales from header
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `event` | `H3Event` | The H3Event \| H3 event |
+| `__namedParameters?` | `HeaderOptions` | - |
+
+## Returns
+
+`Locale`[]
+
+The locales that wrapped from header, if you use `accept-language` header and `*` (any language) or empty string is detected, return an empty array.
+
+## Description
+
+wrap language tags with Intl.Locale \| locale, languages tags will be parsed from `accept-language` header as default.
+
+## Example
+
+example for h3:
+
+```ts
+import { createApp, eventHandler } from 'h3'
+import { getHeaderLocales } from '@intlify/utils/h3'
+
+app.use(eventHandler(event) => {
+  const locales = getHeaderLocales(event)
+  // ...
+  return `accepted locales: ${locales.map(locale => locale.toString()).join(', ')}`
+})
+```
+
+## Throws
+
+Throws the RangeError if header are not a well-formed BCP 47 language tag.