How to Build a Claude-Powered Translation App

Building a Claude-powered translation app comes down to three parts: a prompt that produces consistent, accurate translations, an API layer that handles requests reliably, and a frontend that streams results back to users without lag. Claude is well suited to translation because it handles idiom, tone, and context better than rule-based systems, and it can preserve formatting like markdown, HTML, or code comments inside the translated text.

This guide walks through the actual implementation: prompt structure, request handling, streaming, and how to expose it as a usable API endpoint rather than a one-off script.

Why Claude works well for translation

Traditional translation APIs (Google Translate, DeepL) are optimized for literal accuracy. Claude is better at:

• Context-aware translation — understanding that "bark" means something different in a dog story vs. a tree description.
• Tone preservation — keeping formal, casual, or technical register intact.
• Structured content — translating text inside JSON, markdown, or HTML without breaking the structure.
• Domain adaptation — you can instruct it to translate legal, medical, or marketing copy differently in the same prompt.

The tradeoff is latency and cost compared to dedicated translation APIs, so it's worth designing the app around short, focused requests rather than giant batch dumps.

Step 1: Design the translation prompt

The biggest mistake in Claude-powered translation apps is a vague prompt like "translate this to French." You get inconsistent results — sometimes Claude adds commentary, explains idioms, or changes formatting.

Lock down the output with an explicit system prompt:

System: You are a professional translator. Translate the user's text from {source_language} to {target_language}.
Rules:
- Output ONLY the translated text, no explanations or notes.
- Preserve all markdown, HTML tags, and line breaks exactly.
- Keep proper nouns, brand names, and code untranslated.
- Match the tone and formality of the original.

Then send the actual text as the user message. Keeping instructions in the system prompt and content in the user message makes it easy to swap languages and content independently.

Step 2: Send the request

Here's a minimal request using curl against a Claude-compatible endpoint:

curl https://api.subtoapi.app/v1/messages \
  -H "Authorization: Bearer $SUBTOAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4",
    "max_tokens": 1024,
    "system": "You are a professional translator. Translate from English to Spanish. Output ONLY the translated text, preserving formatting.",
    "messages": [
      {"role": "user", "content": "Your order has shipped and will arrive within 3-5 business days."}
    ]
  }'

The response contains the translated text in the content field, ready to display or store. If you're new to this request shape, the docs/quickstart and docs/messages pages cover the exact payload structure.

Step 3: Handle multiple languages dynamically

Real translation apps need to support many target languages from one code path. Build the request dynamically instead of hardcoding language pairs:

async function translate(text, sourceLang, targetLang) {
  const response = await fetch("https://api.subtoapi.app/v1/messages", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.SUBTOAPI_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      model: "claude-sonnet-4",
      max_tokens: 1024,
      system: `You are a professional translator. Translate from ${sourceLang} to ${targetLang}. Output ONLY the translated text, preserving formatting and tone.`,
      messages: [{ role: "user", content: text }]
    })
  });

  const data = await response.json();
  return data.content[0].text;
}

This function becomes the core of your app — call it from a form submission, a chat interface, or a batch job that processes a CSV of strings.

Step 4: Stream output for a better UX

For longer documents, users don't want to stare at a blank screen waiting for the full translation. Streaming the response token by token makes the app feel instant, which matters a lot for translation UIs where users expect near-real-time feedback.

const response = await fetch("https://api.subtoapi.app/v1/messages", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SUBTOAPI_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "claude-sonnet-4",
    max_tokens: 2048,
    stream: true,
    system: "Translate from English to German. Output only the translation.",
    messages: [{ role: "user", content: longDocumentText }]
  })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();
let output = "";

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  output += decoder.decode(value);
  updateUI(output); // render partial translation as it arrives
}

Details on event formats and parsing are in docs/streaming.

Step 5: Handle formatting-heavy content

If your app translates UI strings, markdown docs, or app copy with placeholders (like {username} or %s), add explicit rules so Claude doesn't translate variable names:

Rules:
- Never translate text inside curly braces {} or percent placeholders %s, %d.
- Keep variable names exactly as written.

Test this with real production strings before shipping — placeholder handling is the most common failure point in Claude-powered localization pipelines.

Step 6: Add batch translation for scale

For apps translating many strings at once (e.g., localizing a product catalog), batch requests instead of looping one call per string. Combine strings into a single structured payload and ask Claude to return them in the same structure:

User: Translate each value in this JSON object to French. Return valid JSON with the same keys.
{"welcome": "Welcome back", "logout": "Log out", "settings": "Settings"}

This cuts latency and cost dramatically compared to individual requests, and keeps key-value pairing intact for direct use in your i18n files.

Step 7: Deploy it as a real API

Once the prompt and request logic work, wrap them behind your own endpoint so frontend and mobile clients don't need direct model access or shared secrets. If you're using SubToAPI, you get this structure already — application-specific keys (sub_live_...), usage metadata per request, and team seats if multiple people are building against the same translation service. Check pricing for plan details, or signup to get a key and start testing the examples above.

Questions

Does Claude translate better than Google Translate or DeepL? For context-heavy or domain-specific text (marketing, support tickets, documentation) Claude often produces more natural results. For plain short-string translation at massive scale, dedicated translation APIs may still be cheaper and faster.

How do I keep translations consistent across requests? Lock the system prompt wording, specify tone and formality rules explicitly, and avoid letting temperature vary between requests. Using the same prompt template for every call is the single biggest factor in consistency.

Can I translate HTML or markdown without breaking the structure? Yes — explicitly instruct Claude to preserve tags and formatting exactly, and test with real content samples. This works reliably for markdown and HTML as long as the instruction is unambiguous in the system prompt.