Uma voz da marca define a forma como o seu produto comunica — tom, formalidade e estilo — com um texto por idioma de destino. Pertence à organização: é um contentor com nome que inclui uma variação para cada idioma que abrange, aplicada a um motor de localização através de associação.
Uma voz, muitos idiomas
Antes, uma voz da marca era o texto de um único idioma, pertencente a um único motor. Agora, é uma única voz com um texto por idioma. Os motores que tinham uma voz por idioma foram consolidados numa ú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 o motor processa um pedido para um idioma de destino, encontra a única variação com a melhor correspondência entre todas as vozes associadas e inclui esse texto no prompt do LLM — moldando a escolha de palavras, a estrutura das frases e o registo.
Aplica-se exatamente um texto de voz da marca por pedido. As regras e os termos do glossário combinam-se; as vozes da marca não.
| Campo | Descrição |
|---|---|
| Idioma de destino | O idioma a que este texto se aplica (por exemplo, de, fr-CA, ja) ou * para qualquer idioma |
| Texto da voz | Instruções em formato livre que descrevem o tom, a formalidade e o estilo para esse idioma |
Uma voz por idioma por motor#
Um motor lê uma voz da marca por idioma, e há três salvaguardas para garantir que assim é:
| Tentativa | Resultado |
|---|---|
Associar duas vozes que incluam ambas um texto para de | Recusado (400), indicando os idiomas sobrepostos |
Adicionar um texto de a uma voz, quando outra voz no mesmo motor já cobre de | Recusado (409) |
Adicionar um segundo texto de à mesma voz | Recusado (409) - uma voz tem um texto por idioma |
Uma variação * é a predefinição para todos os idiomas que não têm texto próprio. Um texto específico de um idioma tem sempre prioridade sobre ela, e a resolução regional aplica-se como habitualmente: um texto de-DE responde a um pedido genérico de. Consulte Locale Resolution.
As vozes da marca pertencem à organização#
| Ação | Efeito |
|---|---|
| Criar uma voz da marca | Existe ao nível da organização e não se aplica a nada até ser associada |
| Associá-la a um motor | Cada uma das suas variações aplica-se aos idiomas correspondentes desse motor |
| Associá-la a vários motores | A mesma voz governa todos eles - edite uma vez, todos os motores acompanham a alteração |
| Associar várias vozes a um motor | Permitido, desde que nenhuma cubra o mesmo idioma |
| Desassociá-la de um motor | O motor deixa de a aplicar. A voz e as suas variações são mantidas. |
| Eliminar uma voz da marca | Recusado enquanto algum motor ainda a aplicar - desassocie-a primeiro. Ao eliminá-la, as suas variações são eliminadas também. |
| Eliminar um motor | As vozes da marca mantêm-se. Pertencem à organização, não ao motor. |
Faça a gestão das vozes em Brand voices na barra lateral da organização — a lista mostra quantos idiomas cada voz cobre e quantos motores a aplicam, e a página de detalhe de cada voz apresenta os respetivos textos por idioma. O separador Brand Voice de um motor mostra uma linha por idioma e permite desassociar vozes completas.
Escrever um texto de voz da marca#
O texto da voz é escrito em linguagem natural e em formato livre. Escreva-o como se estivesse a orientar um tradutor que nunca trabalhou com o seu produto.
As vozes da marca mais eficazes incluem:
- Nível de formalidade — formal "Sie" vs. informal "du" em alemão, "vous" vs. "tu" em francês
- Tom — profissional, conversacional, descontraído, técnico
- Público — programadores, compradores empresariais, consumidores, equipas internas
- Convenções — como tratar números, datas, moeda ou terminologia específica do produto
Exemplo#
Para um idioma alemão direcionado a um público de programadores:
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 contentor para as pessoas - identificam a voz na lista da organização e explicam para que serve. Só o texto da variação chega ao modelo.
Utilizar vozes da marca com a API#
As vozes da marca são aplicadas automaticamente quando chama o endpoint localize. O motor faz corresponder o targetLocale do pedido às variações de cada voz associada e inclui a melhor correspondência no prompt. Não são necessários parâmetros adicionais.
{
"sourceLocale": "en",
"targetLocale": "de",
"data": {
"greeting": "Hey there! Ready to ship?",
"cta": "Get started"
}
}Com o texto alemão acima, o motor produz traduções informais e de orientação técnica, em vez de um resultado formal genérico.
| 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 motores |
GET /brand-voices/:id/variations | Listar os textos por idioma de uma voz |
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 um motor aplica |
DELETE /engines/:id/brand-voices/:brandVoiceId | Deixar de aplicar uma voz a um motor |
GET /engines/:id/brand-voice-variations | Listar todos os textos por idioma que um motor aplica atualmente |
POST /brand-voices continua a aceitar targetLocale e text em conjunto e inicializa a primeira variação da voz, e ownerEngineId continua a adicionar à voz que um motor já aplica - criando e aplicando uma, caso ainda não exista nenhuma.
Acesso#
org:brandvoice:read e org:brandvoice:edit regem as vozes e as respetivas variações; associar uma a um motor também exige engine:edit nesse motor. 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.
Gerir vozes da marca através do MCP#
Se utilizar o servidor MCP da Lingo.dev, o seu assistente de programação com IA pode criar e atualizar vozes da marca diretamente a partir da 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."