A brand voice defines how your product speaks - tone, formality, and style - with one text per target locale. It is organization-owned: a named container that carries a variation for each locale it covers, applied to a localization engine by attachment.
One voice, many locales
A brand voice used to be a single locale's text, owned by one engine. It is now one voice holding a text per locale. Engines that carried a voice per locale were collapsed into a single voice with a variation per locale - every locale and every text is exactly where it was.
How it works#
| Object | Fields |
|---|---|
| Brand voice | Name, description. Holds one text per target locale. |
| Variation | Target locale (or *), voice text. |
When the engine processes a request for a target locale, it resolves the single best-matching variation across every attached voice and includes that text in the LLM prompt - shaping word choice, sentence structure, and register.
Exactly one brand voice text applies per request. Rules and glossary terms combine; brand voices don't.
| Field | Description |
|---|---|
| Target locale | The locale this text applies to (e.g., de, fr-CA, ja), or * for any locale |
| Voice text | Free-form instructions describing tone, formality, and style for that locale |
One voice per locale per engine#
An engine reads one brand voice for a locale, and three guards keep it that way:
| Attempt | Result |
|---|---|
Attach two voices that both carry a text for de | Refused (400), naming the locales that overlap |
Add a de text to a voice while another voice on the same engine already covers de | Refused (409) |
Add a second de text to the same voice | Refused (409) - a voice holds one text per locale |
A * variation is the default for every locale that has no text of its own. A locale-specific text always outranks it, and regional resolution applies as usual: a de-DE text answers a bare de request. See Locale Resolution.
Brand voices are organization-owned#
| Action | Effect |
|---|---|
| Create a brand voice | It exists at organization level and applies to nothing until attached |
| Attach it to an engine | Each of its variations applies to that engine's matching locales |
| Attach it to several engines | The same voice governs all of them - edit once, every engine follows |
| Attach several voices to one engine | Allowed as long as no two of them cover the same locale |
| Detach it from an engine | The engine stops applying it. The voice and its variations are kept. |
| Delete a brand voice | Refused while any engine still applies it - detach first. Deleting takes its variations with it. |
| Delete an engine | Brand voices survive. They belong to the organization, not the engine. |
Manage voices under Brand voices in the organization sidebar - the list shows how many locales each voice covers and how many engines apply it, and each voice's detail page lists its per-locale texts. An engine's Brand Voice tab shows one row per locale and detaches whole voices.
Writing a brand voice text#
Voice text is free-form natural language. Write it as if briefing a translator who has never worked with your product.
Effective brand voices include:
- Formality level - formal "Sie" vs. informal "du" in German, "vous" vs. "tu" in French
- Tone - professional, conversational, playful, technical
- Audience - developers, enterprise buyers, consumers, internal teams
- Conventions - how to handle numbers, dates, currency, or product-specific terminology
Example#
For a German locale targeting a developer audience:
Use informal "du" address. Keep a direct, technical tone - similar
to how Stripe or Vercel write their German documentation. Prefer
short sentences. Use active voice. When a German equivalent exists
for a technical term, use it (e.g., "Bereitstellung" for deployment),
but keep widely-adopted English terms as-is (e.g., API, CLI, Token).Keep the container's name and description for humans - they identify the voice in the organization list and say what it is for. Only the variation text reaches the model.
Using brand voices with the API#
Brand voices are applied automatically when you call the localize endpoint. The engine matches the request's targetLocale against the variations of every attached voice and includes the best match in the prompt. No additional parameters are needed.
{
"sourceLocale": "en",
"targetLocale": "de",
"data": {
"greeting": "Hey there! Ready to ship?",
"cta": "Get started"
}
}With the German text above, the engine produces informal, technically-oriented translations rather than generic formal output.
| Call | Purpose |
|---|---|
POST /brand-voices | Create a voice for the organization |
GET /organizations/:id/brand-voices | List the organization's voices with locale and engine counts |
GET /brand-voices/:id/variations | List a voice's per-locale texts |
POST /brand-voice-variations with brandVoiceId | Add a text for one locale |
PUT /brand-voice-variations/:id | Change a text or move it to another locale |
PUT /engines/:id/brand-voices | Replace the set of voices an engine applies |
DELETE /engines/:id/brand-voices/:brandVoiceId | Stop applying one voice to an engine |
GET /engines/:id/brand-voice-variations | List every locale text an engine currently applies |
POST /brand-voices still accepts targetLocale and text together and seeds the voice's first variation, and ownerEngineId still adds to the voice an engine already applies - creating and applying one if it has none.
Access#
org:brandvoice:read and org:brandvoice:edit govern voices and their variations; attaching one to an engine also needs engine:edit on that engine. A per-voice grant gives someone read and edit on a single voice instead of every voice in the organization. See Roles & Permissions.
Managing brand voices via MCP#
If you use the Lingo.dev MCP server, your AI coding assistant can create and update brand voices directly from the conversation:
"Create a brand voice called Product voice and apply it to the
docs engine.""Set its German text to informal du, technical tone, short
sentences, active voice."