@virsical/i18n-sdk

这是一个轻量级的 I18n 客户端 SDK，专注于解决前端项目中的多语言文案加载、缓存与格式化问题。

为什么需要它？

因为把所有语言的 JSON 全部打包进主 JS 是愚蠢的。这个 SDK 让你可以按需（Namespace/Locale）从 CDN 远程加载语言包，并自动利用 localStorage 进行缓存，避免重复的网络请求。

核心特性：

• 按需加载：支持 Namespace 分割，别一次性加载整个世界的文案。
• 多级缓存：LocalStorage -> 内存缓存。再次打开页面时零请求。
• 健壮兜底：Remote 失败 -> 本地 Fallback -> Host Intl -> 直接返回 Key。确保页面永远不会因为翻译服务挂了而空白。
• 标准格式化：基于 intl-messageformat，支持标准的 ICU 语法（变量替换、复数等）。
• 遗留支持：zh() 方法支持直接使用中文原文作为 Key 进行反查（虽然我不推荐这么写，但它就在那）。

安装

npm install @virsical/i18n-sdk

快速上手

1. 初始化与配置

在你的应用启动处（Entry file）创建一个实例并配置远程地址。

import { createI18nClient } from '@virsical/i18n-sdk';

// 创建实例（闭包隔离，无全局污染）
const i18n = createI18nClient({ isDev: process.env.NODE_ENV === 'development' });

// 配置远程加载参数
i18n.configureRemote({
  baseUrl: 'https://cdn.example.com/i18n', // 你的 CDN 地址
  version: '1.0.0',                        // 版本号，用于缓存失效控制
  namespaces: ['common', 'home'],          // 默认加载的命名空间
  requestTimeout: 5000,                    // 超时控制
});

// 设置本地兜底文案（可选，但在关键路径上是好习惯）
i18n.setFallbackMessages('zh-CN', {
  'app.title': '我的应用',
});

2. 加载语言包

通常在路由切换或应用启动时调用。

// 并发加载 'zh-CN' 下的默认 namespaces
await i18n.loadLocale('zh-CN');

// 或者指定加载特定的 namespaces
await i18n.loadLocale('en-US', ['settings', 'payment']);

3. 格式化文案

// 1. 标准用法：使用 ID
const text = i18n.formatMessage({ id: 'welcome_msg', defaultMessage: 'Welcome' }, { name: 'Linus' });
// Output: "Welcome, Linus" (假设语言包里配置了 "welcome_msg": "Welcome, {name}")

// 2. 简单用法
i18n.formatMessage('app.submit'); 

4. 监听更新（可选）

如果你的应用需要响应语言包的动态加载（比如异步加载完成后刷新 UI）。

i18n.onLocaleData((locale, messages) => {
  console.log(`Loaded ${locale}`, messages);
  // 这里触发你的 UI 框架更新，比如 React 的 setState
});

高级功能

中文 Key 反查 (zh)

这是一个为了兼容遗留代码或特定开发习惯存在的功能。它允许你直接在代码里写中文，SDK 会去查一个 zh-map.json 把它映射回 ID。

// 实际上会去查 '你好' 对应的 ID，然后进行格式化
i18n.zh('你好', { name: 'World' });

警告：这需要依赖远程存在 zh-map.json 映射表。如果映射表加载失败，它会退化到使用本地兜底或直接返回文本。

开发辅助

在开发环境下（isDev: true），你可以连接一个 Socket 服务，用于自动上报代码里出现但尚未翻译的中文 Key。

// 连接到本地的翻译采集服务
i18n.devIntlSocket('http://localhost:8999');

API 参考

详见 src/index.d.ts，那是最好的文档。代码不会撒谎。

Generated by Gemini CLI.