Idiomatic Translate

---
type: skill
id: idiomatic-translate
name: idiomatic-translate
description: Translate strings idiomatically across multiple target languages using a project glossary, preserving tone, domain terminology, and format placeholders while flagging untranslatable content.
layer: cross
category: content
created_at: 2026-03-02
updated_at: 2026-03-02
---

# Skill: Idiomatic Translate (Multi-Language)

## Purpose

Translate copy from any source language to any target language with idiomatic fluency, cultural awareness, domain expertise, and consistent voice — language-agnostic pattern optimized for B2B SaaS platforms.

> **Usage context:** Bulk translation of UI copy, help text, error messages, and onboarding content. Automatically detects source language. Replaces mechanical translation with culturally-aware, tonally-consistent output in the target language.

---

## Input

```json
{
  "source_string": "You pay $0.50 per direct link request",
  "source_language": null,                    // null = auto-detect, or explicit: "en", "fr", "de", "es"
  "target_language": "fr",                    // required: "en", "fr", "de", "es", "it", "pt", "nl", etc.
  "context": {
    "domain": "billing",                       // domain expertise context
    "component": "PricingCard",
    "tone": "transparent",                     // transparent, benevolent, precise, casual, formal, technical
    "audience": "expert",                      // expert, prospect, admin, user
    "key": "billing.directLink.perRequest"
  },
  "glossary": {
    "direct link": "lien direct",              // source term : target term (or multi-lang)
    "request": "demande",
    "lead": "prospect",
    "milestone": "jalon"
    // Can also use language-keyed format:
    // "direct link": { "fr": "lien direct", "de": "direkter Link", "es": "enlace directo" }
  },
  "regional_preferences": {
    "currency": "EUR",                         // override default currency ($→€, etc.)
    "date_format": "DD/MM/YYYY",
    "number_format": "de_DE"                   // locale code for number formatting
  },
  "notes": "Avoid formal 'vous' / use informal 'tu', clarify that €0.50 is machine cost not per-lead"
}
```

## Output

```json
{
  "translated_string": "Tu paies 0,50 € par demande traitée",
  "source_language_detected": "en",
  "target_language": "fr",
  "confidence": "high",                         // high, medium, low
  "idiomaticity_score": 4.5,                    // 1-5 scale (5 = native speaker fluency)
  "notes": "Changed 'requête' to 'demande' (more natural in billing context). Used '€' instead of '$' for FR audience. Used informal 'tu' per context. Tone: factual, reassuring.",
  "alternatives": [
    {
      "text": "Tu paies 0,50 € par traitement de demande",
      "note": "More formal variant"
    },
    {
      "text": "Chaque demande te coûte 0,50 €",
      "note": "More casual variant"
    }
  ],
  "cultural_notes": "French audience expects € currency and informal 'tu' in UX context. 'Demande' is more natural than 'requête' in billing."
}
```

---

## Translation Principles (Universal)

### 1. **Idiomatic > Literal**
- ❌ "You pay $0.50 per request" → literal French: "Vous payez 0,50 $ par requête"
- ✅ "You pay $0.50 per request" → idiomatic French: "Vous payez 0,50 € par demande"

(Reasoning: FR audience expects €, not $. "Demande" is more natural than "requête" in billing context.)

**For any language pair:** Prioritize cultural norms, expected terminology, and natural phrasing over word-for-word mapping.

### 2. **Domain-Aware Glossary Alignment**

Glossary can be:
- **Flat (single language pair):** `{ "source": "target" }`
- **Multi-language keyed:** `{ "term": { "en": "...", "fr": "...", "de": "..." } }`

Example (project domain):

| EN | FR | DE | ES |
|---|---|---|---|
| **Lead** | prospect | Lead / Interessent | prospecto |
| **Direct link** | lien direct | direkter Link | enlace directo |
| **Milestone** | jalon | Meilenstein | hito |
| **Expertise** | domaine de compétence | Fachgebiet | área de expertise |
| **Spending limit** | limite de dépenses | Ausgabenlimit | límite de gasto |

**Skill behavior:** Always check glossary first. If term exists in target language, use it. If not, translate idiomatically and flag for glossary update.

### 3. **Universal Tone & Voice Principles**

Define voice once, apply across all languages:

| Attribute | Principle | EN Example | FR Example | DE Example |
|---|---|---|---|---|
| **Transparent** | Explain the WHY | "You pay for qualified leads" | "Vous payez pour les prospects qualifiés" | "Sie zahlen für qualifizierte Leads" |
| **Benevolent** | Avoid blame | "Honest experts get better leads" | "Les experts honnêtes reçoivent de meilleurs prospects" | "Ehrliche Experten erhalten bessere Leads" |
| **Precise** | Avoid vague terms | "50 free requests" | "50 demandes gratuites" | "50 kostenlose Anfragen" |
| **Multi-lang ready** | Avoid untranslatable idioms | Prefer universal phrasing | Structure that works across languages | Cultural idioms verified in target lang |

### 4. **Context-Aware Adaptation**

These apply to ANY language pair:
- **Audience:** Expert (formal) vs Prospect (friendly) → affects formality level
- **Urgency:** Error message (concise) vs Help text (detailed) → affects length
- **Domain:** Billing (precise) vs Onboarding (encouraging) → affects tone
- **Length:** Button text has tight constraints → abbreviation strategies per language
- **Regional preferences:** Currency, date format, number separators (e.g., $, €, CHF; DD/MM/YYYY vs MM/DD/YYYY; 1.000,50 vs 1,000.50)

---

## Acceptance Criteria for Translation Quality (Universal)

- [ ] **AC1:** No word-for-word translation (idiomatic fluency required in target language)
- [ ] **AC2:** Glossary consistency — if term exists, use it; if not, flag for addition
- [ ] **AC3:** Tone matches voice definition (transparent, benevolent, precise) across language
- [ ] **AC4:** No untranslatable idioms (if source uses culturally-specific metaphor, adapt to target culture)
- [ ] **AC5:** Character length ≤ 120% of original (avoid unnecessary bloat on buttons/short fields)
- [ ] **AC6:** Regional preferences respected (currency, date format, number formatting)
- [ ] **AC7:** If uncertainty, provide 2-3 alternatives + rationale for each
- [ ] **AC8:** Cultural notes provided (e.g., "German audience expects formal 'Sie' in B2B context")

---

## Output Format

Always return:
1. **translated_string** — the translated text in target language
2. **source_language_detected** — auto-detected or confirmed source language (ISO 639-1: en, fr, de, es, etc.)
3. **target_language** — target language (as requested)
4. **confidence** — "high", "medium", "low" (based on ambiguity or cultural nuance)
5. **idiomaticity_score** — 1-5 scale (5 = native speaker fluency, 1 = mechanical)
6. **notes** — why this translation was chosen (reasoning, cultural decisions, tone adjustments)
7. **alternatives** — 2-3 alternative translations with rationale for each
8. **cultural_notes** — any culture-specific context or expectations in target language region

---

## Batch Workflow (Recommended)

Translate in batches (language pair agnostic):

```
Input: Array of {
  source_string,
  source_language: null or "en"/"fr"/"de"/etc.,
  target_language: "fr" or "de" or "es"/etc.,
  context,
  glossary
}

Process:
1. Auto-detect source language (if not provided)
2. Translate each string to target language
3. Apply domain glossary, tone, regional preferences
4. Provide alternatives + confidence scores

Output: JSON array {
  key,
  source_language_detected,
  target_language,
  translated_string,
  confidence,
  idiomaticity_score,
  notes,
  alternatives,
  cultural_notes
}

Review: Human expert reads all "medium/low" confidence items + "idiomaticity_score" < 4.0
Finalize: Choose final translation or iterate with skill
```

**Velocity:** ~50-80 strings per batch per language pair (1-2 hours with review).
**Scaling:** Batch translate to DE, ES, IT simultaneously (parallel skill invocations).

---

## Known Constraints

- **Terminology drift:** New terms must update glossary immediately (reuse across all language pairs)
  - Example: "qualification_rate" → glossary should map: `{ "qualification_rate": { "en": "qualification rate", "fr": "taux de qualification", "de": "Qualifizierungsquote" } }`
- **Context dependency:** Same source phrase can translate differently in billing vs error context — always provide context
- **Humor/idioms:** Culture-specific wordplay is hard to translate idiomatically — flag for manual review or rephrase
- **Regional variants:** Same language can have regional differences (e.g., European Spanish vs Latin American Spanish, European Portuguese vs Brazilian Portuguese)
- **Names/proper nouns:** Keep unchanged (your project name, n8n, Zapier, OpenAI, etc.)
- **Currency/date/number:** Use regional preferences to adapt formatting

---

## Language Coverage & Auto-Detection

**Supported languages (confidence > 95%):**
- EN (English), FR (Français), DE (Deutsch), ES (Español), IT (Italiano), PT (Português), NL (Nederlands)
- Extensible to others (JA, ZH, etc.) with similar workflow

**Auto-detection:** Claude's native language detection used if `source_language` is null. Explicit source language preferred if known.

---

## Notes for Delivery Agent

This skill is **discovery-phase only** (creates translated content artefacts). The Delivery Agent will:

1. **Extract strings** from codebase → JSON with `source_language`, `target_language`, `context`
2. **Batch translate** to one or more target languages (parallel invocations OK)
3. **Use skill** to generate translations with glossary + tone
4. **Review output** — all "medium/low" confidence + idiomaticity_score < 4.0
5. **Iterate** with skill if needed (provide feedback, alternative examples)
6. **Integrate** into i18n JSON files (structure: `locales/{lang}/*.json`)
7. **Commit** to version control
8. **Update glossary** with any new terms discovered during translation

**Post-MVP automation:** CI/CD pipeline can auto-translate new strings → PR (human review required for merge). This skill can handle the automation.

**Multi-language parallelization:** Extract strings once, translate to FR, DE, ES simultaneously (3 parallel skill invocations = faster than sequential).