references/cultural-adaptation.md
# Cultural Adaptation Profiles
Locale profiles for cultural deep-adaptation. Loaded on demand by
`blog-localize` and by `blog-multilingual` during 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 to DSGVO (GDPR in DACH-speak),
FTC to Bundeskartellamt, FCC to Bundesnetzagentur. Accessibility law is
jurisdiction-specific: DE BGG, AT BGStG, CH BehiG. Keep ADA when the claim
is specifically about US compliance.
- **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 for `fr-FR` and `fr-BE`, CHF for `fr-CH`, 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. Do not conflate `es-ES` with `es-MX` or
generic `es`. If a user writes `es`, ask which market or require explicit
neutral Spanish mode.
### 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 COP`). Use whole-peso COP examples unless a source explicitly
uses centavos. 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. Prefer `1,234円` in body copy or
`JPY 1,234` in finance-style 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:
```yaml
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 custom locale profiles outside this shared skill reference, for example in
a project-local `.claude/blog-locale-profiles/<locale>.md` file or in the task
output. Do not append runtime profiles to this file.
## Profile Selection Logic
Used by `blog-localize` (Phase 1) and `blog-multilingual` (Phase 4):
1. Exact locale match (`de-CH`, `fr-CA`, `es-MX`).
2. Language-only fallback only for unambiguous editorial markets (`de`, `fr`,
`ja`). Treat `es`, `pt`, `zh`, and any language spanning materially
different legal, currency, or script markets as ambiguous unless the user
requests explicit neutral mode.
3. Regional grouping (e.g., DACH for any `de-*`, LATAM for any
`es-*` other than `es-ES`).
4. Custom-locale template if no match.
references/translation-rules.md
# 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`, `font-size`, `fill`, `transform`,
`viewBox`). 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% |
If text overflows the chart frame, raise `viewBox` width 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. Use fields such as `translatedFrom`, `translatedDate`,
`translationTool`, `sourceHash`, and `translationHash`.
SKILL.md
---
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-invokable: true
argument-hint: "<file> --to <comma-separated-codes>"
license: MIT
compatibility: Standalone within claude-blog. Invoked by blog-multilingual.
metadata:
author: AgriciDaniel
version: "2.2.0"
category: blog
---
# 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) 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`. 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 every SVG attribute (`x`,
`y`, `font-size`, `fill`, `transform`).
- 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 (via Task) for each target language with:
- The source content.
- The keyword localization map from Phase 3.
- The target language code.
- Pointer to `references/translation-rules.md`.
- Instruction to limit this phase to language, register, natural topical
coverage, and formatting. Reserve brand, legal, statistic, and cultural
substitutions for `blog-localize`.
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:
```yaml
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.
- Evidence-backed explanations from the source remain intact where present.
3. Save translated files:
```
translations/
{lang}/{localized-slug}.{ext}
```
When invoked from `blog-multilingual`, save into
`multilingual/{lang}/{localized-slug}.{ext}` instead.
Before writing, slugify `{localized-slug}` to lowercase ASCII with only
`a-z`, `0-9`, and hyphens, rejecting empty or reserved names. Create the
language directory from the normalized hreflang code only. Resolve the
final path and require it to stay inside the intended output root; reject
symlinked output paths.
### 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
| Scenario | Action |
|----------|--------|
| Unsupported language code | Suggest the correct Google-compatible hreflang code |
| Source equals a target | Skip with "Source is already in [lang]" |
| File not found | Report error with suggested path |
| Translator agent timeout | Retry once, then report partial results |
| Binary or non-text file | Report error, suggest correct file |
## 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>`