sync-translations

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

sync-translations

同步翻译

Keeps the

docs/ko/

Korean translations synchronized with the English source documents in

docs/en/

保持

docs/ko/

目录下的韩文翻译与

docs/en/

中的英文源文档同步。

When to Use

使用场景

User says "sync docs", "update translations", "sync translations", "번역 동기화", "mirror docs"
After a batch of documentation updates where Korean translations may be missing
Periodically to audit translation completeness across the project

用户输入“sync docs”、“update translations”、“sync translations”、“번역 동기화”或“mirror docs”时
批量更新文档后，可能缺少韩文翻译时
定期检查项目中翻译的完整性时

Directories in Scope

涉及目录

English source	Korean translation
`docs/en/specifications/`	`docs/ko/specifications/`
`docs/en/issue/`	`docs/ko/issue/`
`docs/en/policy/`	`docs/ko/policy/`

docs/reference/

is excluded — user-managed, language-neutral, no translations needed.

英文源文档目录	韩文翻译目录
`docs/en/specifications/`	`docs/ko/specifications/`
`docs/en/issue/`	`docs/ko/issue/`
`docs/en/policy/`	`docs/ko/policy/`

docs/reference/

目录不在范围内——该目录由用户维护，为语言中立内容，无需翻译。

Step-by-Step Instructions

分步操作指南

Step 1: Audit — Find Missing Translations

步骤1：检查——查找缺失的翻译内容

List all English source files in the three directories:

bash

find docs/en/specifications docs/en/issue docs/en/policy \
  -name "*.md" ! -name ".gitkeep" 2>/dev/null | sort

For each file found (e.g.,

docs/en/issue/issue003.md

), check whether the corresponding translation exists (e.g.,

docs/ko/issue/issue003.md

Build a Missing list of files with no Korean translation.

列出三个目录下的所有英文源文件：

bash

find docs/en/specifications docs/en/issue docs/en/policy \
  -name "*.md" ! -name ".gitkeep" 2>/dev/null | sort

对于找到的每个文件（例如

docs/en/issue/issue003.md

），检查对应的韩文翻译文件是否存在（例如

docs/ko/issue/issue003.md

）。

构建一个缺失列表，记录所有没有韩文翻译的文件。

Step 2: Audit — Find Stale Translations

步骤2：检查——查找过时的翻译内容

For files where a Korean translation exists, compare modification times using git:

bash

git log --follow -1 --format="%ai" -- docs/en/issue/issue003.md
git log --follow -1 --format="%ai" -- docs/ko/issue/issue003.md

If the English source has a more recent commit than the Korean translation, add it to a Stale list.

对于已存在韩文翻译的文件，使用git比较修改时间：

bash

git log --follow -1 --format="%ai" -- docs/en/issue/issue003.md
git log --follow -1 --format="%ai" -- docs/ko/issue/issue003.md

如果英文源文档的提交时间晚于韩文翻译文件，则将其加入过时列表。

Step 3: Report and Confirm

步骤3：报告并确认

Tell the user:

Sync audit complete:

Missing translations (<N> files):

docs/en/issue/issue004.md

docs/en/specifications/architecture.md

Potentially stale (<N> files):

docs/en/policy/policy.md (English updated 2025-11-01, Korean updated 2025-10-15)

Shall I create/update all of them?

Wait for confirmation before writing any files.

告知用户：

同步检查完成：

缺失的翻译内容（共<N>个文件）：

docs/en/issue/issue004.md

docs/en/specifications/architecture.md

可能过时的翻译内容（共<N>个文件）：

docs/en/policy/policy.md（英文文档更新于2025-11-01，韩文文档更新于2025-10-15）

是否需要创建/更新所有这些文件？

在写入任何文件前，等待用户确认。

Step 4: Create or Update Translations

步骤4：创建或更新翻译内容

For each file in the Missing or Stale lists:

Read the English source file completely
Translate all prose content into Korean
Write the file to the corresponding
```
docs/ko/
```
path with the same filename

Naming rule: Replace

docs/en/

with

docs/ko/

(same filename):

docs/en/issue/issue003.md

→

docs/ko/issue/issue003.md

docs/en/specifications/requirements.md

→

docs/ko/specifications/requirements.md

docs/en/policy/commit-message-rule.md

→

docs/ko/policy/commit-message-rule.md

对于缺失列表或过时列表中的每个文件：

完整读取英文源文件
将所有散文内容翻译为韩文
将翻译后的内容写入
```
docs/ko/
```
目录下对应的路径，保持文件名不变

命名规则：将

docs/en/

替换为

docs/ko/

（文件名保持一致）：

docs/en/issue/issue003.md

→

docs/ko/issue/issue003.md

docs/en/specifications/requirements.md

→

docs/ko/specifications/requirements.md

docs/en/policy/commit-message-rule.md

→

docs/ko/policy/commit-message-rule.md

Step 5: Report Results

步骤5：报告结果

List every file created or updated with their paths.

列出所有已创建或更新的文件及其路径。

Translation Rules

翻译规则

Translate to Korean:

All prose paragraphs and sentences
Section headings
List item descriptions
Table cell text

Keep in English:

Code blocks (
```
...
```
) — never translate the content inside
File paths (
```
docs/en/issue/issue001.md
```
)
Function names, variable names, class names
Branch names and command-line examples
Technical acronyms: API, URL, HTTP, JSON, Git, etc.
Checkbox markers:
```
- [ ]
```
,
```
- [x]
```

For technical acronyms on first use, optionally add a brief Korean explanation in parentheses, then use the acronym alone thereafter.

Preserve markdown structure exactly:

Same heading levels (
```
#
```
,
```
##
```
,
```
###
```
)
Same list and checkbox formatting
Same bold/italic markers
Same horizontal rules and table structure

需翻译为韩文的内容：

所有散文段落和句子
章节标题
列表项描述
表格单元格文本

需保留英文的内容：

代码块（
```
...
```
）——切勿翻译代码块内的内容
文件路径（如
```
docs/en/issue/issue001.md
```
）
函数名、变量名、类名
分支名和命令行示例
技术缩写词：API、URL、HTTP、JSON、Git等
复选框标记：
```
- [ ]
```
、
```
- [x]
```

对于技术缩写词的首次出现，可选择性地在括号中添加简短的韩文解释，之后直接使用缩写词即可。

严格保留Markdown结构：

相同的标题层级（
```
#
```
、
```
##
```
、
```
###
```
）
相同的列表和复选框格式
相同的粗体/斜体标记
相同的水平线和表格结构