Agent-almanac translate-content

install

source · Clone the upstream repo

git clone https://github.com/pjt222/agent-almanac

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/pjt222/agent-almanac "$T" && mkdir -p ~/.claude/skills && cp -r "$T/i18n/zh-CN/skills/translate-content" ~/.claude/skills/pjt222-agent-almanac-translate-content-13d4c8 && rm -rf "$T"

manifest: i18n/zh-CN/skills/translate-content/SKILL.md

source content

Translate Content

Translate English source content into a target locale, preserving technical accuracy and structural integrity.

适用场景

Localizing a skill, agent, team, or guide into a supported language
Updating a translation that has become stale after source changes
Batch-translating multiple items within a domain or content type
Creating initial translations for a new locale

输入

必需: Content type —
```
skills
```
,
```
agents
```
,
```
teams
```
, or
```
guides
```
必需: Item ID — the name/identifier of the content (e.g.,
```
create-r-package
```
)
必需: Target locale — IETF BCP 47 code (e.g.,
```
de
```
,
```
zh-CN
```
,
```
ja
```
,
```
es
```
)
可选: Batch list — multiple IDs to translate in sequence

步骤

第 1 步：Read the English source

1.1. Determine the source file path:

Skills:
```
skills/<id>/SKILL.md
```
Agents:
```
agents/<id>.md
```
Teams:
```
teams/<id>.md
```
Guides:
```
guides/<id>.md
```

1.2. Read the entire source file to understand context, structure, and content.

1.3. Identify sections that must stay in English:

All code blocks (fenced with triple backticks)
Inline code (backtick-wrapped)
YAML frontmatter field names and technical values (
```
name
```
,
```
tools
```
,
```
model
```
,
```
priority
```
,
```
skills
```
list entries,
```
allowed-tools
```
,
```
tags
```
,
```
domain
```
,
```
language
```
)
File paths, URLs, command examples

<!-- CONFIG:START -->

<!-- CONFIG:END -->

blocks in teams

预期结果： Full understanding of source content with clear mental separation of translatable prose vs preserved technical content.

失败处理： If source file is not found, verify the ID exists in the registry. Check for typos in the content type or ID.

第 2 步：Scaffold the translation file

2.1. Run the scaffolding script:

npm run translate:scaffold -- <content-type> <id> <locale>

2.2. If the file already exists, read it to check whether it needs updating (stale) or is already current.

2.3. Verify the scaffolded file has translation frontmatter fields:

```
locale
```
— matches target locale
```
source_locale
```
—
```
en
```
```
source_commit
```
— current git short hash
```
translator
```
— attribution string
```
translation_date
```
— today's date

预期结果： Scaffolded file at

i18n/<locale>/<content-type>/<id>/SKILL.md

(or

.md

for other types) with correct frontmatter.

失败处理： If the scaffold script fails, create the directory manually with

mkdir -p

and copy the source file. Add frontmatter fields manually.

第 3 步：Translate the description

3.1. Translate the

description

field in the YAML frontmatter into the target locale.

3.2. For skills, the description is inside the top-level frontmatter. For agents/teams/guides, it is also in the top-level frontmatter.

3.3. Keep the translation concise — match the length and style of the original.

预期结果： Description field contains an idiomatic translation that accurately conveys the original meaning.

失败处理： If the description is ambiguous, keep it closer to literal translation rather than risk misinterpretation.

第 4 步：Translate prose sections

4.1. Translate all prose content section by section:

Section headings (e.g., "## When to Use" → "## Wann verwenden" in German)
Paragraph text
List item text (but not list item code/paths)
Table cell text (but not table cell code/values)

4.2. Preserve these elements exactly as-is:

Code blocks (``` fenced and indented)
Inline code (
```
backtick-wrapped
```
)
File paths and URLs
Skill/agent/team IDs in cross-references
YAML/JSON configuration examples
Command-line examples
```
**Expected:**
```
and
```
**On failure:**
```
markers (translate the label, keep the structure)

4.3. For skills, translate the standardized section names:

"When to Use" → locale equivalent
"Inputs" → locale equivalent
"Procedure" → locale equivalent
"Validation" → locale equivalent
"Common Pitfalls" → locale equivalent
"Related Skills" → locale equivalent

4.4. For agents, translate:

Purpose, Capabilities, Available Skills (section name only — skill IDs stay English), Usage Scenarios, Best Practices, Examples, Limitations, See Also

4.5. For teams, translate:

Purpose, Team Composition (prose only — IDs stay English), Coordination Pattern, Task Decomposition, Usage Scenarios, Limitations

4.6. For guides, translate:

All prose sections, troubleshooting text, table descriptions
Keep command examples, code blocks, and configuration snippets in English

预期结果： All prose sections translated idiomatically. Code blocks identical to English source. Cross-references use English IDs.

失败处理： If uncertain about a technical term, keep the English term with a parenthetical translation. Example: "Staging-Bereich (Staging Area)" in German.

第 5 步：Verify structural integrity

5.1. Confirm the translated file has the same number of sections as the source.

5.2. For skills, verify all required sections are present:

YAML frontmatter with
```
name
```
,
```
description
```
,
```
allowed-tools
```
,
```
metadata
```
When to Use, Inputs, Procedure, Validation, Common Pitfalls, Related Skills

5.3. Verify code blocks are identical to the English source (diff the fenced blocks).

5.4. Check line count: skills must be ≤ 500 lines.

5.5. Verify

name

field matches the English source exactly (it is the ID, never translated).

预期结果： Structurally valid translated file that passes validation.

失败处理： Compare section-by-section with the English source. Restore any missing sections.

第 5.5 步：验证散文已翻译

5.5.1. 从翻译文件的正文中抽取 3 个散文段落。从不同章节选择段落——不包括标题、代码块或前置元数据。

5.5.2. 确认每个抽取的段落都用目标语言编写，而非英语。

5.5.3. 如果任何抽取的段落仍为英语，则翻译不完整。返回步骤 4，在继续之前翻译剩余的英语散文。

预期结果： 所有 3 个散文段落样本均为目标语言，确认正文内容已翻译——而不仅仅是标题和前置元数据。

失败处理： 识别哪些章节仍包含英语散文。在继续步骤 6 之前翻译它们。

第 6 步：Write the translated file

6.1. Write the complete translated content to the target path using the Write or Edit tool.

6.2. Verify the file exists at the expected path:

Skills:
```
i18n/<locale>/skills/<id>/SKILL.md
```
Agents:
```
i18n/<locale>/agents/<id>.md
```
Teams:
```
i18n/<locale>/teams/<id>.md
```
Guides:
```
i18n/<locale>/guides/<id>.md
```

预期结果： Translated file written to disk at the correct path.

失败处理： Check directory exists. Create with

mkdir -p

if needed.

验证清单

Translated file exists at
```
i18n/<locale>/<type>/<id>
```
```
name
```
field matches English source exactly
```
locale
```
field matches target locale
```
source_commit
```
field is set to a valid git short hash
All code blocks are identical to English source
All cross-referenced IDs (skills, agents, teams) are in English
File is under 500 lines (for skills)
```
npm run validate:translations
```
reports no issues for this file
Prose reads idiomatically in the target language

常见问题

Translating code blocks: Code, commands, and configuration must stay in English. Only translate surrounding prose.
Translating the
name
field: The
```
name
```
field is the canonical ID. Never translate it.
Translating tag values: Tags in
```
metadata.tags
```
stay in English for cross-locale consistency.
Inconsistent terminology: Use the same translation for a technical term throughout the file and across files in the same locale.
Literal translation of idioms: Translate the meaning, not the words. "Common Pitfalls" should become the locale's natural equivalent, not a word-for-word translation.
Missing
source_commit
: Without this field, freshness tracking breaks. Always include it.
Exceeding 500 lines: Translations may expand ~10-20% vs English. If near the limit, tighten prose rather than removing content.