npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@intlify/h3-edge

v0.5.0-28804712.8d87f7a

Published

Internationalization middleware & utilities for h3

Downloads

36

Readme

@intlify/h3

npm version npm downloads CI

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(async (event) => {
    // use `useTranslation` in event handler
    const t = await 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'

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

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

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 { defineI18nMiddleware, getQueryLocale } from '@intlify/h3'
import type { DefineLocaleMessage } from '@intlify/h3'
import type { H3Event } from 'h3'

const loader = (path: string) => import(path).then((m) => m.default || m)
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 (event: H3Event, i18n: CoreContext<string, DefineLocaleMessage>): Promise<string> => {
  // detect locale
  const locale = getCookieLocale(event).toString()

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

  return locale
}

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

🧩 Type-safe resources

[!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/h3'
import { createApp } from 'h3'
import en from './locales/en.ts'

// define resource schema, as 'en' is master resource schema
type ResourceSchema = typeof en

const middleware = defineI18nMiddleware<[ResourceSchema], 'en' | 'ja'>({
  messages: {
    en: { hello: 'Hello, {name}' },
  },
  // something options
  // ...
})

const app = createApp({ ...middleware })
// 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:13

If 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.

Type-safe resources

🖌️ Resource keys completion

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

Key Completion

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:

const router = createRouter()
router.get(
  '/',
  eventHandler(async (event) => {
    type ResourceSchema = {
      hello: string
    }
    // set resource schema as type parameter
    const t = await useTranslation<ResourceSchema>(event)
    // you can completion when you type `t('`
    return t('hello', { name: 'h3' })
  }),
)

global resource schema with declare module '@intlify/h3'

[!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/h3' {
  // extend `DefineLocaleMessage` with `ResourceSchema`
  export interface DefineLocaleMessage extends ResourceSchema {}
}

const router = createRouter()
router.get(
  '/',
  eventHandler(async (event) => {
    const t = await useTranslation(event)
    // you can completion when you type `t('`
    return t('hello', { name: 'h3' })
  }),
)

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

🛠️ 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. (Exclude useTranslation) return the Intl.Locale

Translations

  • useTranslation(event): use translation function, asynchronous

Headers

  • getHeaderLocale(event, options): get locale from accept-language header
  • getHeaderLocales(event, options): get some locales from accept-language header
  • tryHeaderLocale(event, options): try to get locale from accept-language header
  • tryHeaderLocales(event, options): try to get some locales from accept-language header

Cookies

  • getCookieLocale(event, options): get locale from cookie
  • tryCookieLocale(event, options): try to get locale from cookie
  • setCookieLocale(event, options): set locale to cookie

Misc

  • getPathLocale(event, options): get locale from path
  • tryPathLocale(event, options): try to get locale from path
  • getQueryLocale(event, options): get locale from query
  • tryQueryLocale(event, options): try to get locale from query

Helpers

  • detectLocaleFromAcceptLanguageHeader(event): 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