/blog-translate

name: blog-translate
description: >
  Translate existing blog posts into one or more target languages with
  SEO-optimized localization. Produces native-quality translations that
  preserve markdown structure, frontmatter, schema JSON-LD, image and chart
  embeds, and evidence-backed explanations. Localizes keywords, meta tags, numbers,
  dates, currencies, and quote styles per locale. Flags machine-translation
  artifacts for review. Run BEFORE blog-localize: this handles language
  conversion; localize handles cultural adaptation after translation
  completes.
  Use when user says "translate blog", "blog translate", "uebersetzen",
  "traduire", "traducir", "translate post", "blog auf Deutsch", "blog en
  espanol".
user-invocable: true
argument-hint: "<file> --to <comma-separated-codes>"
license: MIT
compatibility: Standalone within claude-blog. Invoked by blog-multilingual.
metadata:
  author: AgriciDaniel
  version: "2.3.2"
  category: blog

Blog Translate, SEO-Optimized Blog Translation

Bundled paths below use host Markdown substitution of `${CLAUDE_SKILL_DIR}`; it is not an exported shell variable. Resolve them before execution, quote paths, and refuse nonabsolute overrides. Pass `blog_reference_root` resolved from `${CLAUDE_SKILL_DIR}/../blog/references`, `blog_template_root` from `${CLAUDE_SKILL_DIR}/../blog/templates`, and needed sibling roots to agents. Read the main reference `orchestration-details.md` before loading project context; pass only its helper-fenced output to downstream agents.

Translates an existing blog post into one or more target languages. Unlike generic translation, this skill produces SEO-optimized, publication-ready content with localized keywords, meta tags, and culturally correct formatting.

> Adapted from `claude-blog-multilingual` by Chris Mueller (Pro Hub Challenge, > March 2026). Original repository: no longer available as of 2026-10-12

Key References

Load on demand:

• `${CLAUDE_SKILL_DIR}/references/translation-rules.md`, format preservation, number/date/currency

formats per locale, quote handling, quality criteria.

• `${CLAUDE_SKILL_DIR}/references/cultural-adaptation.md`, cultural profiles per locale (DACH,

Francophone, Hispanic, Japanese, custom). This file is shared with `blog-localize` (do not duplicate).

Workflow

Phase 1: Input Parsing

1. Read the source file (markdown, MDX, or HTML) only after resolving it against the project root/current working directory. Reject symlinked paths, traversal outside the root, files over 10 MB, and binary files. 2. Auto-detect source language. Order of preference:

• Frontmatter `lang` field.
• HTML `lang` attribute.
• Content analysis (script, common stop words).

3. Parse target languages from `--to` as comma-separated Google-compatible hreflang tags (`de`, `fr`, `es-MX`, `ja`, `pt-BR`, `zh-Hant`). If `--to` is missing, ask the user once: "Which languages should I translate to? Provide hreflang tags such as de, fr, es-MX, ja, pt-BR." 4. Normalize every code with the shared multilingual locale rules used by `blog-multilingual`, `blog-localize`, and `blog-locale-audit`: ISO 639-1 language in lowercase, optional ISO 15924 script in title case, optional ISO 3166-1 Alpha-2 region in uppercase. Reject invalid codes with a suggestion (`jp` becomes "Did you mean `ja` for Japanese?"). Require a region or explicit neutral mode for ambiguous language-only targets such as `es`, `pt`, and `zh`. Google accepts a language code by itself as hreflang (https://developers.google.com/search/docs/specialty/international/localized-versions, read 2026-10-12), but never a region by itself; this stricter rule exists for translation quality, not because Google requires a region. If a target equals the normalized source language, skip it with a notice.

Phase 2: Content Analysis

Extract the translatable surface:

• Frontmatter: `title`, `description`, `tags`, `author` (only when

translatable, e.g. role labels, not personal names).

• All headings (H1, H2, H3).
• Body paragraphs.
• Image `alt` text and `<figcaption>` content.
• Chart `<text>` and `<tspan>` content; preserve SVG attributes (`x`, `y`,

`fill`, `transform`), except under the overflow rule: if text overflows, widen the `viewBox` or reduce `font-size`; never truncate (see `${CLAUDE_SKILL_DIR}/references/translation-rules.md`).

• FAQ questions and answers.
• Evidence-backed explanation text.
• Key Takeaways or summary box.
• CTA text.
• Internal-link zone anchor text.

Preserve unchanged:

• Markdown and HTML structure, tags, attributes.
• Image URLs, link URLs, frontmatter keys.
• Executable code fences and inline code. Translate comments only outside

executable code, or when the user explicitly asks for localized tutorial comments.

• Internal-link zone markers (`[INTERNAL-LINK: ...]`).
• Source organization names in citations (Gartner, McKinsey, etc.).
• Person names.
• Schema JSON-LD blocks (translate user-facing content strings only; never

translate Person, Organization, or Brand names, URLs, IDs, `@id`, or `sameAs`).

Identify the primary and secondary keywords for Phase 3.

Phase 3: Keyword Localization

For each target language:

1. Decide whether the source keyword is the established term in the target market. If yes (e.g., "Content Marketing" stays in German), keep it. 2. If a local equivalent has real search behavior, swap to it. 3. Apply the same logic to secondary keywords. 4. Record the mapping. The translator agent uses it to update title, meta description, and H2 headings consistently.

Phase 4: Translation

Spawn the `blog-translator` agent (Agent tool, one call per target language) with:

• The source content.
• The keyword localization map from Phase 3.
• The target language code.
• Pointer to `${CLAUDE_SKILL_DIR}/references/translation-rules.md`.
• Instruction to limit this phase to language, register, natural topical

coverage, and formatt