fastify-intl

描述

@kne/fastify-intl 是一个专为 Fastify 项目设计的国际化解决方案插件。它基于业界成熟的 @formatjs/intl 库构建，提供了强大而灵活的多语言支持能力，帮助开发者轻松实现应用的国际化和本地化。

安装

npm i --save @kne/fastify-intl

概述

@kne/fastify-intl 是一个专为 Fastify 项目设计的国际化解决方案插件。它基于业界成熟的 @formatjs/intl 库构建，提供了强大而灵活的多语言支持能力，帮助开发者轻松实现应用的国际化和本地化。

该插件采用现代化的设计理念，支持按需加载语言包，完美集成 Fastify 生态系统。通过命名空间管理机制，不同模块可以独立维护自己的翻译文件，避免代码耦合。插件内置多种语言检测策略，包括查询参数、Cookie 和请求头，确保为用户提供最合适的语言体验。

@kne/fastify-intl 提供了简洁直观的 API，在请求对象上直接暴露 locale、intl 和 t 等属性，让国际化操作变得轻而易举。它还支持动态加载远程语言包，配合智能缓存机制，既保证了性能又提供了足够的扩展性。无论是小型项目还是大型企业级应用，这款插件都能满足各种国际化场景的需求。

基础使用

1. 注册插件

const fastify = require('fastify')();
const fastifyIntl = require('@kne/fastify-intl');

await fastify.register(fastifyIntl);

2. 配置默认翻译消息

await fastify.register(fastifyIntl, {
  defaultMessages: {
    'en-US': {
      hello: 'Hello World',
      welcome: 'Welcome, {name}!'
    },
    'zh-CN': {
      hello: '你好世界',
      welcome: '欢迎, {name}!'
    }
  }
});

3. 在路由中使用

fastify.get('/hello', async (request, reply) => {
  return {
    message: request.t('hello')
  };
});

fastify.get('/welcome', async (request, reply) => {
  return {
    message: request.t('welcome', { name: 'John' })
  };
});

动态加载翻译消息

await fastify.register(fastifyIntl, {
  requestMessages: async ({ locale, name }) => {
    const response = await fetch(`https://api.example.com/messages/${locale}/${name}`);
    return response.json();
  }
});

与命名空间集成

await fastify.register(require('@kne/fastify-namespace'));
await fastify.register(fastifyIntl);

fastify.namespace.user = {
  locale: {
    'en-US': {
      profile: {
        title: 'User Profile',
        settings: 'Settings'
      }
    }
  }
};

fastify.namespace.order = {
  locale: {
    'en-US': {
      title: 'My Orders'
    }
  }
};

自定义语言检测顺序

await fastify.register(fastifyIntl, {
  defaultLocale: 'en-US',
  acceptLanguage: 'en-US,zh-CN,ja-JP'
});

语言检测优先级：

1. query.language / query.lang
2. cookies.x-user-locale / cookies.x-client-language
3. headers.x-user-locale / headers.x-client-language
4. headers.accept-language
5. defaultLocale

控制缓存大小

插件使用 LRU 缓存来优化性能，支持两个级别的缓存：

await fastify.register(fastifyIntl, {
  cacheSize: 200
});

• intlCache: 缓存 Intl 实例，避免重复创建（LRU 策略，默认最多 100 个）
• localeCache: 缓存请求级别的 locale 检测结果（Map 结构，无限制）

多模块支持

await fastify.register(fastifyIntl, {
  moduleName: 'app'
});

// 在请求中切换模块
fastify.get('/admin', async (request, reply) => {
  request.moduleName = 'admin';
  request.intl = await fastify.intl.createIntl(request.locale, 'admin');
  return {
    message: request.t('dashboard')
  };
});

Q: 如何处理缺失的翻译？

插件会自动回退到 defaultLocale，确保始终有可用的翻译。

Q: 如何支持嵌套的翻译消息？

消息对象支持嵌套结构：

{
  'en-US': {
    user: {
      profile: {
        title: 'User Profile',
        name: 'Full Name'
      }
    }
  }
}

使用点号访问嵌套消息：

request.t('user.profile.title')

Q: 如何处理复数形式？

使用 ICU MessageFormat 语法：

{
  'en-US': {
    itemCount: 'You have {count, plural, =0{no items} one{1 item} other{# items}}'
  }
}

request.t('itemCount', { count: 5 }) // "You have 5 items"

Q: 如何在生产环境禁用动态加载？

await fastify.register(fastifyIntl, {
  requestMessages: process.env.NODE_ENV === 'development' ? loadRemoteMessages : null
});

示例

示例代码

API

配置选项

属性名	说明	类型	默认值
name	插件装饰器名称	string	'intl'
acceptLanguage	接受的语言列表，* 表示接受所有语言	string	'*'
defaultLocale	默认语言环境	string	'en-US'
moduleName	默认模块名称	string	'global'
defaultMessages	默认翻译消息对象	object	{}
requestMessages	动态加载翻译消息的函数，支持按 locale 和 name 缓存	function|null	null
cacheSize	Intl 缓存大小	number	100

requestMessages 说明

requestMessages 函数用于动态加载远程翻译消息。该函数会根据 locale 和 name 参数进行缓存，避免重复加载。

函数签名：

requestMessages(params: {
  locale: string;
  name: string;
}): Promise<Record<string, string>> | Record<string, string>

缓存机制：

• 当首次调用 createIntl(locale, name) 时，如果 message[locale][name] 不存在，会触发 requestMessages
• 加载的消息会被缓存，后续相同 locale 和 name 的调用会直接使用缓存
• 缓存的 key 格式为 ${locale}:${name}

示例：

await fastify.register(fastifyIntl, {
  requestMessages: async ({ locale, name }) => {
    const response = await fetch(`https://api.example.com/messages/${locale}/${name}`);
    return response.json();
  }
});

// 第一次调用会触发远程请求
const intl1 = await fastify.intl.createIntl('en-US', 'user');

// 第二次调用使用缓存，不会触发远程请求
const intl2 = await fastify.intl.createIntl('en-US', 'user');

// 不同的 locale 或 name 会触发新的请求
const intl3 = await fastify.intl.createIntl('zh-CN', 'user');

请求属性

属性名	说明	类型
request.locale	当前请求的语言环境	string
request.intl	国际化格式化对象	IntlShape
request.moduleName	当前模块名称	string

方法

创建一个国际化格式化实例。

参数	说明	类型
locale	语言环境代码	string
name	模块名称，默认为配置的 moduleName	string

返回值：IntlShape 对象

getRequestLocale(request)

从请求中获取语言环境。

参数	说明	类型
request	Fastify 请求对象	Request

返回值：语言环境字符串

检测顺序：query.language / query.lang → cookies.x-user-locale / cookies.x-client-language → headers.x-user-locale / headers.x-client-language → headers.accept-language → defaultLocale

request.t(id, values)

翻译消息的快捷方法。

参数	说明	类型
id	消息 ID	string
values	格式化参数	object

返回值：翻译后的字符串