# @diglot/core 中文文档

规范地址：https://npmcn.com/package/%40diglot/core/

版本：0\.2\.2
npm 元数据更新时间：2026-11-08T11:46:30.428Z
中文译文更新时间：2026-11-12T09:28:42.881Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：95.9 kB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：1 个
- 首次发布：2026-11-02T18:45:34.272Z
- 最新版本发布：2026-11-08T11:46:30.149Z
- 近 30 天下载量：4097（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 10 个）

## 中文简介

分会场一级,人类第一译作减记文件

## 安装

```sh
npm install @diglot/core
```

也可以使用：`pnpm add @diglot/core`、`yarn add @diglot/core`、`bun add @diglot/core`

## README

# @ diglot/ 核心

解析器中性核心 [挖掘机](https://npmcn.com/package/README.md):分段模式、占位符形式和散列、翻译验证、应用助手、分段和句子diff、翻译记录、政策和词汇类型。 它没有标分分解依赖; 适配器, 例如 [`@diglot/comark`](https://npmcn.com/package/%40diglot/comark) 财务报告和审定财务报表 [`@diglot/mdast`](https://npmcn.com/package/%40diglot/mdast) 为其制作片段。 它导入了无节点内置,因此在浏览器和边缘运行时间以及节点运行.

```bash
pnpm add @diglot/core
```

## 部分

适配器将每个可转换单元转换为 `SegmentDraft` 在小 IR 中包含内含内容( R)`text`, (中文(简体) ), `strong` 编号 : `emphasis` 编号 : `delete`, (中文(简体) ), `link` 它的开口和收尾 `atomic` 横跨其减值源. `buildSegment` 把它变成一个 `Segment`数字 :

```ts
import { buildSegment } from '@diglot/core'

const segment = buildSegment({
  kind: 'paragraph',
  content: [
    { type: 'text', value: 'Nuxt is powered by ' },
    { type: 'link', open: '[', close: '](https://nitro.build)', children: [{ type: 'text', value: 'Nitro' }] },
    { type: 'text', value: '.' },
  ],
  context: { headingTrail: [], containers: [] },
  position: { startLine: 1, endLine: 1, precision: 'node' },
}, { file: 'intro.md', index: 0 })

segment.skeleton // 'Nuxt is powered by {0}Nitro{/0}.'
segment.hash // sha256 of the skeleton, truncated to 16 hex characters
```

`{n}` 代表原子跨度(内置代码、图像、组件、HTML、绑定、硬断)和 `{n}...{/n}` 覆盖链接的文本。 白空间被倒塌了,并逃脱了文本中被标记的下浮点,所以骨架在再包装和被保护的跨度编辑之间是稳定的. 平面片段(道具,前事,标签,代码注释)除了有相同骨架的被标记下片段的散列外,所以每个翻译都根据一套规则进行验证. 一项政策可以在模糊的短弦的散列上加上上下文盐.

`prepareSegment` 使用相同的参数并返回 `{ segment, nodes }` (或 `undefined` 没有内容的单位,例如 `buildSegment`),在其中 `nodes[id]` 是占位符后面的链接或原子节点 `id`。适配器使用它从当前源节点重建一个翻译单元.

## 验证

```ts
import { validate } from '@diglot/core'

validate('Nuxt est propulsé par {0}Nitro{/0}.', segment).ok // true
validate('Nuxt [Vite](https://example.com)', segment).errors // link syntax, missing placeholder
```

译文可包含文本,强调标记和其出处的占位符. 重复的代码占位符是一种警告. 平面片段(道具,前题,标签,代码注释)为单行并可能不添加标记;代码注释可能不包含注释终止符.

`validate(translation, segment, { style, maxLength })` 并检查长度:带有本地语言 `style.lengthRatio`,译出25个或25个以上字符的译名 `lengthRatio` (在占位器外的特征) 在乐队之外得到一个 `length` 警告,并且比 `maxLength` 获得一个 `too-long` 错误. `maxTranslationLength(source)` 是极限 `editRecord` 默认应用:4倍源外加100个字符,最多为8000个.

`resolveTranslation(segment, translations)` 通过散列查看翻译, 验证并重新输入当前源的保护跨度 。 翻译是骨架或 `TranslationRecord`s,在由散列键键入的地图中,或由查询函数返回. `parseSkeleton` 将一个经验证的骨架转换成树,用于将翻译应用到AST的适配器. `pseudoTranslate` 生成任何骨架的有效伪地翻译.

## 应用事件

适应者 `apply` 接受函数 `onSegment`,以 `ApplySegmentEvent` 按萃取顺序排列的每个段:

-   `segment`:源部分,及其 `hash` 财务报告和审定财务报表 `words`
-   `outcome`数字 : `translated`, (中文(简体) ), `missing` (无翻译), `rejected` (一) 复议员拒绝翻译或不予审定; `errors` 或 `skipped` (无所译而无所译也. 未翻译的部分保留其源文本
-   `record`: 记录,如果有,则返回检索
-   `status`:读者所看到的,从 `recordStatus`。作为裸骨架提供的翻译没有地位
-   `target`: 对于区块级区段,一个其 `setAttribute(name, value)` 设置输出节点的属性; `null` 用于前题、道具、图像选择、代码标签和代码注释

`wordsByStatus(events)` 每页覆盖按状况分列的分字数. `createSegmentEvent` 为适配器构建事件.

## 变动

```ts
import { diffSegments, sentenceDiff } from '@diglot/core'

const { unchanged, added, removed, modified } = diffSegments(before, after)
for (const { before, after, similarity, ambiguous } of modified)
  console.log(sentenceDiff(before.skeleton, after.skeleton).changed)
```

`diffSegments` 比较一个文件的片段:相等散列不变,其余去除和添加的片段由骨架相似性对接(阈值) `0.5` )查找每个被修改段的前身.

## 记录

`TranslationRecord` 将一个源片段翻译成一个地块: `hash`, (中文(简体) ), `source`, (中文(简体) ), `text`, (中文(简体) ), `origin` (单位:千美元)`mt`, (中文(简体) ), `tm`, (中文(简体) ), `human`, (中文(简体) ), `review` (单位:千美元)`none`, (中文(简体) ), `edited`, (中文(简体) ), `verified`, (中文(简体) ), `rejected`, (中文(简体) ), `derived` (单位:千美元)`fresh`, (中文(简体) ), `carry`, (中文(简体) ), `update`),可选择 `prev`, (中文(简体) ), `salt`, (中文(简体) ), `mt` (模型、即时版本和未经编辑的候选人), `by`, (中文(简体) ), `verifiedBy`, (中文(简体) ), `rejectedBy` 财务报告和审定财务报表 `updatedAt`。 。 。 .

编审通过设置拒绝翻译 `review: 'rejected'` 财务报告和审定财务报表 `rejectedBy: { by, at }` 在记录中。 文本保留给审查者和度量衡,但读者看到源文本,而机器翻译则留下了记录. 编辑( E)`review: 'edited'`,没有 `rejectedBy`)或用新源散列来取而代之.

-   `parseRecord(value)` 检查形状并扔出 `RecordError`。 。 。 . `verifiedBy` 何时需要 `review` 实值 `verified`· ; `rejectedBy` 何时需要 `review` 实值 `rejected`,并只允许
-   `createRecord({ segment, text, origin })` 填入身份字段
-   `recordStatus(record, segment)` 返回读取器所看到的 : `untranslated`, (中文(简体) ), `machine`, (中文(简体) ), `pending-review`, (中文(简体) ), `edited`, (中文(简体) ), `verified` 或者说 `rejected` (一被否决的记录,或无法验证的文本 `segment`) (中文(简体) ). 由前身携带或更新的记录是: `pending-review` 直到有人编辑或证实它,无论它是什么 `origin`
-   `editRatio(record)` 衡量一名审查员更换多少机器候选人

## 审查

`editRecord`, (中文(简体) ), `verifyRecord` 财务报告和审定财务报表 `rejectRecord` 使用当前记录(或 `undefined`返回时 `{ ok: true, record, warnings }` 与下一个记录,或 `{ ok: false, code, message, errors }`数字 :

```ts
import { editRecord, verifyRecord } from '@diglot/core'

const result = verifyRecord(record, { segment, by: 'danielroe', expected: textTheReviewerSaw })
if (!result.ok)
  throw new Error(result.message) // result.code: 'stale', 'rejected', ...
```

-   `editRecord(record, { segment, text, by, style, maxLength })` 写作人类编辑( i)`origin: 'human'`, (中文(简体) ), `review: 'edited'`),保留 `mt`, (中文(简体) ), `prev` 财务报告和审定财务报表 `derived` 并放弃审查邮票。 它拒绝一个无法验证或超过 `maxLength` (单位:千美元)`invalid`· ; `maxTranslationLength` 默认来源, `false` (无)和(无)文本不变`unchanged`除非记录被拒绝。 记录 `hash` 部分不是被拒绝的,因为 `mismatch`
-   `verifyRecord(record, { segment, by })` 套装 `review: 'verified'` 财务报告和审定财务报表 `verifiedBy`它拒绝缺失的记录(`no-record`),被否决者(`rejected`: 编辑取而代之的拒绝, 文本无法校验 `segment` (单位:千美元)`invalid`)和经核实的记录(`unchanged`(中文(简体) )
-   `rejectRecord(record, { by })` 套装 `review: 'rejected'` 财务报告和审定财务报表 `rejectedBy` 减少 `verifiedBy`它拒绝丢失或拒绝的记录

每一个都要 `at` (违约至今)和 `expected`,审查者看到的文字:其文字差异的记录被拒绝作为 `stale`,以及 `null` 希望没有记录.

## 配置

`snapshotPolicy(policy)` 返回策略的可序列部分 `policyFingerprint`,用于 `.diglot/policy.json`。 。 。 . `restorePolicy(snapshot, { salt, codeLabel })` 重建运行时间的策略 `extract` 财务报告和审定财务报表 `apply`; 函数无法序列化, 因此快照列出自定义的 `custom`,并恢复投出,除非它们被传入,结果具有相同的指纹。 指纹按其结果对一组固定输入进行函数比较.

`defineConfig` 类型 a `diglot.config.ts`· ; `defaultPolicy` 列出默认情况下提取的道具、布局容器和前题路径,以及 `starlightPolicy` 列出星光站点( 诸如 `navigation.title` 匹配字词 `navigation.title` 键或嵌入 `navigation: { title }`,而翻译则写回读取的密钥; `Glossary` 描述每个本地 `glossary.yml` 财务报告和审定财务报表 `LocaleStyle` a 每个地方 `style.yml`· ; `MtConfig` 拥有机器翻译设置; `LocaleState` 描述每个本地 `locale.yml` 有机器翻译开关 和背后的检讨指标.

## 常见问题

### @diglot/core 是什么？

分会场一级,人类第一译作减记文件

### 如何安装 @diglot/core？

在项目目录运行 npm install @diglot/core，或使用 pnpm add / yarn add / bun add。

### @diglot/core 支持 TypeScript 吗？

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

### @diglot/core 支持 ESM 还是 CommonJS？

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

### @diglot/core 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @diglot/core 可以商用吗？

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

### @diglot/core 的下载量有多少？

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

### @diglot/core 还在维护吗？

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