Internationalization middleware & utilities for Hono
โ ๏ธ ย Translation: Simple API like vue-i18n
โ ย Custom locale detector: You can implement your own locale detector on server-side
โ ๏ธ๏ธ ย Useful utilities: support internationalization composables utilities via @intlify/utils
# Using npm
npm install @intlify/hono
# Using yarn
yarn add @intlify/hono
# Using pnpm
pnpm add @intlify/hono
# Using bun
bun add @intlify/honoimport { Hono } from 'hono'
import {
defineI18nMiddleware,
detectLocaleFromAcceptLanguageHeader,
useTranslation,
} from '@intlify/hono'
// define middleware with vue-i18n like options
const i18nMiddleware = defineI18nMiddleware({
// detect locale with `accept-language` header
locale: detectLocaleFromAcceptLanguageHeader,
// resource messages
messages: {
en: {
hello: 'Hello {name}!',
},
ja: {
hello: 'ใใใซใกใฏใ{name}๏ผ',
},
},
// something options
// ...
})
const app = new Hono()
// install middleware with `app.use`
app.use('*', i18nMiddleware)
app.get('/', c => {
// use `useTranslation` in handler
const t = useTranslation(c)
return c.text(t('hello', { name: 'hono' }) + `\n`)
})
export default appYou can detect locale with your custom logic from current Context.
example for detecting locale from url query:
import { defineI18nMiddleware, getQueryLocale } from '@intlify/hono'
import type { Context } from 'hono'
const DEFAULT_LOCALE = 'en'
// define custom locale detector
const localeDetector = (ctx: Context): string => {
try {
return getQueryLocale(ctx).toString()
} catch () {
return DEFAULT_LOCALE
}
}
const middleware = defineI18nMiddleware({
// set your custom locale detector
locale: localeDetector,
// something options
// ...
})Warning
This is experimental feature (inspired from vue-i18n). We would like to get feedback from you ๐.
Note
The exeample code is here
You can support the type-safe resources with schema using TypeScript on defineI18nMiddleware options.
Locale messages resource:
export default {
hello: 'hello, {name}!'
}your application code:
import { defineI18nMiddleware } from '@intlify/hono'
import en from './locales/en.ts'
// define resource schema, as 'en' is master resource schema
type ResourceSchema = typeof en
const i18nMiddleware = defineI18nMiddleware<[ResourceSchema], 'en' | 'ja'>({
messages: {
en: { hello: 'Hello, {name}' },
},
// something options
// ...
})
// someting your implementation code ...
// ...Result of type checking with tsc:
npx tsc --noEmit
index.ts:13:3 - error TS2741: Property 'ja' is missing in type '{ en: { hello: string; }; }' but required in type '{ en: ResourceSchema; ja: ResourceSchema; }'.
13 messages: {
~~~~~~~~
../../node_modules/@intlify/core/node_modules/@intlify/core-base/dist/core-base.d.ts:125:5
125 messages?: {
~~~~~~~~
The expected type comes from property 'messages' which is declared here on type 'CoreOptions<string, { message: ResourceSchema; datetime: DateTimeFormat; number: NumberFormat; }, { messages: "en"; datetimeFormats: "en"; numberFormats: "en"; } | { ...; }, ... 8 more ..., NumberFormats<...>>'
Found 1 error in index.ts:13If you are using Visual Studio Code as an editor, you can notice that there is a resource definition omission in the editor with the following error before you run the typescript compilation.
Warning
This is experimental feature (inspired from vue-i18n). We would like to get feedback from you ๐.
Note
Resource Keys completion can be used if you are using Visual Studio Code
You can completion resources key on translation function with useTranslation.
resource keys completion has twe ways.
Note
The exeample code is here
You can useTranslation set the type parameter to the resource schema you want to key completion of the translation function.
the part of example:
app.get('/', c => {
type ResourceSchema = {
hello: string
}
// set resource schema as type parameter
const t = useTranslation<ResourceSchema>(c)
// you can completion when you type `t('`
return c.json(t('hello', { name: 'hono' }))
}),Note
The exeample code is here
You can do resource key completion with the translation function using the typescript declare module.
the part of example:
import en from './locales/en.ts'
// 'en' resource is master schema
type ResourceSchema = typeof en
// you can put the type extending with `declare module` as global resource schema
declare module '@intlify/hono' {
// extend `DefineLocaleMessage` with `ResourceSchema`
export interface DefineLocaleMessage extends ResourceSchema {}
}
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.
@intlify/hono has a concept of composable utilities & helpers.
@intlify/hono composable utilities accept context (from
(context) => {})) as their first argument. (Exclud useTranslation) return the Intl.Locale
useTranslation(context): use translation function
getHeaderLocale(context, options): get locale fromaccept-languageheadergetHeaderLocales(context, options): get some locales fromaccept-languageheader
getCookieLocale(context, options): get locale from cookiesetCookieLocale(context, options): set locale to cookie
getPathLocale(context, options): get locale from pathgetQueryLocale(context, options): get locale from query
detectLocaleFromAcceptLanguageHeader(context): detect locale fromaccept-languageheader
If you are interested in contributing to @intlify/hono, I highly recommend checking out the contributing guidelines here. You'll find all the relevant information such as how to make a PR, how to setup development) etc., there.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent