@langlink/dsh-l10n 0.1.0 → 0.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +10 -1
- package/dist/index.js +2023 -246
- package/dist/index.js.map +4 -4
- package/package.json +2 -2
- package/skills/l10n-assets/SKILL.md +48 -0
- package/skills/l10n-backfill/SKILL.md +20 -0
- package/skills/l10n-cat-formats/SKILL.md +16 -0
- package/skills/l10n-check/SKILL.md +22 -0
- package/skills/l10n-polish/SKILL.md +24 -0
- package/skills/l10n-project/SKILL.md +26 -0
- package/skills/l10n-translate/SKILL.md +22 -0
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@langlink/dsh-l10n",
|
|
3
|
-
"version": "0.1
|
|
3
|
+
"version": "0.2.1",
|
|
4
4
|
"private": false,
|
|
5
5
|
"type": "module",
|
|
6
6
|
"description": "LangLink localization toolsets for DeepSeek Harness (dsh): XLIFF/SDLXLIFF, TM/term matching, QA, translate/polish, OOXML extraction/backfill.",
|
|
@@ -45,7 +45,7 @@
|
|
|
45
45
|
}
|
|
46
46
|
},
|
|
47
47
|
"peerDependencies": {
|
|
48
|
-
"@deepseek-ai/dsh-tools": "0.2.1-rc.2"
|
|
48
|
+
"@deepseek-ai/dsh-tools": ">=0.2.1-rc.2 <0.3.0"
|
|
49
49
|
},
|
|
50
50
|
"dependencies": {
|
|
51
51
|
"htmlparser2": "^12.0.0",
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: l10n-assets
|
|
3
|
+
description: Register, inspect and curate local TM, TBX/CSV terminology and bilingual-table assets in a localization project; explain mapping and enable/disable semantics.
|
|
4
|
+
whenToUse: The user asks to add/remove/enable a TM or termbase, import a bilingual table, fix a mis-parsed asset, or check why an asset is not used.
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# 资产与术语(l10n-assets)
|
|
8
|
+
|
|
9
|
+
资产是对 `<root>/.langlink/manifest.json` 中 `assets[]` 的登记:文件留在原处,manifest 记录类型、语言对、hash、
|
|
10
|
+
条数、是否启用、优先级与导入映射。match/translate/check 工具会自动使用“启用且语言对匹配”的资产,显式 `tm`/
|
|
11
|
+
`glossary` 参数会与项目资产合并,不会被项目覆盖。
|
|
12
|
+
|
|
13
|
+
## 登记
|
|
14
|
+
|
|
15
|
+
1. 先确认文件属于哪类,不要靠猜测:
|
|
16
|
+
- TMX 1.4b → `l10n_asset_add`,`kind: tm`。
|
|
17
|
+
- TBX-Basic/Minis、CSV/TSV 术语表(`source,target[,forbidden]`)→ `kind: tb`。
|
|
18
|
+
- 双语表(CSV/TSV/TXT/XLSX,含 source/target 列)→ `kind: bilingual`。它作为**句对 TM**使用,
|
|
19
|
+
不是可编辑文档;要编辑文件请走 XLIFF/`l10n_extract_doc` 流程。
|
|
20
|
+
2. 自动识别:`.tmx`→tm,`.tbx`→tb,`.xlsx`/`.tsv`→bilingual;`.csv` 若表头含 forbidden/禁用 视为 tb,
|
|
21
|
+
含 id/location 表头视为 bilingual,否则默认 tb。识别不符合预期时显式传 `kind`。
|
|
22
|
+
3. 双语表列义不清时先问用户,再用 `mapping` 重登记或 `l10n_asset_update`:
|
|
23
|
+
`sheet`(XLSX 表名或 1-based 序号)、`headerRow`(1-based;0 表示无表头)、`sourceColumn`/`targetColumn`
|
|
24
|
+
(1-based 序号、Excel 列字母或表头名)、术语表的 `forbiddenColumn`。
|
|
25
|
+
4. 语言对默认取项目语言对;资产语言与项目不同时显式传 `sourceLang`/`targetLang`,否则不会参与匹配。
|
|
26
|
+
5. 重复登记同一文件+类型会被拒绝;先 `l10n_asset_update`(改映射/语言/优先级),或移除后重加。
|
|
27
|
+
资产文件在项目目录外时,`l10n_asset_add` 要显式传 `project`(项目根或 manifest 路径)。
|
|
28
|
+
|
|
29
|
+
## 会话内管理
|
|
30
|
+
|
|
31
|
+
- `l10n_asset_update`:`enabled: false` 暂时不用于任何匹配/QA;`priority` 越大越先使用;
|
|
32
|
+
`rescan: true` 重新读文件、算 hash/条数(文件被替换后使用)。
|
|
33
|
+
- `l10n_asset_remove`:只删 manifest 记录,不删磁盘文件。
|
|
34
|
+
- `update`/`remove` 没有文件路径可锚定项目,需显式传 `project`(项目根或 manifest 路径)或 `input`(项目内文件)。
|
|
35
|
+
- `l10n_project_status`:列出资产 id、类型、条数、`exists`、`hashMatch`;`hashMatch: false` 说明文件已变,
|
|
36
|
+
先 rescan 再继续。
|
|
37
|
+
- 资产替换/覆盖、发布、跨项目复用一律先人工确认;本工作流只写 manifest 与新文件。
|
|
38
|
+
|
|
39
|
+
## 只读共享资产服务
|
|
40
|
+
|
|
41
|
+
`l10n_assets` 读取 `L10N_ASSET_BASE_URL` 指向的只读服务(`/health`、`/glossary`、`/tm`、`/warnings`,
|
|
42
|
+
可选 bearer token)。服务不可用不影响本地流程,报告即可。
|
|
43
|
+
|
|
44
|
+
## 转换
|
|
45
|
+
|
|
46
|
+
`l10n_convert`(`input`、`to: csv|txt|xlsx`、`output`)只写新文件;CSV 固定 `id,source,target,location` 四列,
|
|
47
|
+
XLSX 用 exceljs。转换后行数应与源一致,warnings 逐条说明。TM 合并/去重由项目资产与显式 `--tm`(CLI)自动完成,
|
|
48
|
+
不要手工拼接 TMX。
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: l10n-backfill
|
|
3
|
+
description: Extract DOCX/XLSX/PPTX text to a bilingual table, translate the table, and backfill a new original-format file with map-based validation.
|
|
4
|
+
whenToUse: The user asks to extract, translate, restore, or round-trip Word, Excel, or PowerPoint files while keeping the original format.
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# 原格式抽取与回填(l10n-backfill)
|
|
8
|
+
|
|
9
|
+
流程:extract_doc → 填双语表 → backfill → 校验。只写新文件,原件只读。
|
|
10
|
+
|
|
11
|
+
1. `l10n_extract_doc`:`path`(DOCX/XLSX/PPTX)、`rowsOutput`(CSV 或 XLSX)、`mapOutput`(map.json)。返回 `format`、`rows`、`warnings`。
|
|
12
|
+
- map.json 必须与本次抽取配对使用;不要跨文件复用。
|
|
13
|
+
- 数字、公式、图表、批注、修订等不在抽取范围,`warnings` 要转述给用户。
|
|
14
|
+
2. 填双语表:只填 `target` 列,`id`/`source` 不动;空 target 行回填时会被跳过。
|
|
15
|
+
3. `l10n_backfill`:`original`、`map`、`bilingual`、`output`。返回 `applied/skipped/warnings`;`skipped` 非 0 要说明(通常是空译文、公式单元格、缺失节点)。
|
|
16
|
+
4. 校验:用 `@langlink/l10n-core` 的 `extractOoxml` 重新抽取输出文件,比对译文;再用对应 Office 应用打开/保存/重开(人工或脚本),确认无修复提示。DOCX 表格/页眉、XLSX 多 sheet、PPTX 全部 slide 都要覆盖。
|
|
17
|
+
5. 支持边界见 `docs/ooxml-support-matrix.md`:run 级格式、批注、修订、文本框、图表不保证;遇到这些先说明再决定是否继续。
|
|
18
|
+
6. 输出摘要:原文件/输出路径、applied/skipped、warnings、仍不支持的结构、Office 实机验收结果。
|
|
19
|
+
|
|
20
|
+
禁止:覆盖原文件;把 map.json 当跨任务契约;在回填失败后强行拼接 XML。
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: l10n-cat-formats
|
|
3
|
+
description: Explain and check CAT bilingual formats (SDLXLIFF, MQXLIFF, XLIFF 1.2/2.0/2.1) before write-back, with explicit version and support boundaries.
|
|
4
|
+
whenToUse: The user mentions Trados, SDLXLIFF, memoQ, MQXLIFF, XLIFF 2.x, CAT round-trip, or asks whether a CAT file can be written back safely.
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# CAT 格式与写回边界(l10n-cat-formats)
|
|
8
|
+
|
|
9
|
+
先判断格式/版本,再决定能否写回。未在支持矩阵内的格式不降级猜测。
|
|
10
|
+
|
|
11
|
+
1. `l10n_inspect`:读 `format`、`version`、段数、missingTarget、tagMismatch、warnings。支持:XLIFF 1.2、SDL XLIFF(`sdl:` 命名空间)、XLIFF 2.0/2.1(按 2.0 结构);MQXLIFF 只做结构检测与合成 fixture,真实 MQXLIFF 写回未验收。
|
|
12
|
+
2. SDLXLIFF 写回范围:target 文本 + `sdl:seg@conf/percent/origin/text-match/locked` 状态属性。revisions/track changes/批注、复杂 `sdl:*` 扩展不在范围;未知节点原样保留。
|
|
13
|
+
3. XLIFF 2.x:unit/segment/pc 标签;2.1 增量特性未逐项验证,遇到 2.1 专有结构先报告再决定。
|
|
14
|
+
4. 写回前后必须做结构对比:段数不变、tag mismatch 不变、结构 hash 一致(`l10n_validate`)。任何一项变化立即失败闭锁,保留原件。
|
|
15
|
+
5. 实机验收口径:写回文件必须在目标 CAT 中人工打开/确认/导出抽检后才能对外宣称兼容。仓库记录:2026-10-22 在 Windows + Trados Studio 2019/2022 环境完成字节级/结构级与 Office 验收(见 `docs/acceptance-matrix.md`);GUI 逐项确认仍属人工门。
|
|
16
|
+
6. 不支持时给出替代:生成双语 XLSX/CSV/TMX 供导入,而不是硬改写 CAT 文件。
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: l10n-check
|
|
3
|
+
description: Run deterministic QA plus term/TM checks on local localization files and report evidence-based findings without auto-fixing.
|
|
4
|
+
whenToUse: The user asks to check, QA, review, or audit a local XLIFF/SDLXLIFF file or bilingual table.
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# 质量检查(l10n-check)
|
|
8
|
+
|
|
9
|
+
流程:inspect → terms → check(→ semantic,可选)→ 报告。只报问题,不自动修改。
|
|
10
|
+
|
|
11
|
+
项目模式下(文件祖先目录有 `.langlink/manifest.json`)`l10n_match_terms`/`l10n_check` 会自动使用启用的术语与 TM 资产,
|
|
12
|
+
`glossary`/`tm` 参数可省略;显式路径会与项目资产合并。`targetLocale` 默认取项目 `qa.locale`,白名单默认取项目 `qa.untranslatedCopyWhitelist`。
|
|
13
|
+
|
|
14
|
+
1. `l10n_inspect`:格式/段数/tag mismatch/warnings 基线。`tagMismatch > 0` 时先作为结构问题报告。
|
|
15
|
+
2. `l10n_match_terms`:`path`(项目资产自动生效;也可显式传 `glossary`,CSV/TBX)。报告命中数、forbidden 命中段;permissive case 与 prefix50 语义按工具返回解释,不臆造。
|
|
16
|
+
3. `l10n_check`:确定性 QA。返回 `bySeverity`、`byRule` 与有界 `issues`(每条带 `segmentId`、`evidence`、`origin`)。
|
|
17
|
+
- 先报 coverage(complete/incomplete);不是 complete 时不能总结为“无问题”。
|
|
18
|
+
- `UNTRANSLATED_COPY` 占比高时,结合品牌名/短段/带标签段的已知误报解释,并建议白名单或短段豁免,而不是直接判为质量问题。
|
|
19
|
+
- 报出前用 evidence 复核段号;不要凭规则名推测原因。
|
|
20
|
+
4. 语义 QA(仅当可用):`l10n_semantic_check` 走 dsh LLM 服务,要求严格 JSON 与可定位证据;模型不可用时保留确定性结果并明确标注“语义未检查”,不得报 0 问题。
|
|
21
|
+
5. 报告:JSON/CSV(CLI:`l10n check <file> --format json|csv --out <path>`)。报告含原文/译文,仅本地保存。
|
|
22
|
+
6. 结论分三层:结构/确定性 QA 通过;语义/语言质量未验证;CAT 实机人工验收未做。不要把测试通过写成语言质量 PASS。
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: l10n-polish
|
|
3
|
+
description: Apply reviewed target-language edits to a local XLIFF/SDLXLIFF as a new file, with tag-signature validation.
|
|
4
|
+
whenToUse: The user asks to polish, revise, improve existing translations, or apply a reviewed edit list to a local XLIFF/SDLXLIFF file.
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# 译文润色(l10n-polish)
|
|
8
|
+
|
|
9
|
+
原则:逐条确认后再写;带 inline tag 的段必须给完整 XML 片段;结构不一致直接闭锁。
|
|
10
|
+
|
|
11
|
+
1. `l10n_inspect` + `l10n_check`:先拿到段清单与确定性 QA 结果;`l10n_check` 的 `issues[].segmentId` 是 edit set 的定位依据。
|
|
12
|
+
2. 生成 edit set:只包含用户确认要改的段。格式:
|
|
13
|
+
```json
|
|
14
|
+
{"<segmentId>": {"content": "新译文", "xml": false}}
|
|
15
|
+
{"<segmentId>": {"content": "<g id=\"1\">新</g>译文", "xml": true}}
|
|
16
|
+
```
|
|
17
|
+
无 tag 段用纯文本(`xml` 省略);带 tag 段必须 `xml: true`,保留原段标签签名(数量、类型、顺序、属主不变)。
|
|
18
|
+
3. 向用户逐条展示 before/after,得到确认后再调用 `l10n_polish`:`path`、`edits`(JSON 字符串)、`output`(新文件路径)。
|
|
19
|
+
4. 解析结果:`applied`、`skipped`、`changes[].before/after`。`applied === 0` 且 `warnings` 非空表示整批失败——不要重试写回,报告具体段与原因。
|
|
20
|
+
5. `l10n_validate` 复验:段数、missingTarget、tagMismatch。结构 hash 与修前不一致时停止并说明。
|
|
21
|
+
6. 需要按 MQM 打分时,用 `@langlink/l10n-core` 的 `scoreMqm` 输出 RQS/NPT/CQS,不要自创评分口径。
|
|
22
|
+
7. 结束:列出改了哪些段、diff 摘要、复验结果;提醒 CAT 实机抽检。
|
|
23
|
+
|
|
24
|
+
不做:批量机器改写未确认译文;对带 tag 段做纯文本替换;覆盖输入文件。
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: l10n-project
|
|
3
|
+
description: Create and maintain a local localization project (manifest, language pair, QA defaults, registered assets) before running translate/check workflows.
|
|
4
|
+
whenToUse: The user starts a localization job, opens a project folder, asks where inputs/assets/outputs live, or wants to attach TM/glossary/bilingual assets to the session.
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# 本地化项目准备(l10n-project)
|
|
8
|
+
|
|
9
|
+
目标:在动任何文件之前,先把项目边界、语言对、资产和输出约定确认清楚。项目状态全部保存在
|
|
10
|
+
`<root>/.langlink/manifest.json`,由 `l10n_project_*` 工具维护,不要手工改 JSON 以外的派生文件。
|
|
11
|
+
|
|
12
|
+
1. 确认四项输入:源文件目录、源语言、目标语言、TM/术语表/双语表位置。缺任何一项先问用户,不要猜语言对。
|
|
13
|
+
2. `l10n_project_init`:`root`、`sourceLang`、`targetLang`(必填),可选 `name`、`locale`(QA 语言变体规则用)、
|
|
14
|
+
`threshold`(默认 TM 阈值)、`maxMatches`、`untranslatedCopyWhitelist`。工具会创建 `in/`、`assets/`、`out/`、
|
|
15
|
+
`.langlink/`,已有 manifest 时默认拒绝覆盖;确认用户要改语言对/QA 设置才传 `overwrite: true`,资产不会丢。
|
|
16
|
+
3. 资产登记(TMX/术语表/双语表)用 `l10n_asset_add`,登记即解析并写 manifest;详见 `l10n-assets` skill。
|
|
17
|
+
- TMX → `kind: tm`;TBX/CSV 术语表 → `kind: tb`;双语 CSV/TSV/TXT/XLSX → `kind: bilingual`
|
|
18
|
+
(source→target 句对,作为 TM 使用;不是可编辑文档)。
|
|
19
|
+
- 双语表列不标准时传 `mapping`(`sheet`、`headerRow`、`sourceColumn`、`targetColumn`),先向用户确认列义。
|
|
20
|
+
4. 用 `l10n_project_status` 复核:语言对、启用的资产、文件是否存在、可选 `verify: true` 重算 hash。
|
|
21
|
+
`exists: false` 或 `hashMatch: false` 时先停下列出问题,不要继续翻译。
|
|
22
|
+
5. 用 `l10n_inspect` 逐个检查 `in/` 下的 XLIFF/SDLXLIFF:格式、版本、段数、missing target、tag mismatch、结构 hash。
|
|
23
|
+
格式不支持或编码非 UTF-8 时停止并说明,不做降级转换。
|
|
24
|
+
6. 对 DOCX/XLSX/PPTX 原始文件,先用 `l10n_extract_doc` 生成双语表与 `map.json`,再进入翻译流程;不要直接改原文件。
|
|
25
|
+
7. 结束输出清单:语言对、文件数/段数、启用资产与 id、输出目录、下一步(translate/check/backfill)。
|
|
26
|
+
项目内文件路径只用于本地,客户材料不入库、不上传。
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: l10n-translate
|
|
3
|
+
description: Pre-translate a local XLIFF/SDLXLIFF file from a TMX into a new file, then validate and check it.
|
|
4
|
+
whenToUse: The user asks to translate, pre-translate, fill empty targets, or apply a TM to a local XLIFF/SDLXLIFF file.
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# TM 预翻译(l10n-translate)
|
|
8
|
+
|
|
9
|
+
流程:inspect → match_tm → translate → validate → check。所有写操作输出新文件,永不覆盖原件。
|
|
10
|
+
|
|
11
|
+
项目模式下(`in/` 的祖先目录有 `.langlink/manifest.json`)工具会自动使用启用的 TM/双语表资产:
|
|
12
|
+
`l10n_match_tm`/`l10n_translate` 的 `tm` 参数可以省略;显式 `tm` 会与项目资产合并。阈值默认取项目 `qa.threshold`。
|
|
13
|
+
|
|
14
|
+
1. `l10n_inspect`:确认格式、语言对、段数、missingTarget、tagMismatch。任一项与预期不符先停下说明。
|
|
15
|
+
2. `l10n_match_tm`:`path`(项目内文件可省略 `tm`,自动用项目资产;也可显式传 TMX 路径)看命中率分布;先向用户报告 100/101/99/75–98 各档段数。阈值与语言对以工具返回为准。
|
|
16
|
+
3. `l10n_translate`:`path`、`output`(必须不同于输入);`tm` 可省略(用项目资产),`threshold` 默认取项目或 75。SDLXLIFF 需要写状态时加 `setSdlConf`(例如 `Translated`),工具只改 `sdl:seg@conf/percent` 等状态属性。
|
|
17
|
+
4. 解读结果:`applied` 为填充段数,`skipped` 为已有译文/带 tag 段;带 inline tag 的段不会被自动填充,这是预期行为——不要手工拼接标签,转 polish 流程处理。`warnings` 非空要逐条说明。
|
|
18
|
+
5. `l10n_validate`:确认段数不变、tag mismatch 为 0。失败即闭锁:保留原文件,报告错误,不重试覆盖。
|
|
19
|
+
6. `l10n_check`:确定性 QA。`UNTRANSLATED_COPY` 等疑似误报要结合白名单/短段策略向用户说明,不得直接宣称语言质量结论。
|
|
20
|
+
7. 输出摘要:输入/输出路径、sha256、applied/skipped、QA 计数、仍需人工处理的段(带 tag 段)。
|
|
21
|
+
|
|
22
|
+
限制:非 UTF-8、XLIFF 之外的格式、带标签整段重排不在本流程内;Trados 打开确认属于人工验收门,写回后提醒用户在 CAT 中抽检。
|