Ai Translating Content

AI Translating Content

Translate text between languages while preserving brand voice, enforcing glossary terms, and supporting batch i18n workflows — using DSPy signatures and optimizers.

Step 1 - Understand the translation task

Before writing any code, ask:

• What content? UI strings, marketing copy, support tickets, help docs, legal text?
• What languages? Specific locales (e.g., es-MX vs es-ES) or open-ended?
• Do you have a glossary? Brand terms, product names, and technical terms that must not be translated?
• Tone/formality? Casual app copy vs formal documentation vs friendly support replies?
• Volume? One-off translation vs batch i18n file processing?
• Quality bar? Best-effort draft vs publication-ready?

The answers determine whether you need a simple signature or a full pipeline with glossary enforcement and quality scoring.

Step 2 - Build a basic translator

import dspy

lm = dspy.LM("openai/gpt-4o-mini")  # or "anthropic/claude-sonnet-4-5-20250929", etc.
dspy.configure(lm=lm)

class Translate(dspy.Signature):
    """Translate source_text into the target_language. Preserve formatting, tone, and meaning."""
    source_text: str = dspy.InputField(desc="Text to translate")
    target_language: str = dspy.InputField(desc="Target locale, e.g. 'Spanish (Mexico)' or 'fr-FR'")
    translated_text: str = dspy.OutputField(desc="Translation in the target language")

translator = dspy.Predict(Translate)

result = translator(
    source_text="Get started for free",
    target_language="Spanish (Mexico)"
)
print(result.translated_text)
# → "Comienza gratis"

Step 3 - Add glossary enforcement

Brand terms and product names must survive translation unchanged. Pass them explicitly — do not rely on the model to infer them.

from pydantic import BaseModel
from typing import list

class TranslationResult(BaseModel):
    translated_text: str
    glossary_terms_used: list[str]  # terms from the glossary preserved as-is

class TranslateWithGlossary(dspy.Signature):
    """Translate source_text into target_language. Terms listed in glossary must appear
    verbatim in the output — do not translate them."""
    source_text: str = dspy.InputField()
    target_language: str = dspy.InputField()
    glossary: list[str] = dspy.InputField(
        desc="Terms that must NOT be translated (product names, brand terms, technical terms)"
    )
    result: TranslationResult = dspy.OutputField()

translator = dspy.Predict(TranslateWithGlossary)

result = translator(
    source_text="Upgrade to Acme Pro to unlock unlimited Workspaces.",
    target_language="Spanish (Mexico)",
    glossary=["Acme Pro", "Workspaces"]
)
print(result.result.translated_text)
# → "Actualiza a Acme Pro para desbloquear Workspaces ilimitados."
print(result.result.glossary_terms_used)
# → ["Acme Pro", "Workspaces"]

Step 4 - Locale-aware tone

Pass tone as an explicit input field. Do not rely on the model to infer formality from the locale.

class TranslateLocaleAware(dspy.Signature):
    """Translate source_text into target_language using the specified tone.
    Glossary terms must appear verbatim."""
    source_text: str = dspy.InputField()
    target_language: str = dspy.InputField(desc="Target locale, e.g. 'pt-BR' or 'German (formal)'")
    tone: str = dspy.InputField(
        desc="One of: casual, neutral, formal. Controls register and vocabulary."
    )
    glossary: list[str] = dspy.InputField(default=[])
    translated_text: str = dspy.OutputField()

translator = dspy.Predict(TranslateLocaleAware)

result = translator(
    source_text="Hey! Check out what's new this week.",
    target_language="French (France)",
    tone="casual",
    glossary=[]
)

Step 5 - Batch translation for i18n files

Translate each key individually. Do not concatenate all strings into one call — that degrades quality and makes glossary enforcement unreliable.

import json

def translate_i18n_file(
    source_path: str,
    target_language: str,
    glossary: list[str],
    tone: str = "neutral"
) -> dict:
    with open(source_path) as f:
        strings = json.load(f)  # {"key": "English string", ...}

    translator = dspy.Predict(TranslateLocaleAware)
    translated = {}

    for key, text in strings.items():
        result = translator(
            source_text=text,
            target_language=target_language,
            tone=tone,
            glossary=glossary
        )
        translated[key] = result.translated_text

    return translated

# Usage
es_strings = translate_i18n_file(
    source_path="locales/en.json",
    target_language="Spanish (Mexico)",
    glossary=["Pro", "Workspace", "Dashboard"],
    tone="casual"
)

with open("locales/es-MX.json", "w") as f:
    json.dump(es_strings, f, ensure_ascii=False, indent=2)

For large files, add a progress bar and rate-limit retries:

from tqdm import tqdm

for key, text in tqdm(strings.items(), desc="Translating"):
    ...

Step 6 - Quality estimation per segment

Add a confidence score output to flag segments that need human review.

class TranslationWithQuality(BaseModel):
    translated_text: str
    confidence: float  # 0.0–1.0
    needs_review: bool
    review_reason: str  # empty string if needs_review is False

class TranslateWithQuality(dspy.Signature):
    """Translate source_text into target_language. Also estimate translation confidence:
    1.0 = straightforward, <0.7 = ambiguous or idiom-heavy, flag for human review."""
    source_text: str = dspy.InputField()
    target_language: str = dspy.InputField()
    glossary: list[str] = dspy.InputField(default=[])
    result: TranslationWithQuality = dspy.OutputField()

translator = dspy.Predict(TranslateWithQuality)

result = translator(
    source_text="We'll circle back on this once we've boiled the ocean.",
    target_language="Japanese",
    glossary=[]
)

if result.result.needs_review:
    print(f"Review needed: {result.result.review_reason}")

Step 7 - Test and optimize

Glossary compliance metric

def glossary_compliance(example, pred, trace=None):
    glossary = example.glossary
    translated = pred.result.translated_text if hasattr(pred, "result") else pred.translated_text
    # All glossary terms must appear verbatim in the translation
    return all(term in translated for term in glossary)

Meaning preservation judge

class MeaningPreservationJudge(dspy.Signature):
    """Given a source text and its translation, judge whether the meaning is fully preserved.
    Return a score from 0 to 1."""
    source_text: str = dspy.InputField()
    translated_text: str = dspy.InputField()
    target_language: str = dspy.InputField()
    score: float = dspy.OutputField(desc="0.0 = meaning lost, 1.0 = meaning fully preserved")

judge = dspy.Predict(MeaningPreservationJudge)

def meaning_preserved(example, pred, trace=None):
    translated = pred.result.translated_text if hasattr(pred, "result") else pred.translated_text
    result = judge(
        source_text=example.source_text,
        translated_text=translated,
        target_language=example.target_language
    )
    return result.score >= 0.8

Combined metric and optimization

def translation_metric(example, pred, trace=None):
    return (
        glossary_compliance(example, pred) and
        meaning_preserved(example, pred)
    )

trainset = [
    dspy.Example(
        source_text="Upgrade your plan today.",
        target_language="German",
        glossary=["Pro", "Dashboard"]
    ).with_inputs("source_text", "target_language", "glossary"),
    # add more examples...
]

optimizer = dspy.MIPROv2(metric=translation_metric)
optimized_translator = optimizer.compile(
    dspy.Predict(TranslateWithGlossary),
    trainset=trainset
)

When NOT to use AI translation

DSPy shines when you need glossary enforcement, tone control, quality estimation, or want to optimize translation prompts against a metric.

Key patterns

Gotchas

Claude translates glossary terms instead of keeping them as-is. Name the field glossary and state in the docstring "do not translate these terms — they must appear verbatim." Listing them inline in the docstring also helps. If terms still get translated, switch to dspy.ChainOfThought so the model reasons about each term explicitly.

Claude outputs the source language when target languages are closely related. For pairs like en → pt-PT or es-ES → es-MX, Claude sometimes returns the source text unchanged or barely modified. Always use the full locale label ("Portuguese (Portugal)", "Spanish (Mexico)") rather than a BCP-47 tag alone.

Claude uses `dspy.Assert`/`dspy.Suggest` for glossary enforcement — use `dspy.Refine` instead. Assert/Suggest are deprecated in DSPy 3.x. Use dspy.Refine with a reward function that checks glossary term presence. See /dspy-refine for the pattern.

Claude generates overly formal translations for casual UI copy. Pass tone as an explicit input field with a value like "casual". Do not rely on the model to infer register from the locale. French and German LM outputs default to formal register unless explicitly instructed otherwise.

Claude batch-translates by concatenating all strings into a single LM call. This causes glossary drift, misattributed translations, and subtle meaning errors across long batches. Translate each string individually or in small batches of 3-5 closely related strings (e.g., a dialog's button labels together).

Cross-references

Install any skill: npx skills add lebsral/DSPy-Programming-not-prompting-LMs-skills --skill <name>

• /dspy-refine - retry low-confidence segments or failed glossary enforcement with a reward function
• /dspy-best-of-n - sample N translations and select the best by glossary compliance + fluency score
• /ai-improving-accuracy - optimize translation prompts with MIPROv2 against a labeled dataset
• /ai-checking-outputs - validate translated output structure, glossary compliance, and format
• /ai-generating-data - generate synthetic parallel sentences to build a translation training set

• Install `/ai-do` if you do not have it — it routes any AI problem to the right skill and is the fastest way to work: npx skills add lebsral/DSPy-Programming-not-prompting-LMs-skills --skill ai-do

Additional resources

See examples.md for worked examples:

• Marketing copy translator (English to Spanish with brand glossary)
• i18n JSON batch translator
• Support ticket translator with confidence scoring

ai-translating-content - Examples

Example 1 - Marketing copy translator (English to Spanish with brand glossary)

Translate landing page and product copy from English to Spanish (Mexico) while preserving brand terms like product names and feature labels.

Setup

import dspy
from pydantic import BaseModel
from typing import list

lm = dspy.LM("openai/gpt-4o-mini")  # or "anthropic/claude-sonnet-4-5-20250929", etc.
dspy.configure(lm=lm)

Signatures and module

class MarketingTranslationResult(BaseModel):
    translated_text: str
    glossary_terms_used: list[str]

class TranslateMarketing(dspy.Signature):
    """Translate English marketing copy to the target_language with the given tone.
    Terms in glossary must appear verbatim in the output — do not translate them."""
    source_text: str = dspy.InputField(desc="English marketing copy")
    target_language: str = dspy.InputField()
    tone: str = dspy.InputField(desc="casual, neutral, or formal")
    glossary: list[str] = dspy.InputField(
        desc="Brand terms, product names, and feature labels that must NOT be translated"
    )
    result: MarketingTranslationResult = dspy.OutputField()

translator = dspy.Predict(TranslateMarketing)

Usage

copy_strings = [
    "Get started with Acme Pro for free — no credit card required.",
    "Organize your work in Workspaces. Share with your team in seconds.",
    "The Dashboard gives you a real-time view of every project.",
]

glossary = ["Acme Pro", "Workspaces", "Dashboard"]

for text in copy_strings:
    result = translator(
        source_text=text,
        target_language="Spanish (Mexico)",
        tone="casual",
        glossary=glossary
    )
    print(f"EN: {text}")
    print(f"ES: {result.result.translated_text}")
    print(f"Terms preserved: {result.result.glossary_terms_used}")
    print()

Expected output:

EN: Get started with Acme Pro for free — no credit card required.
ES: Comienza con Acme Pro gratis, sin necesidad de tarjeta de crédito.
Terms preserved: ["Acme Pro"]

EN: Organize your work in Workspaces. Share with your team in seconds.
ES: Organiza tu trabajo en Workspaces. Comparte con tu equipo en segundos.
Terms preserved: ["Workspaces"]

EN: The Dashboard gives you a real-time view of every project.
ES: El Dashboard te da una vista en tiempo real de cada proyecto.
Terms preserved: ["Dashboard"]

Metric

def glossary_compliance_metric(example, pred, trace=None):
    glossary = example.glossary
    translated = pred.result.translated_text
    violations = [term for term in glossary if term not in translated]
    if violations:
        print(f"Glossary violations: {violations}")
    return len(violations) == 0

---

Example 2 - i18n JSON batch translator

Translate a full en.json locale file to multiple target locales, preserving interpolation placeholders like {count} and {name}.

Setup

import dspy
import json
from pathlib import Path

lm = dspy.LM("openai/gpt-4o-mini")  # or "anthropic/claude-sonnet-4-5-20250929", etc.
dspy.configure(lm=lm)

Signatures and module

class TranslateI18nString(dspy.Signature):
    """Translate a single i18n string into target_language.
    Preserve interpolation placeholders exactly as written (e.g., {count}, {name}, %s).
    Glossary terms must appear verbatim."""
    source_text: str = dspy.InputField(desc="Single i18n string, may contain {placeholders}")
    target_language: str = dspy.InputField()
    glossary: list[str] = dspy.InputField(default=[])
    translated_text: str = dspy.OutputField()

translator = dspy.Predict(TranslateI18nString)

def translate_locale_file(
    source_path: str,
    output_path: str,
    target_language: str,
    glossary: list[str] = None
):
    glossary = glossary or []
    with open(source_path) as f:
        strings = json.load(f)

    translated = {}
    for key, text in strings.items():
        result = translator(
            source_text=text,
            target_language=target_language,
            glossary=glossary
        )
        translated[key] = result.translated_text

    Path(output_path).parent.mkdir(parents=True, exist_ok=True)
    with open(output_path, "w") as f:
        json.dump(translated, f, ensure_ascii=False, indent=2)

    print(f"Translated {len(translated)} strings to {output_path}")
    return translated

Usage

Given locales/en.json:

{
  "welcome": "Welcome back, {name}!",
  "items_count": "You have {count} items in your cart.",
  "sign_out": "Sign out",
  "upgrade_cta": "Upgrade to Acme Pro",
  "empty_state": "No results found. Try a different search."
}

glossary = ["Acme Pro"]

# Translate to German
translate_locale_file(
    source_path="locales/en.json",
    output_path="locales/de.json",
    target_language="German (formal)",
    glossary=glossary
)

# Translate to Japanese
translate_locale_file(
    source_path="locales/en.json",
    output_path="locales/ja.json",
    target_language="Japanese",
    glossary=glossary
)

Expected locales/de.json:

{
  "welcome": "Willkommen zurück, {name}!",
  "items_count": "Sie haben {count} Artikel in Ihrem Warenkorb.",
  "sign_out": "Abmelden",
  "upgrade_cta": "Upgrade auf Acme Pro",
  "empty_state": "Keine Ergebnisse gefunden. Versuchen Sie eine andere Suche."
}

Metric

import re

def placeholder_preservation_metric(example, pred, trace=None):
    source = example.source_text
    translated = pred.translated_text
    # Extract all {placeholder} patterns from source
    placeholders = re.findall(r'\{[^}]+\}', source)
    missing = [p for p in placeholders if p not in translated]
    if missing:
        print(f"Missing placeholders: {missing}")
    return len(missing) == 0

---

Example 3 - Support ticket translator with confidence scoring

Translate inbound support tickets from any language to English for your support team, flagging idiom-heavy or ambiguous messages for human review.

Setup

import dspy
from pydantic import BaseModel

lm = dspy.LM("openai/gpt-4o-mini")  # or "anthropic/claude-sonnet-4-5-20250929", etc.
dspy.configure(lm=lm)

Signatures and module

class SupportTranslationResult(BaseModel):
    translated_text: str
    detected_source_language: str
    confidence: float  # 0.0–1.0
    needs_review: bool
    review_reason: str  # empty string if needs_review is False

class TranslateSupportTicket(dspy.Signature):
    """Translate a support ticket into English. Auto-detect the source language.
    Estimate confidence: 1.0 = clear and literal, <0.7 = idioms, sarcasm, or ambiguous phrasing.
    Flag needs_review=True if confidence < 0.75 or if intent is ambiguous."""
    ticket_text: str = dspy.InputField(desc="Raw support ticket text in any language")
    result: SupportTranslationResult = dspy.OutputField()

translator = dspy.ChainOfThought(TranslateSupportTicket)

def process_ticket(ticket_text: str) -> dict:
    result = translator(ticket_text=ticket_text)
    r = result.result
    return {
        "original": ticket_text,
        "translation": r.translated_text,
        "source_language": r.detected_source_language,
        "confidence": r.confidence,
        "needs_review": r.needs_review,
        "review_reason": r.review_reason
    }

Usage

tickets = [
    "Bonjour, mon abonnement a été débité deux fois ce mois-ci. Pouvez-vous corriger cela?",
    "Das ist ja wohl ein Witz! Die App funktioniert überhaupt nicht mehr.",  # sarcasm
    "我无法登录我的账户，密码重置邮件也没有收到。",
    "Ayer todo funcionaba y hoy nada. No sé qué pasó.",
]

for ticket in tickets:
    result = process_ticket(ticket)
    print(f"[{result['source_language']}] Confidence: {result['confidence']:.2f}")
    print(f"Translation: {result['translation']}")
    if result['needs_review']:
        print(f"REVIEW NEEDED: {result['review_reason']}")
    print()

Expected output:

[French] Confidence: 0.97
Translation: Hello, my subscription was charged twice this month. Can you correct this?

[German] Confidence: 0.65
Translation: Are you serious? The app is completely broken.
REVIEW NEEDED: Sarcastic tone detected — "Das ist ja wohl ein Witz" is an idiom expressing frustration, not a literal question.

[Chinese (Simplified)] Confidence: 0.95
Translation: I cannot log in to my account and I have not received the password reset email.

[Spanish] Confidence: 0.82
Translation: Yesterday everything was working and today nothing is. I do not know what happened.

Metric

def translation_quality_metric(example, pred, trace=None):
    r = pred.result
    # Check that high-confidence translations do not get flagged as needing review
    if r.confidence >= 0.85 and r.needs_review:
        return False
    # Check that very low-confidence translations are always flagged
    if r.confidence < 0.6 and not r.needs_review:
        return False
    # Basic sanity - translated text must be non-empty
    return bool(r.translated_text.strip())