500K characters included every month. Add payment details to start.
Home/Blog/Custom Instructions for Translation APIs: Tell the Model Exactly How to Translate
Product Update

Custom Instructions for Translation APIs: Tell the Model Exactly How to Translate

Most translation APIs give you zero control over the output. You send text, you get a translation, and you hope it fits your context. Langbly now lets you pass custom instructions with every request. Here is how it works and why it changes the way you handle translations.

Jasper de Winter· Founder, LangblyMarch 26, 20267 min read

Here is the problem with most translation APIs: you send text in, you get text out, and that is the end of the conversation. No way to tell the engine "use informal Dutch" or "keep brand names in English" or "this is a medical report, not a marketing email."

The result? Developers end up doing strange things. Post-processing translations with regex. Running separate prompts through GPT-4 to fix tone. Building lookup tables to swap back brand names that got translated. All because the translation API treats every request the same.

We just shipped a fix for this. Langbly now accepts three new optional parameters on every translate request: instructions, context, and glossary. They work with all existing SDKs (Python, JavaScript, PHP) and the REST API directly.

What are custom instructions?

Instructions tell the translation model how to translate your text. They are a plain-text string, up to 500 characters, that you send alongside your source text.

Some examples that work well:

  • "Use informal Dutch. Address the user with je/jij, not u."
  • "Do not translate product names or brand names."
  • "This is a legal contract. Use formal, precise language."
  • "Keep technical terms in English when there is no established translation."
  • "Write short, punchy sentences. This is for a mobile app UI."

The instructions get injected into the translation model's system prompt. They apply to all text segments in that request. You can change them per request, so different parts of your app can have different rules.

Instructions vs context vs glossary

Three new parameters, each doing something different. Here is when to use which.

Context

Context describes what the text is. It helps the model understand the domain and pick the right terminology without you spelling out every rule.

{
  "q": "Save changes",
  "target": "nl",
  "context": "settings page in a project management tool"
}

With that context, the model knows "Save" refers to storing data, not rescue. It knows "changes" means modifications, not coins. These seem obvious in English, but in many languages the disambiguation matters.

Instructions

Instructions describe how to translate. They are rules the model follows during translation.

{
  "q": "Welcome back! Your order is on its way.",
  "target": "de",
  "instructions": "Use informal German (du/dein). Keep the friendly, casual tone."
}

You can combine context and instructions in the same request. Context says "this is an e-commerce checkout email" and instructions say "use du, keep it casual." They work together.

Glossary

Glossary forces specific translations for specific terms. No ambiguity, no model judgment. If you say "Workspace" should become "Werkruimte" in Dutch, that is what you get.

{
  "q": "Create a new Workspace and invite your team.",
  "target": "nl",
  "glossary": [
    { "source": "Workspace", "target": "Werkruimte" },
    { "source": "team", "target": "team" }
  ]
}

Glossaries are useful for product terminology. Every SaaS product has words that should always translate the same way. Without a glossary, the model might translate "Workspace" differently in different contexts.

Real examples from production

We have been testing this with early users over the past weeks. Here are some patterns that came up repeatedly.

E-commerce product descriptions

A Shopify store selling handmade ceramics needed Dutch translations that felt personal and warm. Their previous setup with Google Translate produced technically correct but sterile output.

from langbly import Langbly

client = Langbly(api_key="your-key")

result = client.translate(
    "Each piece is hand-thrown on the wheel and glazed with our signature ash glaze.",
    target="nl",
    context="artisan ceramics e-commerce product page",
    instructions="Use informal Dutch. Write as if talking to a friend about craft. Avoid stiff, commercial language."
)

The difference is noticeable. Without instructions, you get a flat, literal translation. With them, the output matches the brand voice the store had spent months developing for their English copy.

SaaS UI strings with protected terms

A project management tool had a persistent problem: their product used "Board," "Sprint," and "Epic" as feature names, and translation APIs kept translating those into the target language. Every release, someone had to manually revert those translations.

import { Langbly } from 'langbly';

const client = new Langbly({ apiKey: 'your-key' });

const result = await client.translate(
  'Drag cards between columns on your Board to update their status.',
  {
    target: 'fr',
    instructions: 'Do not translate: Board, Sprint, Epic, Card. These are product feature names.',
    glossary: [
      { source: 'Board', target: 'Board' },
      { source: 'Sprint', target: 'Sprint' },
    ],
  }
);

The glossary handles the hard constraint (these words must stay English). The instructions give the model additional context about why, which helps it handle edge cases like plural forms or possessives correctly.

Legal content with formality requirements

A fintech company needed to translate their terms of service into German. German has a particularly sharp distinction between formal (Sie) and informal (du) address, and getting it wrong in a legal document is a real problem.

result = client.translate(
    terms_of_service_text,
    target="de",
    context="Terms of Service for a financial services application",
    instructions="Use formal German (Sie/Ihnen). Maintain legal precision. Do not simplify legal terminology."
)

Previously, they were paying a translation agency $0.12 per word for this. The API now handles the first draft at a fraction of that cost, and their legal team reviews the output instead of starting from scratch.

How to use it with the SDKs

All three SDKs (Python, JavaScript/TypeScript, PHP) support the new parameters. Here is a quick overview.

Python

from langbly import Langbly

client = Langbly(api_key="your-key")

result = client.translate(
    "Hello world",
    target="nl",
    context="developer documentation",
    instructions="Use informal Dutch",
    glossary=[{"source": "API", "target": "API"}]
)

print(result.text)

JavaScript / TypeScript

import { Langbly } from 'langbly';

const client = new Langbly({ apiKey: 'your-key' });

const result = await client.translate('Hello world', {
  target: 'nl',
  context: 'developer documentation',
  instructions: 'Use informal Dutch',
  glossary: [{ source: 'API', target: 'API' }],
});

console.log(result.text);

PHP

use Langbly\Client;

$client = new Client('your-key');

$result = $client->translate('Hello world', 'nl', null, null, [
    'context' => 'developer documentation',
    'instructions' => 'Use informal Dutch',
    'glossary' => [['source' => 'API', 'target' => 'API']],
]);

echo $result->translatedText;

REST API directly

curl -X POST https://api.langbly.com/language/translate/v2 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "Hello world",
    "target": "nl",
    "context": "developer documentation",
    "instructions": "Use informal Dutch",
    "glossary": [{"source": "API", "target": "API"}]
  }'

Backward compatibility

All three parameters are optional. If you do not send them, the API works exactly like before. If you are using Langbly as a drop-in replacement for Google Translate v2, nothing changes. Your existing code keeps working.

This is a deliberate design choice. We want migration from Google to be a URL-and-key swap. The new features are there when you need them, invisible when you do not.

Limits and pricing

A few practical details:

  • Instructions: max 500 characters per request
  • Context: max 500 characters per request
  • Glossary: max 200 term pairs per request
  • Billing: only the source text (q) counts toward your character quota. Instructions, context, and glossary terms are free.

That last point matters. Some competitors charge for every character that touches their API, including metadata. We only count what you actually translate.

What is next

Instructions are per-request right now. We are working on saved instruction sets that you can reference by ID, so you do not have to send the same instructions string with every call. Think of it as a translation profile: "use my e-commerce settings" instead of repeating the same 200-character instruction block.

Glossaries will also get a stored version. Upload your glossary once, reference it by ID, and it applies automatically. Useful when you have hundreds of terms and do not want to send them all with each request.

Both are on the roadmap for Q2 2026.

Try it

The new parameters are live on both api.langbly.com (global) and eu.langbly.com (EU-only). All SDK versions from Python 0.2.0, JavaScript 0.3.0, and PHP 1.0 support them.

If you are already a Langbly user, just update your SDK and start adding instructions to your requests. If you are new, the free tier gives you 500K characters per month to test with.

Full API documentation is at langbly.com/docs.

Translation APIInstructionsProduct UpdateDeveloper ToolsSDK

Try custom instructions yourself

Sign up for a Langbly account and start sending instructions with your translations. 500K characters/month included.

Back to all posts