# @happyvertical/smrt-languages 中文文档

规范地址：https://npmcn.com/package/%40happyvertical/smrt-languages/

版本：0\.62\.1
npm 元数据更新时间：2026-11-17T07:53:42.583Z
中文译文更新时间：2026-11-17T09:42:24.652Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40happyvertical/smrt-languages
原文对照：https://npmcn.com/package/%40happyvertical/smrt-languages/?lang=original
项目主页：https://github.com/happyvertical/smrt#readme
源码仓库：https://github.com/happyvertical/smrt

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：237 kB，44 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：9 个
- 首次发布：2026-06-23T01:18:39.177Z
- 最新版本发布：2026-11-17T07:53:42.350Z
- 近 30 天下载量：20253（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：365（近 12 个月 365 个）

## 中文简介

SMRT 的代码第一语言字符串,带有配置 + 租户覆盖和 AI 自动翻译

## 安装

```sh
npm install @happyvertical/smrt-languages
```

也可以使用：`pnpm add @happyvertical/smrt-languages`、`yarn add @happyvertical/smrt-languages`、`bun add @happyvertical/smrt-languages`

## README

# @happyvertical/smrt-languages (英语)

密码第一语言字符串,包含配置 + 租户 覆盖和 AI 驱动 s-m-r-t应用程序的自动翻译.

`smrt-languages` 镜像结构 `@happyvertical/smrt-prompts`数字 : 软件包宣布他们的用户界面字符串为代码、应用程序和租户 通过文件配置或DB行覆盖它们,解析器将每个 层在运行时间。 v1 增加了一个自动AI翻译步骤,由 `@happyvertical/smrt-jobs`: 第一次在语言区请求字符串 解析器返回 a 即刻回落语言并排出背景翻译。 后续 请求点击新的应用程序级别行.

这一一揽子方案是更广泛的一揽子方案史诗的第二阶段先决条件—— 问题 [1200号](https://github.com/happyvertical/smrt/issues/1200)。 。 。 .

## 为什么

-   今天,包件硬码标签像 `'Member'`, (中文(简体) ), `'Article'`,或 `'Payment due by {dueDate}'`租户无法使用 `'Subscriber'` 改为 `'Member'` {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}没有.. 租户以自己的语言经营.
-   `smrt-prompts` 已经证明了 AI 提示的分层覆盖模式 . `smrt-languages` 对显示字符串应用相同的模式,加一个 AI 驱动的漏洞填充器, 关闭缺失本地地址的循环 屏蔽第一个请求.

## 快开始

```typescript
import {
  defineLanguageString,
  resolveLanguageString,
} from '@happyvertical/smrt-languages';

// Define defaults at startup, typically in your package's
// __smrt-register__.ts so the registry is populated before resolves run.
defineLanguageString({
  key: 'users.role.member',
  locale: 'en',
  template: 'Member',
});

defineLanguageString({
  key: 'commerce.invoice.dueText',
  locale: 'en',
  template: 'Payment due by {dueDate}',
});

// Resolve at runtime. Tenant context is read from AsyncLocalStorage by default.
const text = await resolveLanguageString('users.role.member', {
  db,
  locale: 'es',
  vars: { dueDate: '2026-06-01' },
  // strict: false → return the English fallback and enqueue an AI translation.
  // strict: true  → throw when no resolution exists.
});
```

## 分辨率层

递升优先级 :

1.  **代码默认** —— 说 `defineLanguageString({ key, locale, template })`
2.  **文件/配置覆盖** —— 说 `getPackageConfig('languages').overrides[key][locale]`
3.  **App级存储覆盖** —— 说 `LanguageOverride` 与 `tenantId = null`
4.  **租户级存储覆盖** —— 说 `LanguageOverride` 与 `tenantId = <current>`
5.  **运行时间覆盖** —— 说 `resolveLanguageString(key, { overrides: { template: '...' } })`

请求时 `(key, locale)` 不存在任何地方, 解决者走 倒车链 `fr-CA` → `fr` + 已注册的默认- 地点( x)`en`——和 返回第一个点击。 当命中地点不同时 请求中,为原目标排入了AI翻译任务.

## 存储

管理者居住在 `_smrt_language_overrides`数字 :

| 栏 | 页:1 |
| --- | --- |
| `key` | 命名空格字符串密钥( N)`users.role.member`(中文(简体) ) |
| `locale` | BCP-47标签(`en`, (中文(简体) ), `fr-CA`(中文(简体) ) |
| `tenantId` | `null` 租户 租户 |
| `template` | 覆盖字符串 `{var}` 占位符 |
| `auto_generated` | `true` 由AI翻译工作制作 |
| `source_hash` | 翻译时源模板的sha256 |
| `ai_model` | 模型标识符; `null` 用于人类编辑的行 |
| `reviewed_at` 编号 : `reviewed_by` | 设定管理员批准自动行时 |

Source-hash gating 表示只有在源实际发生时才进行再翻译 变化——自动生成的行 `source_hash` 火柴就剩一个人了. 由人类编辑的行`auto_generated: false`已经 **永远** 覆写.

## AI 自动翻译

当a `(key, targetLocale)` 缺少解析器 `LanguageTranslationTask` 任务进入 `languages` 队列带有确定性 身份证明 `smrt-languages.translate:<key>:<targetLocale>` - 如此同时 错过了一个工作。 这份工作:

1.  将租户的现有语言读取为词汇表(在 (无租户背景).
2.  电话 `@happyvertical/ai` 低温翻译提示 本身通过 `smrt-prompts` 下级 `smrt-languages.translation` ——操作员可以调和措辞,而不 调出.
3.  验证反应(非空出,无明显的标记外泄).
4.  提高应用程序级别 `LanguageOverride` 与 `auto_generated: true`, (中文(简体) ), `source_hash`,以及 `ai_model`。 。 。 .
5.  将解析器缓存无效 `(key, targetLocale, *)`。 。 。 .

### 成本和滥用控制

-   `smrt-features` 旗帜 `smrt-languages.auto_translate` ——全球/每名租户 杀死开关.
-   `translationBudgetPerTenantPerDay` ——每个租户每日最高限额.
-   `supportedLocales` ——可选许可列表;其他本地地址的工作被删除 在任何AI呼叫之前.
-   源- hash gating 防止在没有任何变化时重新翻译 .

### 行政审查

```bash
smrt languages translate --locales=es,fr,de   # batch eager pre-population
smrt languages review --locale=es              # list unreviewed auto rows
smrt languages approve <id>                    # mark reviewed
smrt languages edit <id> --template "..."      # edit + flip auto_generated to false
```

CLI表面由从S-m-r-t自动生成 `LanguageOverride` 模型和 帮助 `src/cli.ts`。 。 。 .

## 配置

`smrt.config.{js,ts,json}`数字 :

```js
export default {
  packages: {
    languages: {
      defaultLocale: 'en',
      supportedLocales: ['en', 'es', 'fr', 'de', 'ja'],
      translationBudgetPerTenantPerDay: 200,
      overrides: {
        'users.role.member': {
          es: 'Miembro',
        },
      },
    },
  },
};
```

## 子路径导出

软件包根( R)`@happyvertical/smrt-languages`)只披露已读路径: `defineLanguageString`, (中文(简体) ), `resolveLanguageString`, (中文(简体) ), `LanguageOverride`,缓存 帮助者、词汇帮助者和共享类型/用途。 正在装入根 已经 **没有** 牵出 `@happyvertical/ai`, smrt-jobs, smrt-tetatures, 或 , 或 , smrt-features, 或 冲入了消费者的包里.

翻译工作者们住在一个子路径上:

```typescript
// Background workers + tests that enqueue or run translation jobs.
import {
  enqueueTranslationJob,
  LanguageTranslationTask,
  AUTO_TRANSLATE_FEATURE_KEY,
  TRANSLATION_PROMPT_KEY,
} from '@happyvertical/smrt-languages/jobs';

// Admin / batch CLI helpers.
import {
  translateMissing,
  approveAutoTranslation,
  editLanguageOverride,
  listUnreviewedAutoTranslations,
} from '@happyvertical/smrt-languages/cli';
```

解析器本身 动态导入 工人模块在软缺失,所以 电话 `resolveLanguageString` 仍然会触发一个不包含 来电者必须预先输入 `/jobs` 子路径.

## 范围外(v1)

多元化、 ICU Message Format、 Svelte 组件 i18n、 RTL 版式、 地方 谈判 HTTP 中间软件、 XLIFF/ PO TM 工具集成, 质量更丰富 aI翻译的分数都是v1.1+关注. v1 为平原 `{var}` 替换和上面的解析链,所以通过仍是一个 跨消费品包的机械重构.

## 常见问题

### @happyvertical/smrt-languages 是什么？

SMRT 的代码第一语言字符串,带有配置 \+ 租户覆盖和 AI 自动翻译

### 如何安装 @happyvertical/smrt-languages？

在项目目录运行 npm install @happyvertical/smrt-languages，或使用 pnpm add / yarn add / bun add。

### @happyvertical/smrt-languages 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @happyvertical/smrt-languages 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @happyvertical/smrt-languages 可以商用吗？

@happyvertical/smrt-languages 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @happyvertical/smrt-languages 的下载量有多少？

根据 npm 官方下载统计，@happyvertical/smrt-languages 在 2026/10/17 – 2026/11/15 这 30 天内被下载 20,253 次，日均约 675 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @happyvertical/smrt-languages 还在维护吗？

最新版本 0\.62\.1 发布于 2026/11/17（今天）；至今共发布 365 个版本，其中过去 12 个月发布了 365 个；首次发布于 2026/06/23。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

