A voz da marca define como seu produto se comunica — tom, formalidade e estilo — com um texto por idioma de destino. Ela pertence à organização: é um contêiner nomeado que traz uma variação para cada idioma que abrange e é aplicada a uma engine de localização por anexo.
Uma voz, vários idiomas
Antes, a voz da marca era o texto de um único idioma, vinculado a uma engine. Agora, ela é uma única voz que reúne um texto por idioma. Engines que tinham uma voz por idioma foram consolidadas em uma única voz com uma variação por idioma — cada idioma e cada texto continuam exatamente onde estavam.
Como funciona#
| Objeto | Campos |
|---|---|
| Voz da marca | Nome, descrição. Contém um texto por idioma de destino. |
| Variação | Idioma de destino (ou *), texto da voz. |
Quando a engine processa uma solicitação para um idioma de destino, ela encontra a variação única com a melhor correspondência entre todas as vozes anexadas e inclui esse texto no prompt da LLM — influenciando a escolha de palavras, a estrutura das frases e o registro.
Exatamente um texto de voz da marca se aplica a cada solicitação. Regras e termos do glossário se combinam; vozes da marca, não.
| Campo | Descrição |
|---|---|
| Idioma de destino | O idioma ao qual este texto se aplica (por exemplo, de, fr-CA, ja) ou * para qualquer idioma |
| Texto da voz | Instruções livres que descrevem tom, formalidade e estilo para esse idioma |
Uma voz por idioma em cada engine#
Uma engine lê uma voz da marca por idioma, e três proteções garantem que continue assim:
| Tentativa | Resultado |
|---|---|
Anexar duas vozes que tenham texto para de | Recusado (400), informando os idiomas em sobreposição |
Adicionar um texto de a uma voz enquanto outra voz na mesma engine já cobre de | Recusado (409) |
Adicionar um segundo texto de à mesma voz | Recusado (409) - uma voz tem um texto por idioma |
Uma variação * é o padrão para todo idioma que não tenha um texto próprio. Um texto específico de idioma sempre tem prioridade sobre ela, e a resolução regional continua valendo normalmente: um texto de-DE atende a uma solicitação genérica de. Consulte Resolução de idioma.
As vozes da marca pertencem à organização#
| Ação | Efeito |
|---|---|
| Criar uma voz da marca | Ela existe no nível da organização e não se aplica a nada até ser anexada |
| Anexá-la a uma engine | Cada uma de suas variações se aplica aos idiomas correspondentes dessa engine |
| Anexá-la a várias engines | A mesma voz orienta todas elas — edite uma vez, e toda engine acompanha |
| Anexar várias vozes a uma engine | Permitido, desde que nenhuma delas cubra o mesmo idioma |
| Desanexá-la de uma engine | A engine deixa de aplicá-la. A voz e suas variações são mantidas. |
| Excluir uma voz da marca | Recusado enquanto alguma engine ainda a aplicar — desanexe primeiro. Ao excluir, suas variações vão junto. |
| Excluir uma engine | As vozes da marca continuam existindo. Elas pertencem à organização, não à engine. |
Gerencie as vozes em Brand voices na barra lateral da organização — a lista mostra quantos idiomas cada voz cobre e quantas engines a aplicam, e a página de detalhes de cada voz lista seus textos por idioma. A aba Brand Voice de uma engine mostra uma linha por idioma e desanexa vozes inteiras.
Como escrever um texto de voz da marca#
O texto da voz é escrito em linguagem natural e em formato livre. Escreva como se estivesse orientando uma pessoa tradutora que nunca trabalhou com seu produto.
Uma voz da marca eficaz inclui:
- Nível de formalidade — "Sie" formal vs. "du" informal em alemão, "vous" vs. "tu" em francês
- Tom — profissional, conversacional, descontraído, técnico
- Público — desenvolvedores, compradores corporativos, consumidores, equipes internas
- Convenções — como lidar com números, datas, moeda ou terminologia específica do produto
Exemplo#
Para um idioma alemão voltado a desenvolvedores:
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).Mantenha o nome e a descrição do contêiner para pessoas — eles identificam a voz na lista da organização e explicam para que ela serve. Só o texto da variação chega ao modelo.
Como usar a voz da marca com a API#
As vozes da marca são aplicadas automaticamente quando você chama o endpoint localize. A engine compara o targetLocale da solicitação com as variações de cada voz anexada e inclui a melhor correspondência no prompt. Nenhum parâmetro adicional é necessário.
{
"sourceLocale": "en",
"targetLocale": "de",
"data": {
"greeting": "Hey there! Ready to ship?",
"cta": "Get started"
}
}Com o texto em alemão acima, a engine produz traduções informais e com foco técnico, em vez de uma saída formal genérica.
| Chamada | Finalidade |
|---|---|
POST /brand-voices | Criar uma voz para a organização |
GET /organizations/:id/brand-voices | Listar as vozes da organização com contagens de idiomas e engines |
GET /brand-voices/:id/variations | Listar os textos de uma voz por idioma |
POST /brand-voice-variations com brandVoiceId | Adicionar um texto para um idioma |
PUT /brand-voice-variations/:id | Alterar um texto ou movê-lo para outro idioma |
PUT /engines/:id/brand-voices | Substituir o conjunto de vozes que uma engine aplica |
DELETE /engines/:id/brand-voices/:brandVoiceId | Parar de aplicar uma voz a uma engine |
GET /engines/:id/brand-voice-variations | Listar todos os textos por idioma que uma engine aplica no momento |
POST /brand-voices ainda aceita targetLocale e text juntos e inicializa a primeira variação da voz, e ownerEngineId ainda adiciona à voz uma engine à qual ela já se aplica — criando uma e aplicando-a se ainda não houver nenhuma.
Acesso#
org:brandvoice:read e org:brandvoice:edit controlam vozes e suas variações; anexar uma delas a uma engine também exige engine:edit nessa engine. Uma permissão por voz dá a alguém acesso de leitura e edição a uma única voz, em vez de a todas as vozes da organização. Consulte Roles & Permissions.
Como gerenciar vozes da marca via MCP#
Se você usa o Lingo.dev MCP server, seu assistente de programação com IA pode criar e atualizar vozes da marca diretamente pela conversa:
"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."