Internationalization for Hono

🌟 Features

✅️️  Internationalization utilities: support internationalization utils via @intlify/utils

✅️  Translation: Simple API like vue-i18n

✅  Custom locale detector: You can implement your own locale detector on server-side

💿 Installation

# Using npm
npm install @intlify/hono

# Using yarn
yarn add @intlify/hono

# Using pnpm
pnpm add @intlify/hono

# Using bun
bun add @intlify/hono

🚀 Usage

Detect locale with utils

Detect locale from accept-language header:

import { Hono } from 'hono'
import { getHeaderLocale } from '@intlify/h3'

const app = new Hono()

app.get('/', c => {
  // detect locale from HTTP header which has `Accept-Language: ja,en-US;q=0.7,en;q=0.3`
  const locale = getHeaderLocale(c.req.raw)
  return c.text(locale.toString())
})

Detect locale from URL query:

import { Hono } from 'hono'
import { getQueryLocale } from '@intlify/h3'

const app = new Hono()

app.get('/', c => {
  // detect locale from query which has 'http://localhost:3000?locale=en'
  const locale = getQueryLocale(c.req.raw)
  return c.text(locale.toString())
})

Translation

If you want to use translation, you need to install intlify middleware. As a result, you can use useTranslation within the handler:

import { Hono } from 'hono'
import {
  defineIntlifyMiddleware,
  detectLocaleFromAcceptLanguageHeader,
  useTranslation
} from '@intlify/hono'

// define middleware with vue-i18n like options
const intlify = defineIntlifyMiddleware({
  // 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 intlify middleware with `app.use`
app.use('*', intlify)

app.get('/', async c => {
  // use `useTranslation` in handler
  const t = await useTranslation(c)
  return c.text(t('hello', { name: 'hono' }) + `\n`)
})

export default app

🛠️ Custom locale detection

You can detect locale with your custom logic from current Context.

example for detecting locale from url query, and get locale with getDetectorLocale util:

import { Hono } from 'hono'
import { defineIntlifyMiddleware, getQueryLocale, getDetectorLocale } from '@intlify/hono'
import type { Context } from 'hono'

const DEFAULT_LOCALE = 'en'

// define custom locale detector
const localeDetector = (c: Context): string => {
  try {
    return getQueryLocale(c.req.raw).toString()
  } catch {
    return DEFAULT_LOCALE
  }
}

const intlify = defineIntlifyMiddleware({
  // set your custom locale detector
  locale: localeDetector
  // something options
  // ...
})

const app = new Hono()
app.use('*', intlify)
app.get('/', async c => {
  const locale = await getDetectorLocale(c)
  return c.text(`Current Locale: ${locale.language}`)
})

You can make that function asynchronous. This is useful when loading resources along with locale detection.

[!NOTE] The case which a synchronous function returns a promise is not supported. you need to use async function.

import { Hono } from 'hono'
import { defineIntlifyMiddleware, getCookieLocale } from '@intlify/hono'

import type { Context } from 'hono'
import type { DefineLocaleMessage, CoreContext } from '@intlify/h3'

const loader = (path: string) => import(path).then(m => m.default)
const messages: Record<string, () => ReturnType<typeof loader>> = {
  en: () => loader('./locales/en.json'),
  ja: () => loader('./locales/ja.json')
}

// define custom locale detector and lazy loading
const localeDetector = async (
  c: Context,
  intlify: CoreContext<string, DefineLocaleMessage>
): Promise<string> => {
  // detect locale
  const locale = getCookieLocale(c.req.raw).toString()

  // resource lazy loading
  const loader = messages[locale]
  if (loader && !intlify.messages[locale]) {
    const message = await loader()
    intlify.messages[locale] = message
  }

  return locale
}

const intlify = defineIntlifyMiddleware({
  // set your custom locale detector
  locale: localeDetector
  // something options
  // ...
})

🖌️ Resource keys completion

[!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.

Type parameter for useTranslation

[!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('/', async c => {
  type ResourceSchema = {
    hello: string
  }
  // set resource schema as type parameter
  const t = await 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'

[!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('/', async c => {
  const t = await 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.

🛠️ Utilities & Helpers

@intlify/hono has a concept of composable utilities & helpers.

See the API References

🙌 Contributing guidelines

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.

🤝 Sponsors

The development of srvmid is supported by my OSS sponsors!

©️ License

MIT