Blog Translate

Blog Translate, SEO-Optimized Blog Translation

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: https://github.com/Chriss54/multilingual-int

Key References

Load on demand:

• references/translation-rules.md, format preservation, number/date/currency

formats per locale, quote handling, quality criteria.

• 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). 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 ISO 639-1 codes (de,fr,es,ja,pt-BR). If --to is missing, ask the user once: "Which languages should I translate to? Provide ISO 639-1 codes (e.g., de, fr, es, ja, pt-BR)." 4. Validate every code. Reject invalid ones with a suggestion (jp becomes "Did you mean ja for Japanese?"). If a target equals the 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 every SVG attribute (x,

y, font-size, fill, transform).

• FAQ questions and answers.
• Citation capsule 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.
• Code blocks (translate inline comments only when meaningful).
• Internal-link zone markers ([INTERNAL-LINK: ...]).
• Source organization names in citations (Gartner, McKinsey, etc.).
• Person names.
• Schema JSON-LD blocks (translate only the user-facing string values).

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 (via Task) for each target language with:

• The source content.
• The keyword localization map from Phase 3.
• The target language code.
• Pointers to references/translation-rules.md and the cultural profile in

references/cultural-adaptation.md if one exists for the target locale.

Run agents in parallel when translating into multiple languages.

The agent returns the fully translated post in the same format as the input.

Phase 5: Post-Processing

For each translated version:

1. Add or update locale frontmatter:

   lang: "de"
   translatedFrom: "en"
   translatedDate: "YYYY-MM-DD"
   slug: "wie-man-ki-slop-vermeidet"

2. Verify structural integrity:

• Same number of H2 and H3 sections as the original.
• All images present with translated alt text.
• All SVG charts present with translated text labels (length-adjusted:

DE +30%, FR +15%, JA -20%, others see references/translation-rules.md).

• FAQ count matches.
• Citation capsules present in each H2.

3. Save translated files:

   translations/
     {lang}/{localized-slug}.{ext}

When invoked from blog-multilingual, save into multilingual/{lang}/{localized-slug}.{ext} instead.

Phase 6: Translation-Quality Guardrails

Scan the output for machine-translation artifacts before reporting done:

• Literal idioms (English idioms transliterated, not adapted).
• Unnatural word order (SOV translated as SVO into a non-SVO language, or

the reverse).

• Mixed-language sentences (other than established loanwords).
• Number, date, or currency strings still in source format.
• Frontmatter strings still in the source language.

Flag every issue inline (file path, line number, fix suggestion). The translator agent should re-pass any flagged passage before delivery.

Phase 7: Delivery

## Translation complete: [Original title]

### Source
- Language: [source]
- File: [source path]

### Translations
| Language | File | Keywords adapted | Status |
|----------|------|------------------|--------|
| de | translations/de/{slug}.md | [N] | ok |
| fr | translations/fr/{slug}.md | [N] | ok |

### Quality checks
- Structural integrity: pass / fail per language
- Meta tags localized: pass / fail per language
- Numbers, dates, currencies formatted per locale: pass / fail
- Keywords localized: [N] keywords adapted
- Machine-translation artifacts flagged: [N] (see notes above)

### Next steps
- Run `/blog localize <file> --locale <code>` for cultural deep-adaptation.
- Run `/blog locale-audit translations/` to verify completeness.
- Use `/blog multilingual` to combine write, translate, localize, hreflang
  in one command.

Error Handling

Cross-References

• Next step (cultural depth): /blog localize <file> --locale <code>
• QA sweep across all language versions: /blog locale-audit <directory>
• One-command pipeline: /blog multilingual <topic> --languages <codes>

Cultural Adaptation Profiles

Locale profiles for cultural deep-adaptation. Loaded on demand by both blog-translate (at translation time) and blog-localize (for the adaptation pass). This file is the single source of truth, do not duplicate it elsewhere.

Each profile covers: address form (formality), example brands and companies to substitute in, currency and pricing conventions, statistics sources to prefer, legal references to swap, CTA tone, and idiom notes.

DACH (Germany, Austria, German-speaking Switzerland)

Locales: de-DE, de-AT, de-CH.

• Formality: B2B and tech: Sie (formal). Lifestyle, gaming,

D2C: du (informal). Pick one and use it consistently for the entire post. SaaS for SMB defaults to du; enterprise SaaS defaults to Sie.

• Brand examples to swap to: MediaMarkt, Saturn, Otto,

Zalando (retail), Lidl, Aldi (grocery), Deutsche Bank, ING (finance), SAP, Siemens (B2B tech). For Austria: Spar, Hofer, BAWAG. For Swiss: Migros, Coop, UBS.

• Currency: EUR for DE and AT, CHF for CH. Format: 1.234,56 EUR

(DE/AT) or CHF 1'234.56 (CH).

• Statistics sources to prefer: Statista (Germany scope), Bitkom,

Bundesnetzagentur, Destatis (Statistisches Bundesamt), HWWI, ifo Institut, Bertelsmann Stiftung. Avoid US-only Pew or Nielsen unless explicitly framed as US comparison.

• Legal references to swap: CCPA -> DSGVO (GDPR in DACH-speak),

FTC -> Bundeskartellamt, FCC -> Bundesnetzagentur, ADA -> BGG.

• CTA tone: Informational, never imperative. Prefer "Jetzt

entdecken", "Mehr erfahren", "Kostenlos testen". Avoid "Buy now", "Sign up today" style. Trust signals (data protection, GDPR compliance) outperform urgency.

• Idiom notes: Compound nouns are normal; don't break them.

"Game-changer" becomes "Wendepunkt" or specific concrete claim. "Best practices" stays in English.

Francophone (France, Quebec, Belgium-FR, Switzerland-FR)

Locales: fr-FR, fr-CA, fr-BE, fr-CH.

• Formality: Default vous for almost all professional content.

tu only for B2C lifestyle aimed at under-30 audiences. France business culture is markedly more formal than US.

• Brand examples to swap to: Carrefour, Auchan, Leclerc, FNAC

(retail/electronics), Orange, SFR (telecom), BNP Paribas, Société Générale (finance), Dassault, Capgemini (B2B tech). Quebec: Hydro-Québec, Desjardins, Couche-Tard.

• Currency: EUR (FR, BE, FR-CH context CHF), CAD for fr-CA. Format:

1 234,56 EUR (NBSP as thousands separator). Quebec writes CAD as 1 234,56 $ with the symbol after.

• Statistics sources to prefer: INSEE, Médiamétrie, IFOP, BVA,

ARCOM (formerly CSA), Statistique Canada (for fr-CA), Eurostat (for fr-FR European context).

• Legal references to swap: CCPA / GDPR -> RGPD, FTC -> DGCCRF,

ADA -> loi du 11 février 2005. Quebec adds Loi 25 (privacy) and Loi 96 (French language).

• CTA tone: Polite, restrained, value-focused. "Découvrez",

"En savoir plus", "Essayer gratuitement". Avoid "Achetez maintenant" unless e-commerce flash-sale context. Quebec accepts slightly more direct CTAs than France.

• Idiom notes: "Workflow" stays English in tech contexts. "Brand"

often translated as "marque". Be careful with Quebec vs. France vocabulary differences (e.g., "courriel" vs. "email", "fin de semaine" vs. "weekend").

Hispanic (Spain vs. LATAM)

Hispanic markets split sharply. Don't conflate es-ES with es-MX or generic es. If a user writes es, ask which market.

Spain (es-ES)

• Formality: tú for B2C and most digital content. usted only

for highly formal B2B (banking, legal). "Vosotros" exists; LATAM doesn't use it.

• Brand examples: El Corte Inglés, Mercadona, Carrefour España

(retail), Telefónica/Movistar, Vodafone España (telecom), Santander, BBVA (finance), Inditex/Zara, Iberdrola (B2B).

• Currency: EUR. Format: 1.234,56 EUR.
• Sources: INE (Instituto Nacional de Estadística), CIS,

IAB Spain, Comscore España, Eurostat.

• Legal: RGPD (GDPR), AEPD (data protection authority),

CNMC (competition), Ley General de Publicidad.

• CTAs: Direct but warm. "Descubre", "Empieza ahora",

"Pruébalo gratis".

LATAM (Mexico es-MX, Argentina es-AR, Colombia es-CO)

• Formality: tú general default. Argentina uses vos (voseo).

Colombia mixes tú and usted depending on region. Mexico is consistently tú.

• Brand examples (MX): Walmart México, Liverpool, Coppel,

Telcel, BBVA México, Bimbo. (AR): Mercado Libre, Banco Galicia. (CO): Éxito, Bancolombia, Rappi.

• Currency: Local. MXN ($1,234.56 MXN), ARS ($1.234,56),

COP ($1.234,56 COP). Always specify the currency code; bare $ is ambiguous.

• Sources: INEGI (MX), DANE (CO), INDEC (AR), Comscore LATAM,

IAB LATAM.

• Legal: LFPDPPP (MX), Ley 1581 (CO), Ley 25.326 (AR). PROFECO

(MX consumer protection).

• CTAs: Warm, direct, relationship-building. "Descubre cómo",

"Únete gratis", "Empieza hoy".

Japanese (Japan, ja-JP)

• Formality registers: Three to know. desu/masu (polite, default

for most published content). de aru (declarative, used in serious essays, white papers). Casual forms (da, plain verbs) for blog posts aimed at consumer audiences. Pick one register and stay in it.

• Honorifics: Use -san when referring to people. Companies

take sama in formal contact contexts but not in editorial body.

• Brand examples: Aeon, Ito-Yokado, Don Quijote (retail),

Rakuten, Mercari (e-commerce), NTT Docomo, SoftBank (telecom), MUFG, SMBC (finance), Sony, Toyota, Hitachi (B2B), LINE, PayPay (payments).

• Currency: Yen, no decimals. Format: 1,234 yen or JPY 1,234.

Use the kanji "yen" character in body copy when the publication prefers JP characters; ASCII "yen" is acceptable for SEO contexts.

• Sources: Statistics Bureau of Japan (Soumusho), METI, Nikkei

research, Dentsu reports, Macromill, Recruit Works Institute, Mitsubishi Research.

• Legal: APPI (Act on Protection of Personal Information),

JFTC (Japan Fair Trade Commission), METI guidelines.

• CTAs: Soft, indirect, group-oriented. Avoid imperative tone.

Prefer phrases that emphasize benefit, ease, or community ("everyone is using it" angles). Hard urgency converts poorly.

• Idiom notes: English loanwords (katakana) are common in tech

copy but should be reserved for established terms. Avoid inventing new katakana words. Numbered lists work well; rhetorical questions are less common than in EN.

Custom-Locale Template

When the target locale lacks a profile here, build one inline. Required fields:

locale: <code>           # e.g. nl-NL, pl-PL, sv-SE, tr-TR
formality:
  default: <formal|informal|mixed>
  notes: <when to switch>
brand_examples:
  retail: [..., ...]
  finance: [..., ...]
  telecom: [..., ...]
  b2b_tech: [..., ...]
currency:
  code: <ISO 4217>
  format: <example: 1 234,56 PLN>
sources_preferred:
  - <local statistics body>
  - <local industry research>
legal_references:
  privacy: <local equivalent of GDPR/CCPA>
  competition: <regulator>
  advertising: <regulator>
cta_tone:
  style: <imperative|informational|polite|warm>
  avoid: [...]
idiom_notes: <quirks the translator must respect>

Quick research pass to fill the template:

1. Search [country] official statistics agency for the sources block. 2. Search [country] data protection authority for the legal block. 3. Pull the top 3 retailers and top 3 banks from a recent business press article. 4. Read 2-3 native blog posts in the target market to calibrate formality.default and cta_tone.style.

Save the new profile by appending it as a new section in this file (prefixed with the locale name) so future runs reuse it.

Profile Selection Logic

Used by blog-translate (Phase 4) and blog-localize (Phase 1):

1. Exact locale match (de-CH, fr-CA, es-MX). 2. Language-only fallback (de, fr, es, ja). 3. Regional grouping (e.g., DACH for any de-*, LATAM for any es-* other than es-ES). 4. Custom-locale template if no match.

Translation Rules

SEO and format rules for blog translation. Loaded on demand by blog-translate and the blog-translator agent.

SEO Translation Principles

1. Localize, do not transliterate. Pick the term native speakers actually search for in the target market. 2. Preserve keyword density, not word-for-word match. The localized keyword should appear with similar frequency to the source keyword, not the same count. 3. Independently optimize the title tag and meta description per language. Don't translate, rewrite for the target SERP. 4. Keep slugs in the target language using the locale's romanization rules. 5. Translate alt text and figcaptions; never leave English alt text on a non-English page. 6. Names of organizations, brands, and people stay in their canonical form.

Format Preservation

Preserve unchanged:

• Markdown structure (headings, lists, blockquotes, code fences).
• HTML tags and attributes.
• Frontmatter keys (translate values, not keys).
• Image and link URLs.
• Code blocks. Translate inline comments only when the comment is

human-facing prose.

• SVG attributes (x, y, font-size, fill, transform,

viewBox). Translate only <text> and <tspan> content.

• Schema JSON-LD blocks. Translate user-facing string values

(headline, description, name); leave structural fields (@type, @context, URLs) untouched.

• Internal-link zone markers ([INTERNAL-LINK: ...]).

Adjust SVG text length where the translation is meaningfully longer or shorter than the source:

If text overflows the chart frame, raise viewBox width or reduce font-size, never truncate.

Number, Date, Currency, and Quote Formats per Locale

Notes:

• Always use the locale's currency unless the source explicitly compares

values across currencies.

• Convert USD figures only when the audience benefits. If the source is

reporting "the global tech sector earned $X", keep USD with locale number formatting.

• For dates inside frontmatter (date, lastUpdated, translatedDate),

always use ISO 8601 (YYYY-MM-DD) regardless of locale. Locale formatting applies to dates inside body copy only.

Quote Handling

• en: "..." and '...'.
• de: "..." (with low-9 opening, high-6 closing in print-quality copy

the writer can simplify to "..." for web).

• fr: <<...>> with non-breaking spaces inside (<< ... >>).
• es and it: <<...>> for primary, "..." for nested.
• ja: square brackets for primary, round brackets for nested.
• pl: ,,..." (low-9 opening, high-6 closing).

When the source uses straight quotes, the translator should switch to the locale's primary style above. Preserve nesting depth (outer vs. inner).

Quality Criteria Checklist

Before reporting a translation as done, verify:

• [ ] No untranslated source-language fragments (except established

loanwords like "Content Marketing" in DE).

• [ ] All numbers, dates, currencies use locale format.
• [ ] All quote marks switched to locale style.
• [ ] Frontmatter strings localized (title, description, tags,

slug).

• [ ] All image alt text translated.
• [ ] All <figcaption> content translated.
• [ ] All SVG <text> and <tspan> content translated, lengths

adjusted per the table above.

• [ ] FAQ questions and answers natural in target language.
• [ ] Citation capsules self-contained in target language.
• [ ] No mixed-language sentences (other than loanwords).
• [ ] No literal idiom translations; idioms adapted to local equivalents.
• [ ] Sentence-length parity within +/- 25% of source paragraph length.
• [ ] Markdown and HTML structure intact.
• [ ] Schema JSON-LD inLanguage updated and translationOfWork added.

Banned Patterns in Translation

Never produce:

• Mixed-language sentences (other than established English loanwords).
• Google-Translate-quality literal output.
• Inconsistent formal or informal address within a single document.
• Literally translated English idioms.
• Preserved English SVO sentence structure forced into non-SVO languages.
• English source-attribution like "(Source)" left untranslated where the

locale uses a different convention.

Output Metadata Comment

Append at the very end of the translated file:

<!-- translated: {source_lang} -> {target_lang} | date: {YYYY-MM-DD} | translator: blog-translator -->

For HTML output, use a standard HTML comment:

<!-- translated: en -> de | date: 2026-04-27 | translator: blog-translator -->