lionad-morotar/document-localize

Document Localize

为 LLM 指令文件中的操作添加本地化语言标注。

快速开始

输入：包含操作指令的文本 输出：添加语言标注后的文本

示例：

# Before
- Write a summary of the changes
- Commit the changes with a message

# After (默认中文标注)
- Write a summary of the changes（要求：使用中文）
- Commit the changes with a message（要求：使用中文）

支持的操作类型

文档写入操作

识别模式：

• Write to、Write、Create、Generate、Update、Output
• 撰写、编写、生成、创建、输出
• 编写文档、生成报告、创建文件

Git 操作

识别模式：

• commit、Commit、git commit
• 提交、提交代码
• PR 标题/描述相关指令

代码注释

识别模式：

• Add comments、Comment the code
• 添加注释、代码注释
• 文档字符串生成

其他输出操作

识别模式：

• Print、Display、Output、Show
• 打印、显示、输出、展示
• 回复/响应类指令

使用方式

1. 直接标注

为给定的指令文本添加语言标注：

参数：
- text: 需要标注的文本
- language: 目标语言（默认：中文）
- format: 标注格式（默认：（要求：使用{language}））

2. 批量处理文件

处理整个 prompt 文件：

参数：
- file_path: 文件路径
- language: 目标语言
- operations: 需要标注的操作类型列表（可选，默认全部）

3. 自定义格式

支持自定义标注格式：

# 默认格式
（要求：使用中文）

# 其他格式示例
[请用中文]
-- 请使用中文输出
> Language: Chinese

标注格式说明

默认格式

（要求：使用{language}）

位置

标注默认紧随操作指令，保持原有句子格式不变。

语言映射

| 语言代码 | 标注文本 | |---------|---------| | zh / chinese | 中文 | | ja / japanese | 日语 | | ko / korean | 韩语 | | en / english | English | | de / german | Deutsch | | fr / french | Français |

配置选项

可在执行时指定：

| 选项 | 说明 | 默认值 | |-----|------|-------| | language | 目标语言 | 中文 | | format | 标注格式 | （要求：使用{language}） | | operations | 操作类型过滤 | 全部 | | skip_existing | 跳过已有标注的行 | true |

注意事项

1. 避免重复标注：检测行尾是否已有语言标注
2. 保持格式：不改变原有文本的缩进和结构
3. 智能识别：仅对输出类操作添加标注，不对读取/查询类操作添加

实践洞察

核心判断原则

是否需要标注 = 该指令是否要求 LLM 生成内容

不要死记硬背关键词，而是理解指令的意图：

| 需要标注（LLM生成内容） | 不需要标注（参考/描述/占位） | |------------------------|---------------------------| | Create DISCOVERY.md | See /templates/xxx.md | | Write to: file.md | Use template: /templates/xxx.md | | Output: Report content | Output: [What artifacts will be created] ← 占位符 | | Produces DISCOVERY.md（在 <output> 标签中） | Produces 2-4 commits ← 描述性 |

上下文决定语义

同一个词在不同上下文中含义不同：

<!-- 在 <output> 标签中 = LLM指令，需要标注 -->
<output>
After completion, create SUMMARY.md
</output>

<!-- 在正文中 = 描述性说明，不需要标注 -->
This workflow produces DISCOVERY.md for Level 2-3.

<!-- 方括号 = 人类占位符，不需要标注 -->
Output: [What artifacts will be created]

常见陷阱

陷阱1：过度标注

❌ See /templates/summary.md（要求：使用中文）  ← 错误！只是引用路径
✅ See /templates/summary.md

陷阱2：遗漏标注

❌ After completion, create SUMMARY.md  ← 错误！LLM需要执行
✅ After completion, create SUMMARY.md（要求：使用中文）

陷阱3：混淆 Output: 的语义

❌ Output: [What artifacts will be created]（要求：使用中文）  ← 错误！这是占位符
✅ Output: [What artifacts will be created]

❌ Output: DISCOVERY.md with recommendation  ← 错误！需要标注
✅ Output: DISCOVERY.md with recommendation（要求：使用中文）

快速检查清单

标注前问自己：

1. 谁在执行？ LLM 执行 → 标注；人类执行/参考 → 不标注
2. 什么内容？ 生成新内容 → 标注；引用已有内容 → 不标注
3. 方括号？ [占位符] → 不标注（留给人类填写）
4. XML标签？ <output>、<step> 中的指令 → 通常需要标注