@intlify/h3

Internationalization middleware & utilities for h3

🌟 Features

✅️ 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

💿 Installation

# Using npm
npm install @intlify/h3

# Using yarn
yarn add @intlify/h3

# Using pnpm
pnpm add @intlify/h3

# Using bun
bun add @intlify/h3

🚀 Usage

import { createServer } from 'node:http'
import { createApp, createRouter, eventHandler, toNodeListener } from 'h3'
import {
  defineI18nMiddleware,
  detectLocaleFromAcceptLanguageHeader,
  useTranslation,
} from '@intlify/h3'

// define middleware with vue-i18n like options
const middleware = defineI18nMiddleware({
  // detect locale with `accept-language` header
  locale: detectLocaleFromAcceptLanguageHeader,
  // resource messages
  messages: {
    en: {
      hello: 'Hello {name}!',
    },
    ja: {
      hello: 'こんにちは、{name}！',
    },
  },
  // something options
  // ...
})

// install middleware with `createApp` option
const app = createApp({ ...middleware })

const router = createRouter()
router.get(
  '/',
  eventHandler((event) => {
    // use `useTranslation` in event handler
    const t = useTranslation(event)
    return t('hello', { name: 'h3' })
  }),
)

app.use(router)
createServer(toNodeListener(app)).listen(3000)

🛠️ Custom locale detection

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

example for detecting locale from url query:

import { defineI18nMiddleware, getQueryLocale } from '@intlify/h3'
import type { H3Event } from 'h3'

const DEFAULT_LOCALE = 'en'

// define custom locale detector
const localeDetector = (event: H3Event): string => {
  try {
    return getQueryLocale(event).toString()
  } catch () {
    return DEFAULT_LOCALE
  }
}

const middleware = defineI18nMiddleware({
  // set your custom locale detector
  locale: localeDetector,
  // something options
  // ...
})

🛠️ Utilites & Helpers

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

Utilities

@intlify/h3 composable utilities accept event (from eventHandler((event) => {})) as their first argument. (Exclud useTranslation) return the Intl.Locale

Translations

useTranslation(event): use translation function

Headers

getHeaderLocale(event): get locale from accept-language header
getHeaderLocales(event): get some locales from accept-language header

Cookies

getCookieLocale(): get locale from cookie
setCookieLocale(): set locale to cookie

Misc

getPathLocale(event): get locale from path
getQueryLocale(event): get locale from query

Helpers

detectLocaleFromAcceptLanguageHeader: detect locale from accept-language header

🙌 Contributing guidelines

If you are interested in contributing to @intlify/h3, 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.

©️ License

MIT