SwimmerI18nKit

轻量、分层的共享语言能力：语言选择、独立 ICU 消息目录、Intl 格式、 React/browser 接入和开发期检查。换语言只更新表达；资源按账号、作品或任务身份管理。

当前源码版本为 0.2.0。正式 npm 发布需要 Owner 单独批准，发布状态以官方 registry 为准；不要在发布前把生产项目改成未发布版本或临时 tarball。兼容变化见 升级指南。

最短正确用法

实例拥有目录和配置的快照。在模块级创建，别在 React render 内重复创建：

import { createI18n } from "@pieai/swimmer-i18n-kit";

const source = { greeting: "Hello {name}" } as const;
export const i18n = createI18n({
  sourceLocale: "en",
  source,
  catalogs: { "zh-CN": { greeting: "你好，{name}" } },
});

i18n.translator("zh-CN").t("greeting", { name: "Ada" });
i18n.explain("zh-Hans"); // 请求与实际选择的解释，不保存在 translator 上
i18n.catalogStatus("zh-CN").selectable; // 可用于语言菜单

消息键自动获得类型检查。精确参数类型使用 CLI 从源目录生成的 MessageContracts， 传入 createI18n<typeof source, MessageContracts>；生成文件不手写。

React 的绑定也放在模块级：

import { createI18nContext } from "@pieai/swimmer-i18n-kit/react";
import { i18n } from "./i18n.js";

export const { Provider, useI18n } = createI18nContext(i18n);
// 宿主负责 requestedLocale 的来源。不要给整个工作区加 key={requestedLocale}。
// <Provider locale={requestedLocale}><Workspace /></Provider>

同一实例、实际语言相同，translator 及其方法保持身份稳定。替换目录时创建新实例， 通过绑定 Provider 的 instance 属性或普通 I18nProvider 的 i18n 属性传入； 旧 translator 不会被悄悄改义。不要重新创建绑定上下文或依赖 useMemo 保证任务身份。

三个不同的问题

completeness() 仍只回答“键是否齐全”；catalogStatus() 另外报告语法/参数有效性 与可选择性；CLI 的 requiredLocales 声明本次检查必须具备哪些语言。 三者都不能证明译文自然或业务语义正确。52 项语言登记是计划，不是52份已完成翻译。

边界与入口

| 入口 | 责任 | | --- | --- | | 根入口 . | 无 DOM、无 React 的快照、匹配、ICU 与 Intl | | /browser | 宿主主动调用的系统语言、偏好适配、整页 lang/dir | | /react | 可选 React peer 的 Provider/hook；不管理编辑器、任务或账号 | | /pseudo | 开发期长文本/RTL 伪语言，不改用户原文 | | /cli | Node 检查、类型生成、扁平 JSON 交换、启发式源码扫描 | | /package.json | 包版本、导出和许可元数据 |

界面语言、作品原文语言、模型输出语言、区域格式、时区彼此独立。 金额值与币种也是原始业务事实；切英文不会把 CNY 变成 USD。 Kit 不管保存、撤销、编辑器生命周期、路由、存储策略、模型调用或费用。 默认不联网、不上报、不自动翻译；t() 返回纯文本，不提供可信 HTML。

开发与验证

pnpm verify
pnpm docs:check
pnpm measure:bundles
pnpm exec publint
pnpm exec attw --pack . --entrypoints . ./browser ./react ./pseudo ./package.json --profile esm-only

打包消费者真实安装 tarball，覆盖无 React/DOM 的 Node、生成类型、CLI、生产浏览器、 React 18/19 的动态切换与 SSR。每次使用独立目录和端口，证据保存在本机 artifacts/； 这不是六个真实产品已通过验收的证明。

合同分别保存在 API、CLI、 语言匹配、包体与性能； 维护者从仓库的 docs/reference/execution/current-work.md 进入当前任务；执行记录和历史 按需读取，不随 npm 包分发。

许可为 PieAI Limited Use License 1.0，本轮不改变许可或仓库公开性。