国际化

国际化（Internationalization，简称 i18n） 是 Kotori 提供的多语言支持机制。通过国际化系统，你可以轻松地为你的模块提供多语言支持，使其能够适应不同语言环境的用户需求。本节绝大部分内容来自 @kotori-bot/i18n 库并重新导出。

注册翻译数据

有两种方式可以注册翻译数据：直接传入对象或使用文件配置。

对象方式

最简单的方式是直接传入一个包含翻译数据的对象：

文件方式

更推荐的方式是将翻译数据存储在单独的文件中，通常是 JSON 格式：

import type { Context } from 'kotori-bot'
import { join } from 'node:path'

export function main(ctx: Context) {
  // 直接注册
  ctx.i18n.use(join(__dirname, '../locales'))
}

// 或使用语法糖（建议）:
export const lang = [__dirname, '../locales']

翻译文件应按语言代码命名并放在 locales 目录下：

• locales/en_US.json

{
  "hello": "Hello, {0}!",
  "count": "There are {0} apples",
  "welcome": "Welcome to Kotori"
}

• locales/zh_CN.json

{
  "hello": "你好，{0}！",
  "count": "这里有 {0} 个苹果",
  "welcome": "欢迎使用 Kotori"
}

使用翻译

注册翻译数据后，可以通过多种方式使用它：

ctx.i18n.locale('message', 'en_US') // "Hello, {0}!"
ctx.i18n.locale('message', 'zh_CN') // "你好，{0}！"

// 使用模板字符串函数语法糖
ctx.i18n.t`message` // "Hello, {0}!"

// 获取/设置当前语言
ctx.i18n.get() // 'en_US'
ctx.i18n.set('zh_CN')
ctx.i18n.get() // 'zh_CN'

格式化工具

此外，Kotori 的国际化系统基于 ECMAScript 的 Intl API，提供了一系列强大的格式化工具：

// 格式化日期
ctx.i18n.date(new Date(), 'full') // "Friday, January 24, 2025"
ctx.i18n.date(new Date(), 'long', 'zh_CN') // "2025年1月24日"

// 格式化时间
ctx.i18n.time(new Date(), 'medium') // "7:14:49 AM"
ctx.i18n.time(new Date(), 'short', 'zh_CN') // "上午7:14"

// 格式化时段
ctx.i18n.period(new Date()) // "in the morning"
ctx.i18n.period(new Date(), undefined, 'zh_CN') // "上午"

// 格式化数字
ctx.i18n.number(1234567.89) // "1,234,567.89"
ctx.i18n.number(1234567.89, { style: 'currency', currency: 'CNY' }, 'zh_CN') // "¥1,234,567.89"

// 格式化列表
ctx.i18n.list(['apple', 'banana', 'orange']) // "apple, banana, and orange"
ctx.i18n.list(['苹果', '香蕉', '橘子'], undefined, 'zh_CN') // "苹果、香蕉和橘子"

// 相对时间格式化
ctx.i18n.rtime(-1, 'day') // "yesterday"
ctx.i18n.rtime(3, 'month', undefined, 'zh_CN') // "3个月后"

// 文本分词
ctx.i18n.segmenter('Hello, World!') // { value: "Hello", done: false }
ctx.i18n.segmenter('你好，世界！', undefined, 'zh_CN') // { value: "你好", done: false }

所有格式化方法都支持指定语言参数，如果未指定则使用当前设置的语言。

格式化工厂

formatFactory() 由 @kotori-bot/tools 库提供并重新导出。其接收一个 i18n 实例，它同时结合了字符串格式化与国际化的功能，Session 上的 session.format() 实则就是对 formatFactory() 的调用结果。

const format = formatFactory(ctx.i18n)
// 不带有 i18n 直接输出
format('hello, {0}!', ['world'])
// 带有 i18n 自动转换（根据当前上下文中的语言设置）
ctx.i18n.set('zh_CN')
format('message', ['world']) // "你好，world！"

继承机制

你可以创建一个继承自当前实例的新国际化实例：

const child = ctx.i18n.extends('zh_CN')
child.locale('hello') // "你好，{0}！"
ctx.i18n.get() // 'en_US' (父实例的语言设置不受影响)

继承的国际化实例：

• 拥有独立的语言设置
• 可以访问父实例的所有翻译数据
• 可以注册自己的翻译数据而不影响父实例

这个特性在开发子插件时特别有用，允许子插件拥有独立的语言设置。

支持的语言

Kotori 默认支持以下语言：

• en_US: 英语
• zh_CN: 中文
• zh_TW: 台文
• ja_JP: 日语

你可以通过配置或代码设置模块支持的语言列表。当用户切换到不支持的语言时，系统会自动使用默认语言（通常是英语）。

TIP

建议始终提供英语（en_US）翻译作为默认的回退选项。