razbakov/translate-blog-post

Translate Blog Post

When to use

Trigger this skill when:

• The user points at a single English blog post (URL, markdown filepath, or slug) and asks to translate it.
• They say "translate to 5 languages", "add German/Spanish/Russian/Ukrainian", "publish in other languages", "make multilingual versions".
• They want translations as a follow-up to publishing the original.

Do NOT use this for translating arbitrary text snippets, UI strings, or untouched non-blog content. This is specifically for blog posts that follow the repo's blog conventions.

Inputs the skill needs

Confirm or read from the project's CLAUDE.md / repo conventions:

| Input | Where it usually lives | |---|---| | Source post path | User-provided URL or filepath | | Target languages | User request, or default set in repo's CLAUDE.md (e.g. de, es, ru, uk) | | Filename convention | An existing 5-lang post in the same repo | | Frontmatter shape | An existing translation in the same repo | | Per-language overrides | Repo's CLAUDE.md (e.g. RU/UK Telegram channel differs from EN) | | Hero image policy | Repo's CLAUDE.md (usually shared across translations — same image: path) |

Read one existing 5-language post in the same repo before dispatching agents. Filename + frontmatter conventions are always per-repo and never inferred from training data.

Workflow

1. Read the source

Read the full English markdown — frontmatter and body. Note:

• Title, description, hero image path
• Category and tags (tags are usually slugs; do NOT translate them)
• Telegram / messaging links
• Voice register (formal? conversational? second person? umlaut on the author's name?)

2. Dispatch one sub-agent per target language (parallel)

For each target language, dispatch one sub-agent (in Claude Code: the Agent tool with subagent_type: general-purpose and run_in_background: true). Each prompt must include:

• The exact filepath to write (matching repo convention)
• The full source markdown (so the agent translates from the canonical version, not a paraphrase)
• The frontmatter template with that language's overrides (language: <lang>, telegram channel if it differs, etc.)
• Translation rules (see below)
• Explicit instruction: NO git commits

All agent dispatches go in a single message (parallel). One agent per language, not one per paragraph.

3. Translation rules to include in every agent prompt

Tailor per language but always cover:

• Voice & register — match the source. First-person if source is. Conversational if source is. Don't make it more formal than the English.
• Author's name — preserve umlauts and accents (e.g. "Alösha" stays "Alösha"; in Cyrillic-script languages use the native form like "Алёша" / "Альоша").
• Reserved nouns — Newton, Einstein, brand names, the Matrix → keep as proper nouns (translate to local scripts only when conventional, e.g. Cyrillic).
• Headings — translate H2/H3 too. Don't leave English headings.
• Cultural references — use the localized version where it exists (e.g. "the spoon doesn't exist" → "ложки не существует" in RU, "la cuchara no existe" in ES).
• Tags — keep as English slugs (they're URL paths, not display text).
• Form of address — informal ("ты" / "tú" / "du") unless the source repo's voice guide says otherwise.
• Native vocabulary — for Ukrainian especially: write proper Ukrainian, not Russian-sounding Ukrainian. Same caution applies to any closely-related language pair.

4. Verify, commit, deploy

When all language agents report back:

• Confirm each file exists with correct frontmatter (language:, hero image path, title in the target language, etc.).
• Stage all translation files and commit in one commit. Push.
• Wait for the deploy.
• Verify each language URL returns 200 (the canonical i18n URL is usually /<locale>/blog/<slug>-<locale> — check an existing 5-lang post to confirm the pattern).
• Verify the localized title shows in the rendered HTML (curl + grep <title>).

Report back with the 5 URLs grouped by language.

Common gotchas

• i18n routing prefix. Most Nuxt/Next sites with i18n route non-default-locale pages under /<locale>/.... Direct URLs without the prefix may also work (because the file is prerendered) but the canonical URL is the prefixed one — use that for sharing.
• Translation state inheritance. If the source post has hidden: true or draft: true, translations should usually inherit that. Confirm with the user before publishing translations of an unpublished essay.
• Hero image is usually shared, not duplicated. The same /images/blog/<slug>/hero.png works for all languages by default. Generate per-language images only when the hero embeds text or a culturally-specific symbol that wouldn't read in the target language.
• Tags are slugs, not display text. Translating tags breaks tag-based filtering and routing. Always keep the English slug.
• Per-language messaging channels. Some repos route RU + UK posts to a different Telegram/social channel than EN/DE/ES. Check the repo's CLAUDE.md for the mapping; don't hardcode.
• Don't translate the date. Date stays in ISO format.
• Don't have agents do git work in parallel. Same rule as essay-cluster-from-transcript — orchestrator commits, agents only write files.

Optional: review pass

After translation, the user may want a native-speaker review pass. Note in the final report which languages would benefit (typically RU/UK if the user is more confident in those, ES if not). Don't auto-trigger reviews — leave that as a follow-up.