Typesafe-i18n：在 TypeScript 中实现完全类型安全的国际化

\n\n

在现代 Web 开发中，国际化 (i18n) 不仅仅是文本翻译，而是一整套本地化管理体系。Typesafe-i18n 是一个专为 TypeScript 设计的库，它将国际化提升到了新的高度，在从编写翻译到代码使用的所有阶段都提供了完整的类型安全性。

\n\n

为什么需要这个库？传统的 i18n 解决方案（例如 i18next）通常使用动态字符串，这容易导致错误：键名拼写错误、参数不正确或缺少翻译。Typesafe-i18n 从根本上解决了这个问题：如果你编写了 LL.WELCOME({name: "Alexey"})，TypeScript 会检查 WELCOME 键是否存在，是否接受 name 参数以及该参数的类型。本地化错误将变为编译时错误，而不是运行时错误。

\n\n

该库非常适合需要严格类型化的项目：React/Vue/Angular 应用程序、Node.js 服务器、组件库。它支持复数形式、插值、嵌套键、异步加载以及基于你的翻译文件生成类型。在本文中，我们将探讨使用 Typesafe-i18n 的所有方面：从安装到高级技术。

\n\n

安装

\n\n

通过 npm（或 yarn/pnpm）进行安装：

\n\n

npm install typesafe-i18n\n

\n\n

生成类型和翻译文件需要额外的包：

\n\n

npm install --save-dev typesafe-i18n-cli\n

\n\n

安装后，初始化项目：

\n\n

npx typesafe-i18n --init\n

\n\n

此命令将创建基本的文件夹结构和配置文件。

\n\n

快速入门：最小工作示例

\n\n

让我们创建一个简单的应用程序，用不同语言向用户问好。

\n\n

步骤 1：创建翻译文件

\n\n

创建文件 src/i18n/en/index.ts：

\n\n

import type { Translation } from '../i18n-types'\n\nconst en: Translation = {\n   HI: 'Hello {name}!',\n   GOODBYE: 'Goodbye, {name}!'\n}\n\nexport default en\n

\n\n

步骤 2：创建俄语翻译文件

\n\n

创建文件 src/i18n/ru/index.ts：

\n\n

import type { Translation } from '../i18n-types'\n\nconst ru: Translation = {\n   HI: 'Привет, {name}!',\n   GOODBYE: 'До свидания, {name}!'\n}\n\nexport default ru\n

\n\n

步骤 3：运行类型生成

\n\n

npx typesafe-i18n\n

\n\n

步骤 4：在代码中使用

\n\n

import { i18n } from './i18n/i18n-util'\nimport { loadLocale } from './i18n/i18n-util.sync'\nimport { L } from './i18n/i18n-util'\n\n// 加载语言包\nloadLocale('en')\nloadLocale('ru')\n\n// 创建英文实例\nconst LL_en = i18n('en')\nconsole.log(LL_en.HI({ name: 'Alex' })) // 输出：Hello Alex!\n\n// 切换到俄语\nconst LL_ru = i18n('ru')\nconsole.log(LL_ru.HI({ name: 'Алексей' })) // 输出：Привет, Алексей!\n

\n\n

请注意：如果你尝试在不提供 name 参数的情况下调用 LL_en.HI()，TypeScript 将抛出编译错误。如果你在键名中拼写错误（例如 LL_en.Hello），同样会报错。

\n\n