Skip to content

AgriciDaniel/claude-blog / skills/blog-translate

blog-translate

Verified

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".

FileKindSize
SKILL.mdskill md12.7 KB
references/cultural-adaptation.mdmarkdown8.4 KB
references/translation-rules.mdmarkdown6.6 KB

references/translation-rules.md

View on GitHub
# 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 topical and entity coverage, not keyword density. Match the
   search intent and localized SERP phrasing without forcing repeated terms.
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.
- Executable code fences and inline code. Keep them unchanged unless the user
  explicitly asks for localized tutorial comments.
- SVG attributes (`x`, `y`, `fill`, `transform`, and `viewBox` or `font-size`
  unless the overflow rule below applies). Translate only `<text>` and
  `<tspan>` content.
- Schema JSON-LD blocks. Translate user-facing content strings such as
  `headline` and `description`; never translate Person, Organization, or
  Brand names, URLs, IDs, `@id`, or `sameAs`.
- Internal-link zone markers (`[INTERNAL-LINK: ...]`).

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

| Locale | Length delta vs. EN |
|--------|---------------------|
| DE | +25% to +30% |
| FR | +10% to +15% |
| ES | +10% |
| IT | +10% |
| PT-BR | +10% |
| JA | -20% (per character count) |
| ZH | -25% (per character count) |
| KO | -15% |

**SVG overflow rule (the one rule, used by the skill and the agent):** if text
overflows the chart frame, widen the `viewBox` or reduce `font-size`; never
truncate.

## Number, Date, Currency, and Quote Formats per Locale

| Locale | Decimal | Thousands | Date | Currency | Quotes |
|--------|---------|-----------|------|----------|--------|
| en-US | `.` | `,` | MM/DD/YYYY or "March 25, 2026" | $1,234.56 | "..." |
| en-GB | `.` | `,` | DD/MM/YYYY or "25 March 2026" | GBP 1,234.56 | '...' |
| de-DE | `,` | `.` | DD.MM.YYYY | 1.234,56 EUR | "..." |
| de-CH | `.` | `'` | DD.MM.YYYY | CHF 1'234.56 | "..." |
| fr-FR | `,` | ` ` (NBSP) | DD/MM/YYYY | 1 234,56 EUR | « ... » |
| fr-CA | `,` | ` ` (NBSP) | YYYY-MM-DD | 1 234,56 $ | « ... » |
| es-ES | `,` | `.` | DD/MM/YYYY | 1.234,56 EUR | «...» or "..." by publication style |
| es-MX | `.` | `,` | DD/MM/YYYY | $1,234.56 MXN | "..." |
| pt-BR | `,` | `.` | DD/MM/YYYY | R$ 1.234,56 | "..." |
| pt-PT | `,` | ` ` (NBSP) | DD/MM/YYYY | 1 234,56 EUR | «...» or "..." by publication style |
| it-IT | `,` | `.` | DD/MM/YYYY | 1.234,56 EUR | «...» or "..." by publication style |
| ja-JP | `.` | `,` | YYYY/MM/DD or YYYY-MM-DD | 1,234円 or JPY 1,234 | 「...」 |
| zh-CN | `.` | `,` | YYYY-MM-DD | CNY 1,234.56, ¥1,234.56, or 1,234.56元 | “...” or 「...」 by market style |
| nl-NL | `,` | `.` | DD-MM-YYYY | 1.234,56 EUR | '...' |
| pl-PL | `,` | ` ` (NBSP) | DD.MM.YYYY | 1 234,56 PLN | „...” |

Notes:

- Preserve reported facts and original amounts for sourced claims.
- Convert currency only when it helps the local reader, keep the original
  amount nearby, and include exchange date and source in the note or citation.
- If the source reports a factual claim such as "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: prefer `„...“` or `»...«`; straight quotes are only an explicit ASCII
  fallback.
- fr: `« ... »` with non-breaking or narrow no-break spaces inside.
- es, it, and pt-PT: use `«...»` or `"..."` according to publication style.
- ja: `「...」` primary and `『...』` nested.
- zh: use Chinese quote conventions such as `“...”` or `「...」` by market
  style.
- pl: `„...”` primary, with accepted nested forms such as `«...»` or
  `»...«` by publication style.

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.
- [ ] Evidence-backed explanations remain accurate and self-contained in the
      target language where present.
- [ ] No mixed-language sentences (other than loanwords).
- [ ] No literal idiom translations; idioms adapted to local equivalents.
- [ ] Information parity, section coverage, and readability are preserved.
- [ ] 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.

## Translation Provenance

Store translation provenance in frontmatter or CMS metadata, not rendered
comments, and do not append an HTML comment. Use `translatedFrom`,
`translatedDate`, `sourceHash` and `translationHash` (`blog-locale-audit`
uses them to spot a translation whose source changed); `translationTool` is optional. `sourceHash` is the
sha256 of the source file bytes and `translationHash` the sha256 of the
translated body (everything after the closing frontmatter `---`). The
translator agent has no Bash, so the orchestrator adds the two hashes in
`blog-translate` Phase 5.
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 323kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 323kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 323kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 323kUpdated Claude CodeCodexVerifiedInstall