From agent-almanac
Translates agent-almanac skills, agents, teams, or guides to target locales (e.g., de, zh-CN, ja), preserving code blocks, frontmatter, IDs, and structure. Use for localizing content, updating stale translations, or batch processing.
npx claudepluginhub pjt222/agent-almanacThis skill uses the workspace's default tool permissions.
---
Translates repository README.md to multilingual variants like README.zh.md, adds language switchers, preserves GitHub Markdown structure, badges, code, and repo mechanics. Use for localizing repo docs.
Translates MkDocs docs from en/ folders to target locale, mirrors structure in new folder, creates git branch, updates includes and mkdocs.yml i18n config.
Translates UI strings, documentation, marketing copy preserving tone, style, natural word order. Context-aware: infers register, domain from source and codebase.
Share bugs, ideas, or general feedback.
Translate English source content into a target locale, preserving technical accuracy and structural integrity.
skills, agents, teams, or guidescreate-r-package)de, zh-CN, ja, es)1.1. Determine the source file path:
skills/<id>/SKILL.mdagents/<id>.mdteams/<id>.mdguides/<id>.md1.2. Read the entire source file to understand context, structure, and content.
1.3. Identify sections that must stay in English:
name, tools, model, priority, skills list entries, allowed-tools, tags, domain, language)<!-- CONFIG:START --> / <!-- CONFIG:END --> blocks in teamsExpected: Full understanding of source content with clear mental separation of translatable prose vs preserved technical content.
On failure: If source file is not found, verify the ID exists in the registry. Check for typos in the content type or ID.
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 localesource_locale — ensource_commit — current git short hashtranslator — attribution stringtranslation_date — today's dateExpected: Scaffolded file at i18n/<locale>/<content-type>/<id>/SKILL.md (or .md for other types) with correct frontmatter.
On failure: If the scaffold script fails, create the directory manually with mkdir -p and copy the source file. Add frontmatter fields manually.
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.
Expected: Description field contains an idiomatic translation that accurately conveys the original meaning.
On failure: If the description is ambiguous, keep it closer to literal translation rather than risk misinterpretation.
4.1. Translate all prose content section by section:
4.2. Preserve these elements exactly as-is:
backtick-wrapped)**Expected:** and **On failure:** markers (translate the label, keep the structure)4.3. For skills, translate the standardized section names:
4.4. For agents, translate:
4.5. For teams, translate:
4.6. For guides, translate:
Expected: All prose sections translated idiomatically. Code blocks identical to English source. Cross-references use English IDs.
On failure: If uncertain about a technical term, keep the English term with a parenthetical translation. Example: "Staging-Bereich (Staging Area)" in German.
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:
name, description, allowed-tools, metadata5.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).
Expected: Structurally valid translated file that passes validation.
On failure: Compare section-by-section with the English source. Restore any missing sections.
5.5.1. Sample 3 prose paragraphs from the body of the translated file. Choose paragraphs from different sections — not headings, not code blocks, not frontmatter.
5.5.2. Confirm each sampled paragraph is written in the target language, not English.
5.5.3. If any sampled paragraph is still in English, the translation is incomplete. Return to Step 4 and translate the remaining English prose before proceeding.
Expected: All 3 sampled prose paragraphs are in the target language, confirming the body text has been translated — not just headings and frontmatter.
On failure: Identify which sections still contain English prose. Translate them before continuing to Step 6.
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:
i18n/<locale>/skills/<id>/SKILL.mdi18n/<locale>/agents/<id>.mdi18n/<locale>/teams/<id>.mdi18n/<locale>/guides/<id>.mdExpected: Translated file written to disk at the correct path.
On failure: Check directory exists. Create with mkdir -p if needed.
i18n/<locale>/<type>/<id>name field matches English source exactlylocale field matches target localesource_commit field is set to a valid git short hashnpm run validate:translations reports no issues for this filename field: The name field is the canonical ID. Never translate it.metadata.tags stay in English for cross-locale consistency.source_commit: Without this field, freshness tracking breaks. Always include it.