Instructions#
Instructions are named linguistic rules that tell the localization engine how to handle specific translation patterns for a target locale. Unlike a brand voice, which sets the overall tone, instructions encode discrete, testable rules — each addressing one linguistic concern.
How it works#
Each instruction belongs to a localization engine and targets a specific locale (or all locales via the * wildcard). When the engine processes a translation request, it collects all instructions matching the target locale and includes them in the LLM prompt alongside the brand voice and glossary.
| Field | Description |
|---|---|
| Name | A short label identifying the rule (e.g., "German formal address") |
| Target locale | The locale this instruction applies to, or * for all locales |
| Text | The linguistic rule, written in natural language |
Multiple instructions per locale
You can create as many instructions as needed for each locale. Each instruction should address one specific rule — this makes them easier to test, update, and debug independently.
Instructions vs. brand voices#
Both shape translation output, but at different levels:
| Brand Voice | Instruction | |
|---|---|---|
| Scope | Overall tone, style, formality | One specific linguistic rule |
| Per locale | One per locale | Many per locale |
| Wildcard | No | Yes (* applies to all locales) |
| Example | "Use informal du, technical tone" | "Always abbreviate Straße to Str. in addresses" |
Use a brand voice to define how your product speaks in a language — formality, register, sentence style.
Use instructions to encode specific rules the model would otherwise miss — abbreviation conventions, punctuation preferences, unit formatting, or locale-specific grammar patterns.
They work together: the brand voice sets the voice, instructions handle the edge cases.
Writing effective instructions#
Each instruction should be a single, unambiguous rule. The engine includes the full text in the LLM prompt, so clarity matters.
Good instructions#
Always use the Oxford comma in English lists.In Japanese, use full-width parentheses （）instead of half-width ().For German addresses, abbreviate "Straße" to "Str." and
"Nummer" to "Nr."When translating percentage values for French, add a
non-breaking space before the percent sign: 42 %.What to avoid#
- Vague guidance that overlaps with the brand voice ("be more casual") — put that in the brand voice instead
- Multiple unrelated rules in one instruction — split them so each can be tested independently
- Rules that contradict the glossary — glossary terms take precedence in the engine's rule hierarchy
Wildcard locale#
Set the target locale to * to apply an instruction across all locales. This is useful for rules that are language-independent:
Never translate product feature names: "Smart Compose",
"Quick Actions", "Flow Builder".Preserve Markdown formatting in all translated strings.
Keep bold (**), italic (*), and link syntax [text](url) intact.Locale-specific instructions and wildcard instructions are both included when the engine processes a request — they combine, not override.
Using instructions with the API#
Instructions are applied automatically when you call the localize endpoint. The engine collects all instructions matching the request's targetLocale (plus any * wildcard instructions) and includes them in the prompt.
No additional parameters are needed in the API request.
Managing instructions via MCP#
If you use the Lingo.dev MCP server, your AI coding assistant can create, update, and delete instructions directly:
"Add an instruction for German: always abbreviate Straße
to Str. in addresses.""Add a wildcard instruction: never translate the term
Smart Compose."