# @ccssmnn/intl 中文文档 规范地址：https://npmcn.com/package/%40ccssmnn/intl/ 版本：0\.1\.1 npm 元数据更新时间：2025-09-27T08:14:00.054Z 中文译文更新时间：2026-11-09T09:29:21.145Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40ccssmnn/intl 原文对照：https://npmcn.com/package/%40ccssmnn/intl/?lang=original 项目主页：https://github.com/ccssmnn/intl 源码仓库：https://github.com/ccssmnn/intl ## 关键信息（来自 npm 元数据） - 包体积（解压后）：150 kB，25 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - 运行依赖：1 个 - peer 依赖：react ^17\.0\.0 \|\| ^18\.0\.0 \|\| ^19\.0\.0 - 首次发布：2025-09-27T07:35:49.581Z - 最新版本发布：2025-09-27T08:13:59.885Z - 近 30 天下载量：3074（2026-10-10 至 2026-11-08，npm 官方下载统计） - 已发布版本数：2（近 12 个月 0 个） ## 中文简介 类型安全 Unicode Message Format 2.0 工具,带有运行时间格式化和回放绑定. ## 安装 ```sh npm install @ccssmnn/intl ``` 也可以使用：`pnpm add @ccssmnn/intl`、`yarn add @ccssmnn/intl`、`bun add @ccssmnn/intl` ## README # @ ccssmnn/ intl (英语) 一个不需要取出/编码的国际性效用,是超级型号安全的,与编码剂有很大作用. 基本上只是输入和反应在官方 Unicode Message Format 2.0 上建的公用设备. ## 特征 - QQ 没有代码生成/ 信件提取: 作者信件并立即使用. - {}通过 Unicode Message Format 2 语法 [`messageformat`](https://github.com/messageformat/messageformat) (唯一的依赖). - \* 用于供应商、钩子和带有标记渲染的组件的响应公用事业. - 由于熟悉的语法和友好类型错误,与编码代理无缝对等——消息. - QQ在服务器上同样有效,例如通知和电子邮件. ### 支持的信件格式语法 **运行时间支持 :** 图书馆代表向 `messageformat@4` 用于完整消息格式2.0支持. **类型级别支持 :** TypeScript 类型目前验证规格的焦点子集 : **参数:** - `{$param}` - 字符串参数 - `{$param :number}` - 数量参数 - `{$param :datetime}` - 日期/时间参数 - `{$param :date}` - 日期参数 - `{$param :time}` - 时间参数 **马克:** - `{#tag}content{/tag}` - 简单的标记跨度(无属性) - 嵌入标记标记 - React 中的类型安全组件映射 **选取/拼接:** - `.input {$var} .match $var` 模式 - `one`编号 :`*` 复数规则 - 自定义选择分支 **QQ 没有类型验证( 但运行时工作) :** - 参数选项如 `style=currency` - 标记标签属性 - 复杂函数调用 - 其他信件格式 2. 0 特性 类型系统注重最常见的i18n模式,同时允许您在需要时使用高级特性. ## 安装 ```bash pnpm add @ccssmnn/intl ``` **同伴依赖关系 :** - React 17+(仅在使用 React 集成时需要) **所需经费:** - 有ES2020支持的节点.js 16+或现代浏览器 ## 快速启动 ```ts import { messages, createIntl } from "@ccssmnn/intl" // 1. Define your messages const copy = messages({ greeting: "Hello {$name}!", count: "You have {$num :number} items", }) // 2. Create translator const t = createIntl(copy, "en") // 3. Use it t("greeting", { name: "World" }) // "Hello World!" t("count", { num: 42 }) // "You have 42 items" ``` ## 使用量 ### 信件格式 2.0 实例 类型验证的常见模式 : ```ts const messages = messages({ // Basic interpolation greeting: "Hello {$name}!", // Typed parameters (type-validated) price: "Price: {$amount :number}", date: "Today is {$today :datetime}", time: "Meeting at {$when :time}", // Pluralization items: ".input {$count :number} .match $count one {{one item}} * {{{$count} items}}", // Selection status: ".input {$role} .match $role admin {{Welcome admin}} user {{Hello user}} * {{Hi there}}", // Markup tags welcome: "Welcome {#bold}{$name}{/bold}! Click {#link}here{/link} to continue", // Complex nested structure cart: `.input {$count :number} {$hasDiscount} .match $count $hasDiscount 0 true {{Your cart is empty, but you have a discount!}} 0 * {{Your cart is empty}} one true {{You have one item with discount applied}} one * {{You have one item}} * true {{You have {$count} items with discount applied}} * * {{You have {$count} items}}`, }) ``` ### 核心 API ```ts import { messages, createIntl, translate } from "@ccssmnn/intl" // annotates `base` with the messages types let base = messages({ greeting: "Hello {$name}!", count: "You have {$num :number} items", }) // guarantees on a type level that `german` has the same message signature as `base` let german = translate(base, { greeting: "Hallo {$name}!", count: "Du hast {$num :number} Elemente", }) // create typesafe message consumption utility! let t = createIntl(german, "de") t("greeting", { name: "Carl" }) // → "Hallo Carl!" ``` 所有帮助者都被打出强烈的字. 譬如说, `t` 没有电话就拒绝 `name` 参数,以及 `translate` 强制要求翻译保留与底稿相同的参数/标记. ### 处理错误 库为错误消息提供优雅的错误处理: ```ts const problematic = messages({ valid: "Hello {$name}!", broken: "Invalid syntax {{{", // Malformed message }) const t = createIntl(problematic, "en") t("valid", { name: "Carl" }) // "Hello Carl!" t("broken") // "❌: broken" (fallback with key name) // Console shows table with error details ``` 当信件格式汇编失败时, 库 : 1. 日志详细错误信息到控制台 2. 创建显示有问题的密钥的倒置消息 3. 继续执行而不丢弃 ### 反应整合 ```tsx import { createIntlForReact, messages } from "@ccssmnn/intl" const copy = messages({ signIn: "Hey {$name}! {#link}Sign in here{/link}", }) const { IntlProvider, useIntl, T } = createIntlForReact(copy, "en") function Toolbar() { const t = useIntl() return

{t("signIn", { name: "Carl" })}

} function Entry() { return ( {children} }} /> ) } ``` 钩子暴露了相同的类型 `t` 函数为核心 API,所以 TypeScript 将在 React 组件中标记缺失的参数/标记右侧。 这个 `` 组件用途 `formatToParts` 让您为标记标记提供 React 组件. ## API 参考 ### 核心职能 - **`messages(obj)`** - 从对象文字创建已键入的信件目录 - **`createIntl(messages, locale)`** - 创建用于提供字符串的翻译功能 - **`createIntlToParts(messages, locale)`** - 创建手动渲染的论坛(用于构建UI框架适配器) - **`translate(base, translation)`** - 创建保护结构的型号安全翻译 - **`merge(...catalogs)`** - 合并多个信息目录(防止关键冲突) - **`check(base, ...parts)`** - 核查翻译覆盖面并合并部分 ### 反应集成 - **`createIntlForReact(messages, locale)`** - 回归 `{ IntlProvider, useIntl, T, useLocale }` - **`IntlProvider`** - 消息和语言的背景提供者 - **`useIntl()`** - Hook 返回翻译功能 `t(key, params?, components?)` - **`T`** - 发送带有标记的信息的组件: `` - **`useLocale()`** - Hook 返回当前区域字符串 ## 使用指南 ### 组织工作流程 - 每个特性组织信件目录(例如:. `~/intl/messages.todos.ts`(e) 保持相关信息在同一地点,使其更容易工作. - 将全球目录集成到 `~/intl/messages.ts` 通过将特性切片与 `merge(...)` ,并通过 `check(...)`。 。 。 . - 一次在 `shared/intl/setup.ts` 使用 `createIntlForReact(messagesEn, "en")`;导出结果 `IntlProvider`, (中文(简体) ), `useIntl`, (中文(简体) ), `T`,以及 `useLocale`。 。 。 . - 重新使用框架不可知性帮助( E)`createIntl`, (中文(简体) ), `createIntlToParts`)用于服务器任务,如本地化的推取通知. **这种办法的好处:** - 更小、重点更突出的信息模块更容易导航和修改 - 相关消息要贴近其使用特性 - 更好地使用能够理解和修改特定特征背景的编码代理 - 当多个特性同时添加信件时, 防止冲突合并 ### 典型布局 ``` shared/ intl/ setup.ts # configured React exports messages.ts # merges base + locale slices messages.todos.ts # per-feature catalogue (base + translate) messages.*.ts # additional slices server/ notifications/ send-push.ts # imports createIntl() for localized payloads ``` ### 特性信件切片 ```ts // ~/intl/messages.todos.ts import { messages, translate } from "@ccssmnn/intl" export { baseTodoMessages, deTodoMessages } let baseTodoMessages = messages({ "todos.header": "Tasks for {$name}", "todos.remaining": "You have {#strong}{$count :number}{/strong} remaining", }) let deTodoMessages = translate(baseTodoMessages, { "todos.header": "Aufgaben für {$name}", "todos.remaining": "Du hast noch {#strong}{$count :number}{/strong} übrig", }) ``` ### 汇总全球目录 ```ts // ~/intl/messages.ts import { merge, check } from "@ccssmnn/intl" import { baseTodoMessages, deTodoMessages } from "./messages.todos" // import other feature slices... export { messagesEn, messagesDe } let messagesEn = merge( baseTodoMessages /* other base slices */ ) let messagesDe = check( messagesEn, deTodoMessages /* other locale slices */ ) ``` ### 反应消耗 ```tsx // ~/intl/setup.ts import { createIntlForReact } from "@ccssmnn/intl/react" import { messagesEn } from "./messages" // create the provider with the default messages and locale export const { IntlProvider, useIntl, T, useLocale } = createIntlForReact( messagesEn, "en" ) // ui/components/todo-header.tsx import { useIntl, T } from "~/intl/setup" export function TodoHeader({ username, remaining, }: { username: string remaining: number }) { const t = useIntl() return (

{t("todos.header", { name: username })}

{children} }, }} />
) } ``` ### 语言切换 ```tsx // app/root.tsx import { IntlProvider } from "~/intl/setup" import { messagesEn, messagesDe } from "~/intl/messages" const catalogs = { en: messagesEn, de: messagesDe, } export function App({ locale }: { locale: keyof typeof catalogs }) { return ( {/* ... */} ) } ``` ### 服务器侧 ```ts // server/notifications/send-push.ts import { createIntl } from "@ccssmnn/intl" import { messagesEn, messagesDe } from "~/intl/messages" const catalogs = { en: messagesEn, de: messagesDe, } export function buildTodoNotification( locale: keyof typeof catalogs, taskTitle: string, dueAt: Date ) { const t = createIntl(catalogs[locale], locale) return { title: t("notifications.todo.title", { title: taskTitle }), body: t("notifications.todo.body", { dueAt }), } } ``` ### 工作流程提示 - 首先为底片添加新信件密钥; 编译失败, 直至翻译匹配, 保持本地同步 . - 使用 `` 只有在需要标记时; `useIntl()` 足够简单的弦. - 运行 `pnpm test` (启用了类型检查)在修改目录后立即捕捉ICU或标记错配. - 提取到共享库时,导出相同的原始文献(`messages`, (中文(简体) ), `merge`, (中文(简体) ), `translate`, (中文(简体) ), `check`, (中文(简体) ), `createIntl`, (中文(简体) ), `createIntlForReact`),所以客户端和服务器消费者都保留了ergonomics. ## 发展 - `pnpm install` - `pnpm test` - 运行Vitest套房(Core and React). - `pnpm build` - 将无害环境管理+d.ts产出放入 `dist/`。 。 。 . ## 许可证 [麻省理工学院](https://npmcn.com/package/%40ccssmnn/intl/LICENSE) ## 常见问题 ### @ccssmnn/intl 是什么？ 类型安全 Unicode Message Format 2\.0 工具,带有运行时间格式化和回放绑定\. ### 如何安装 @ccssmnn/intl？ 在项目目录运行 npm install @ccssmnn/intl，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^17\.0\.0 \|\| ^18\.0\.0 \|\| ^19\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @ccssmnn/intl 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @ccssmnn/intl 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @ccssmnn/intl 可以商用吗？ @ccssmnn/intl 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @ccssmnn/intl 的下载量有多少？ 根据 npm 官方下载统计，@ccssmnn/intl 在 2026/10/10 – 2026/11/08 这 30 天内被下载 3,074 次，日均约 102 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @ccssmnn/intl 还在维护吗？ 最新版本 0\.1\.1 发布于 2025/09/27（1\.1 年前）；至今共发布 2 个版本，其中过去 12 个月发布了 0 个；首次发布于 2025/09/27。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。