From 0e8a660f4e8dcf04ed83e3e89f19e1a315d3fce6 Mon Sep 17 00:00:00 2001 From: kazuya kawaguchi Date: Thu, 21 Sep 2023 01:35:20 +0900 Subject: [PATCH] refactor: add example case --- src/h3.ts | 30 +++++++++++++++++++++++++++++- src/node.ts | 29 ++++++++++++++++++++++++++++- src/web.ts | 31 ++++++++++++++++++++++++++++++- 3 files changed, 87 insertions(+), 3 deletions(-) diff --git a/src/h3.ts b/src/h3.ts index 447265c..bfaffe1 100644 --- a/src/h3.ts +++ b/src/h3.ts @@ -8,6 +8,20 @@ import type { H3Event } from 'h3' * * @description parse `accept-language` header string * + * @example + * example for h3 event: + * + * ```ts + * import { createApp, eventHandler } from 'h3' + * import { getAcceptLanguages } from '@intlify/utils/h3' + * + * const app = createApp() + * app.use(eventHandler(event) => { + * const acceptLanguages = getAcceptLanguages(event) + * // ... + * }) + * ``` + * * @param {H3Event} event The {@link H3Event | H3} event * * @returns {Array} The array of language tags, if `*` (any language) or empty string is detected, return an empty array. @@ -23,12 +37,26 @@ export function getAcceptLanguages(event: H3Event): string[] { /** * get locale * + * @example + * example for h3 event: + * + * ```ts + * import { createApp, eventHandler } from 'h3' + * import { getAcceptLanguages } from '@intlify/utils/h3' + * + * app.use(eventHandler(event) => { + * const locale = getLocale(event) + * console.log(locale) // output `Intl.Locale` instance + * // ... + * }) + * ``` + * * @param {H3Event} event The {@link H3Event | H3} event * @param {string} lang The default language tag, default is `en-US`. You must specify the language tag with the {@link https://datatracker.ietf.org/doc/html/rfc4646#section-2.1 | BCP 47 syntax}. * * @throws {RangeError} Throws a {@link RangeError} if `lang` option or `accpet-languages` are not a well-formed BCP 47 language tag. * - * @returns {Intl.Locale} The locale that resolved from `accept-language` header string, first language tag is used. if `*` (any language) or empty string is detected, return `en-US`. + * @returns {Intl.Locale} The first locale that resolved from `accept-language` header string, first language tag is used. if `*` (any language) or empty string is detected, return `en-US`. */ export function getLocale(event: H3Event, lang = 'en-US'): Intl.Locale { return getLocaleWithGetter(() => getAcceptLanguages(event)[0] || lang) diff --git a/src/node.ts b/src/node.ts index 9b74fab..a453b88 100644 --- a/src/node.ts +++ b/src/node.ts @@ -6,6 +6,19 @@ import { getAcceptLanguagesFromGetter, getLocaleWithGetter } from './http.ts' * * @description parse `accept-language` header string * + * @example + * example for Node.js request: + * + * ```ts + * import { createServer } from 'node:http' + * import { getAcceptLanguages } from '@intlify/utils/node' + * + * const server = createServer((req, res) => { + * const acceptLanguages = getAcceptLanguages(req) + * // ... + * }) + * ``` + * * @param {IncomingMessage} event The {@link IncomingMessage | request} * * @returns {Array} The array of language tags, if `*` (any language) or empty string is detected, return an empty array. @@ -18,12 +31,26 @@ export function getAcceptLanguages(req: IncomingMessage) { /** * get locale * + * @example + * example for Node.js request: + * + * ```ts + * import { createServer } from 'node:http' + * import { getAcceptLanguages } from '@intlify/utils/node' + * + * const server = createServer((req, res) => { + * const locale = getLocale(req) + * console.log(locale) // output `Intl.Locale` instance + * // ... + * }) + * ``` + * * @param {IncomingMessage} event The {@link IncomingMessage | request} * @param {string} lang The default language tag, default is `en-US`. You must specify the language tag with the {@link https://datatracker.ietf.org/doc/html/rfc4646#section-2.1 | BCP 47 syntax}. * * @throws {RangeError} Throws a {@link RangeError} if `lang` option or `accpet-languages` are not a well-formed BCP 47 language tag. * - * @returns {Intl.Locale} The locale that resolved from `accept-language` header string, first language tag is used. if `*` (any language) or empty string is detected, return `en-US`. + * @returns {Intl.Locale} The first locale that resolved from `accept-language` header string, first language tag is used. if `*` (any language) or empty string is detected, return `en-US`. */ export function getLocale(req: IncomingMessage, lang = 'en-US'): Intl.Locale { return getLocaleWithGetter(() => getAcceptLanguages(req)[0] || lang) diff --git a/src/web.ts b/src/web.ts index 1cc53ea..3198a47 100644 --- a/src/web.ts +++ b/src/web.ts @@ -5,6 +5,21 @@ import { getAcceptLanguagesFromGetter, getLocaleWithGetter } from './http.ts' * * @description parse `accept-language` header string * + * @example + * example for Web API request on Deno: + * + * ```ts + * import { getAcceptLanguages } from 'https://esm.sh/@intlify/utils/web' + * + * Deno.serve({ + * port: 8080, + * }, (req) => { + * const acceptLanguages = getAcceptLanguages(req) + * // ... + * return new Response('Hello World!') + * }) + * ``` + * * @param {Request} event The {@link Request | request} * * @returns {Array} The array of language tags, if `*` (any language) or empty string is detected, return an empty array. @@ -17,12 +32,26 @@ export function getAcceptLanguages(req: Request) { /** * get locale * + * @example + * example for Web API request on Bun: + * + * import { getAcceptLanguages } from '@intlify/utils/web' + * + * Bun.serve({ + * port: 8080, + * fetch(req) { + * const locale = getLocale(req) + * console.log(locale) // output `Intl.Locale` instance + * // ... + * }, + * }) + * * @param {Request} event The {@link Request | request} * @param {string} lang The default language tag, default is `en-US`. You must specify the language tag with the {@link https://datatracker.ietf.org/doc/html/rfc4646#section-2.1 | BCP 47 syntax}. * * @throws {RangeError} Throws a {@link RangeError} if `lang` option or `accpet-languages` are not a well-formed BCP 47 language tag. * - * @returns {Intl.Locale} The locale that resolved from `accept-language` header string, first language tag is used. if `*` (any language) or empty string is detected, return `en-US`. + * @returns {Intl.Locale} The first locale that resolved from `accept-language` header string, first language tag is used. if `*` (any language) or empty string is detected, return `en-US`. */ export function getLocale(req: Request, lang = 'en-US'): Intl.Locale { return getLocaleWithGetter(() => getAcceptLanguages(req)[0] || lang)