@intlify/h3/dist/index.d.mts

Internationalization for H3

import { CoreContext, CoreContext as CoreContext$1, CoreOptions, IsEmptyObject, Locale, LocaleDetector, LocaleMessage, LocaleParams, NamedValue, PickupPaths, RemoveIndexSignature, RemovedIndexResources, SchemaParams, TranslateOptions } from "@intlify/core";
import { getCookieLocale, getHeaderLanguage, getHeaderLanguages, getHeaderLocale, getHeaderLocales, getPathLocale, getQueryLocale, setCookieLocale, tryCookieLocale, tryHeaderLocale, tryHeaderLocales, tryPathLocale, tryQueryLocale } from "@intlify/utils";
import * as h30 from "h3";
import { H3Event, Middleware } from "h3";

//#region src/symbols.d.ts
/**
* @author kazuya kawaguchi (a.k.a. kazupon)
* @license MIT
*/
/**
 * defined symbols
 */
/**
 * @author kazuya kawaguchi (a.k.a. kazupon)
 * @license MIT
 */
declare const SYMBOL_INTLIFY: unique symbol;
declare const SYMBOL_INTLIFY_LOCALE: unique symbol;
//#endregion
//#region ../shared/src/types.d.ts
type ResolveResourceKeys<Schema extends Record<string, any> = {},
// eslint-disable-line @typescript-eslint/no-explicit-any -- NOTE(kazupon): generic type
DefineLocaleMessageSchema extends Record<string, any> = {},
// eslint-disable-line @typescript-eslint/no-explicit-any -- NOTE(kazupon): generic type
DefinedLocaleMessage extends RemovedIndexResources<DefineLocaleMessageSchema> = RemovedIndexResources<DefineLocaleMessageSchema>, SchemaPaths = (IsEmptyObject<Schema> extends false ? PickupPaths<{ [K in keyof Schema]: Schema[K] }> : never), DefineMessagesPaths = (IsEmptyObject<DefinedLocaleMessage> extends false ? PickupPaths<{ [K in keyof DefinedLocaleMessage]: DefinedLocaleMessage[K] }> : never)> = SchemaPaths | DefineMessagesPaths;
/**
 * The translation function, which will be defined by translation
 */
interface TranslationFunction<Schema extends Record<string, any> = {},
// eslint-disable-line @typescript-eslint/no-explicit-any -- NOTE(kazupon): generic type
DefineLocaleMessageSchema extends Record<string, any> = {},
// eslint-disable-line @typescript-eslint/no-explicit-any -- NOTE(kazupon): generic type
ResourceKeys = ResolveResourceKeys<Schema, DefineLocaleMessageSchema>> {
  /**
   * @param {Key | ResourceKeys} key - A translation key
   * @returns {string} A translated message, if the key is not found, return the key
   */
  <Key extends string>(key: Key | ResourceKeys): string;
  /**
   * @param {Key | ResourceKeys} key - A translation key
   * @param {number} plural - A plural choice number
   * @returns {string} A translated message, if the key is not found, return the key
   */
  <Key extends string>(key: Key | ResourceKeys, plural: number): string;
  /**
   * @param {Key | ResourceKeys} key - A translation key
   * @param {number} plural - A plural choice number
   * @param {TranslateOptions} options - A translate options, about details see {@link TranslateOptions}
   * @returns {string} A translated message, if the key is not found, return the key
   */
  <Key extends string>(key: Key | ResourceKeys, plural: number, options: TranslateOptions): string;
  /**
   * @param {Key | ResourceKeys} key - A translation key
   * @param {string} defaultMsg - A default message, if the key is not found
   * @returns {string} A translated message, if the key is not found, return the `defaultMsg` argument
   */
  <Key extends string>(key: Key | ResourceKeys, defaultMsg: string): string;
  /**
   * @param {Key | ResourceKeys} key - A translation key
   * @param {string} defaultMsg - A default message, if the key is not found
   * @param {TranslateOptions} options - A translate options, about details see {@link TranslateOptions}
   * @returns {string} A translated message, if the key is not found, return the `defaultMsg` argument
   */
  <Key extends string>(key: Key | ResourceKeys, defaultMsg: string, options: TranslateOptions): string;
  /**
   * @param {Key | ResourceKeys} key - A translation key
   * @param {unknown[]} list - A list for list interpolation
   * @returns {string} A translated message, if the key is not found, return the key
   */
  <Key extends string>(key: Key | ResourceKeys, list: unknown[]): string;
  /**
   * @param {Key | ResourceKeys} key - A translation key
   * @param {unknown[]} list - A list for list interpolation
   * @param {number} plural - A plural choice number
   * @returns {string} A translated message, if the key is not found, return the key
   */
  <Key extends string>(key: Key | ResourceKeys, list: unknown[], plural: number): string;
  /**
   * @param {Key | ResourceKeys} key - A translation key
   * @param {unknown[]} list - A list for list interpolation
   * @param {string} defaultMsg - A default message, if the key is not found
   * @returns {string} A translated message, if the key is not found, return the `defaultMsg` argument
   */
  <Key extends string>(key: Key | ResourceKeys, list: unknown[], defaultMsg: string): string;
  /**
   * @param {Key | ResourceKeys} key - A translation key
   * @param {unknown[]} list - A list for list interpolation
   * @param {TranslateOptions} options - A translate options, about details see {@link TranslateOptions}
   * @returns {string} A translated message, if the key is not found, return the key
   */
  <Key extends string>(key: Key | ResourceKeys, list: unknown[], options: TranslateOptions): string;
  /**
   * @param {Key | ResourceKeys} key - A translation key
   * @param {NamedValue} named - A named value for named interpolation
   * @returns {string} A translated message, if the key is not found, return the key
   */
  <Key extends string>(key: Key | ResourceKeys, named: NamedValue): string;
  /**
   * @param {Key | ResourceKeys} key - A translation key
   * @param {NamedValue} named - A named value for named interpolation
   * @param {number} plural - A plural choice number
   * @returns {string} A translated message, if the key is not found, return the key
   */
  <Key extends string>(key: Key | ResourceKeys, named: NamedValue, plural: number): string;
  /**
   * @param {Key | ResourceKeys} key - A translation key
   * @param {NamedValue} named - A named value for named interpolation
   * @param {string} defaultMsg - A default message, if the key is not found
   * @returns {string} A translated message, if the key is not found, return the `defaultMsg` argument
   */
  <Key extends string>(key: Key | ResourceKeys, named: NamedValue, defaultMsg: string): string;
  /**
   * @param {Key | ResourceKeys} key - A translation key
   * @param {NamedValue} named - A named value for named interpolation
   * @param {TranslateOptions} options - A translate options, about details see {@link TranslateOptions}
   * @returns {string} A translated message, if the key is not found, return the key
   */
  <Key extends string>(key: Key | ResourceKeys, named: NamedValue, options: TranslateOptions): string;
}
//#endregion
//#region src/index.d.ts
declare module 'h3' {
  interface H3EventContext {
    [SYMBOL_INTLIFY]?: CoreContext$1;
    [SYMBOL_INTLIFY_LOCALE]?: LocaleDetector;
  }
}
type DefaultLocaleMessageSchema<Schema = RemoveIndexSignature<{ [K in keyof DefineLocaleMessage]: DefineLocaleMessage[K] }>> = IsEmptyObject<Schema> extends true ? LocaleMessage<string> : Schema;
/**
 * Internationalization middleware for H3
 */
interface IntlifyMiddleware {
  /**
   * Request middleware which is defined with [`onRequest`](https://h3.dev/utils/more#onrequesthook)
   */
  onRequest: Middleware;
  /**
   * Response middleware which is defined with [`onResponse`](https://h3.dev/utils/more#onresponsehook)
   */
  onResponse: Middleware;
}
/**
 * Internationalization plugin options for H3
 *
 * @typeParam Schema - Locale message schema type, default is {@linkcode DefaultLocaleMessageSchema}
 * @typeParam Locales - Locale type, default is `string`
 * @typeParam Message - Message type, default is `string`
 */
type IntlifyPluginOptions<Schema = DefaultLocaleMessageSchema, Locales = string, Message = string> = CoreOptions<Message, SchemaParams<Schema, Message>, LocaleParams<Locales>>;
/**
 * Internationalization plugin for H3
 *
 * @example
 * ```ts
 * import { H3 } from 'h3'
 * import { intlify } from '@intlify/h3'
 *
 * const app = new H3({
 *   plugins: [
 *     intlify({
 *       messages: {
 *         en: {
 *           hello: 'Hello {name}!',
 *         },
 *         ja: {
 *           hello: 'こんにちは、{name}！',
 *         },
 *       },
 *       // your locale detection logic here
 *       locale: (event) => {
 *         // ...
 *       },
 *     })
 *   ]
 * })
 */
declare const intlify: (options: IntlifyPluginOptions<LocaleMessage<string>, string, string>) => h30.H3Plugin;
/**
 * Define internationalization middleware for H3
 *
 * Define the middleware to be specified the bellows:
 *
 * - [`H3.use`]({@link https://h3.dev/guide/api/h3#h3use})
 *
 * @example
 *
 * ```js
 * import { H3 } from 'h3'
 * import { defineIntlifyMiddleware } from '@intlify/h3'
 *
 * const intlifyMiddleware = defineIntlifyMiddleware({
 *   messages: {
 *     en: {
 *       hello: 'Hello {name}!',
 *     },
 *     ja: {
 *       hello: 'こんにちは、{name}！',
 *     },
 *   },
 *   // your locale detection logic here
 *   locale: (event) => {
 *     // ...
 *   },
 * })
 *
 * const app = new H3()
 *   .use(intlifyMiddleware.onRequest) // register `onRequest` hook before your application middlewares
 *   .use(intlifyMiddleware.onResponse) // register `onResponse` hook before your application middlewares
 * ```
 *
 * @param options - An `i18n` options like vue-i18n [`createI18n`]({@link 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 A defined internationalization middleware, which is included `onRequest` and `onResponse` options of `H3`
 *
 * @internal
 */
declare function defineIntlifyMiddleware<Schema = DefaultLocaleMessageSchema, Locales = string, Message = string, Options extends CoreOptions<Message, SchemaParams<Schema, Message>, LocaleParams<Locales>> = CoreOptions<Message, SchemaParams<Schema, Message>, LocaleParams<Locales>>>(options: Options): IntlifyMiddleware;
/**
 * Locale detection with `Accept-Language` header
 *
 * @example
 * ```js
 * import { H3 } from 'h3'
 * import { defineIntlifyMiddleware, detectLocaleFromAcceptLanguageHeader } from '@intlify/h3'
 *
 * const intlifyMiddleware = defineIntlifyMiddleware({
 *   messages: {
 *     en: {
 *       hello: 'Hello {name}!',
 *     },
 *     ja: {
 *       hello: 'こんにちは、{name}！',
 *     },
 *   },
 *   locale: detectLocaleFromAcceptLanguageHeader
 * })
 *
 * const app = new H3()
 *   .use(intlifyMiddleware.onRequest)
 *   .use(intlifyMiddleware.onResponse)
 * ```
 *
 * @param event - A H3 event
 *
 * @returns A locale string, which will be detected of **first** from `Accept-Language` header
 */
declare const detectLocaleFromAcceptLanguageHeader: (event: H3Event) => Locale;
/**
 * The type definition of Locale Message for `@intlify/h3` package
 *
 * @example
 * ```ts
 * // type.d.ts (`.d.ts` file at your app)
 * import { DefineLocaleMessage } from '@intlify/h3'
 *
 * declare module '@intlify/h3' {
 *   export interface DefineLocaleMessage {
 *     title: string
 *     menu: {
 *       login: string
 *     }
 *   }
 * }
 * ```
 */
interface DefineLocaleMessage extends LocaleMessage<string> {}
/**
 * Use translation function in event handler
 *
 * @example
 * ```js
 * app.get(
 *   '/',
 *   async (event) => {
 *     const t = await useTranslation(event)
 *     return t('hello', { name: 'H3' })
 *   },
 * )
 * ```
 *
 * @param event - A H3 event
 *
 * @returns Return a translation function, which can be translated with internationalization resource messages
 */
declare 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>>;
/**
 * 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
 */
declare function getDetectorLocale(event: H3Event): Promise<Intl.Locale>;
//#endregion
export { type CoreContext, DefineLocaleMessage, IntlifyMiddleware, IntlifyPluginOptions, defineIntlifyMiddleware, detectLocaleFromAcceptLanguageHeader, getCookieLocale, getDetectorLocale, getHeaderLanguage, getHeaderLanguages, getHeaderLocale, getHeaderLocales, getPathLocale, getQueryLocale, intlify, setCookieLocale, tryCookieLocale, tryHeaderLocale, tryHeaderLocales, tryPathLocale, tryQueryLocale, useTranslation };
//# sourceMappingURL=index.d.mts.map