README.md

@intlify/nitro

Internationalization for Nitro

🌟 Features

✅️️  Internationalization utils: 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

✅  Nitro plugin: Optimized for Nitro v3 plugin system

💿 Installation

# Using npm
npm install @intlify/nitro

# Using yarn
yarn add @intlify/nitro

# Using pnpm
pnpm add @intlify/nitro

# Using bun
bun add @intlify/nitro

🚀 Usage

Plugin setup

Create a Nitro plugin to enable internationalization:

// server/plugins/i18n.ts
import { intlify, detectLocaleFromAcceptLanguageHeader } from '@intlify/nitro'

export default intlify({
  // detect locale with `accept-language` header
  locale: detectLocaleFromAcceptLanguageHeader,
  // resource messages
  messages: {
    en: {
      hello: 'Hello {name}!'
    },
    ja: {
      hello: 'こんにちは、{name}！'
    }
  }
})

Translation

Use useTranslation in your route handlers:

// server/routes/index.ts
import { defineHandler } from 'nitro'
import { useTranslation } from '@intlify/nitro'

export default defineHandler(async event => {
  const t = await useTranslation(event)
  return t('hello', { name: 'Nitro' })
})

Detect locale with utils

Detect locale from accept-language header:

// server/routes/locale.ts
import { defineHandler } from 'nitro'
import { getHeaderLocale } from '@intlify/nitro'

export default defineHandler(event => {
  const locale = getHeaderLocale(event.req)
  return locale.toString()
})

🛠️ Custom locale detection

You can detect locale with your custom logic from the current HTTP event.

Example for detecting locale from URL query:

// server/plugins/i18n.ts
import { intlify, getQueryLocale } from '@intlify/nitro'

import type { HTTPEvent } from 'nitro/h3'

const localeDetector = (event: HTTPEvent): string => {
  return getQueryLocale(event.req).toString()
}

export default intlify({
  locale: localeDetector,
  messages: {
    en: { hello: 'Hello {name}!' },
    ja: { hello: 'こんにちは、{name}！' }
  }
})

You can also get the detected locale in route handlers with getDetectorLocale:

// server/routes/index.ts
import { defineHandler } from 'nitro'
import { getDetectorLocale } from '@intlify/nitro'

export default defineHandler(async event => {
  const locale = await getDetectorLocale(event)
  return `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.

// server/plugins/i18n.ts
import { intlify, getCookieLocale } from '@intlify/nitro'

import type { HTTPEvent } from 'nitro/h3'
import type { DefineLocaleMessage, CoreContext } from '@intlify/nitro'

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')
}

const localeDetector = async (
  event: HTTPEvent,
  intlify: CoreContext<string, DefineLocaleMessage>
): Promise<string> => {
  const locale = getCookieLocale(event.req).toString()

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

  return locale
}

export default intlify({
  locale: localeDetector
})

🖌️ 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.

Type parameter for useTranslation

You can set the type parameter to the resource schema for key completion of the translation function:

// server/routes/index.ts
import { defineHandler } from 'nitro'
import { useTranslation } from '@intlify/nitro'

export default defineHandler(async event => {
  type ResourceSchema = {
    hello: string
  }
  const t = await useTranslation<ResourceSchema>(event)
  return t('hello', { name: 'Nitro' })
})

Global resource schema with declare module '@intlify/nitro'

You can do resource key completion with the translation function using the typescript declare module:

import en from './locales/en.ts'

type ResourceSchema = typeof en

declare module '@intlify/nitro' {
  export interface DefineLocaleMessage extends ResourceSchema {}
}

The advantage of this way is that it is not necessary to specify the resource schema in the useTranslation type parameter.

🛠️ Utilities & Helpers

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

See the API References

🙌 Contributing guidelines

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