Una voz de marca define cómo habla tu producto —tono, formalidad y estilo— con un texto por cada idioma de destino. Pertenece a la organización: es un contenedor con nombre que incluye una variación para cada idioma que cubre y se aplica a un motor de localización al adjuntarse.
Una voz, muchos idiomas
Antes, una voz de marca era el texto de un solo idioma y pertenecía a un solo motor. Ahora es una sola voz que contiene un texto por idioma. Los motores que tenían una voz por idioma se consolidaron en una sola voz con una variación por idioma: cada idioma y cada texto siguen exactamente donde estaban.
Cómo funciona#
| Objeto | Campos |
|---|---|
| Voz de marca | Nombre, descripción. Contiene un texto por idioma de destino. |
| Variación | Idioma de destino (o *), texto de voz. |
Cuando el motor procesa una solicitud para un idioma de destino, resuelve la única variación con la mejor coincidencia entre todas las voces adjuntas e incluye ese texto en el prompt del LLM, lo que moldea la elección de palabras, la estructura de las oraciones y el registro.
Se aplica exactamente un texto de voz de marca por solicitud. Las reglas y los términos del glosario se combinan; las voces de marca, no.
| Campo | Descripción |
|---|---|
| Idioma de destino | El idioma al que se aplica este texto (por ejemplo, de, fr-CA, ja) o * para cualquier idioma |
| Texto de la voz | Instrucciones en formato libre que describen el tono, la formalidad y el estilo para ese idioma |
Una voz por idioma por motor#
Un motor lee una voz de marca por idioma, y hay tres controles que garantizan que siga siendo así:
| Intento | Resultado |
|---|---|
Adjuntar dos voces que ambas incluyen un texto para de | Rechazado (400), indicando los idiomas que se superponen |
Agregar un texto de de a una voz mientras otra voz en el mismo motor ya cubre de | Rechazado (409) |
Agregar un segundo texto de de a la misma voz | Rechazado (409): una voz incluye un texto por idioma |
Una variación * es la opción predeterminada para cualquier idioma que no tenga su propio texto. Un texto específico para un idioma siempre tiene prioridad sobre ella, y la resolución regional se aplica como siempre: un texto de-DE responde a una solicitud genérica de de. Consulta Resolución de idiomas.
Las voces de marca pertenecen a la organización#
| Acción | Efecto |
|---|---|
| Crear una voz de marca | Existe a nivel de organización y no se aplica a nada hasta que se adjunta |
| Adjuntarla a un motor | Cada una de sus variaciones se aplica a los idiomas coincidentes de ese motor |
| Adjuntarla a varios motores | La misma voz rige en todos: editas una vez y cada motor la sigue |
| Adjuntar varias voces a un motor | Se permite siempre que no haya dos que cubran el mismo idioma |
| Desvincularla de un motor | El motor deja de aplicarla. La voz y sus variaciones se conservan. |
| Eliminar una voz de marca | Rechazado mientras algún motor siga aplicándola: primero desvincúlala. Al eliminarla, sus variaciones también se eliminan. |
| Eliminar un motor | Las voces de marca permanecen. Pertenecen a la organización, no al motor. |
Administra las voces en Brand voices en la barra lateral de la organización: la lista muestra cuántos idiomas cubre cada voz y cuántos motores la aplican, y la página de detalle de cada voz enumera sus textos por idioma. La pestaña Brand Voice de un motor muestra una fila por idioma y permite desvincular voces completas.
Cómo escribir un texto de voz de marca#
El texto de voz se escribe en lenguaje natural y en formato libre. Escríbelo como si estuvieras dándole contexto a una persona traductora que nunca ha trabajado con tu producto.
Una voz de marca efectiva incluye:
- Nivel de formalidad: "Sie" formal vs. "du" informal en alemán, "vous" vs. "tu" en francés
- Tono: profesional, conversacional, cercano, técnico
- Audiencia: desarrolladores, compradores empresariales, consumidores, equipos internos
- Convenciones: cómo manejar números, fechas, moneda o terminología específica del producto
Ejemplo#
Para un idioma alemán dirigido a una audiencia de desarrolladores:
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).Reserva el nombre y la descripción del contenedor para las personas: identifican la voz en la lista de la organización y explican para qué sirve. Solo el texto de la variación llega al modelo.
Usar voces de marca con la API#
Las voces de marca se aplican automáticamente cuando llamas al endpoint localize endpoint. El motor compara el targetLocale de la solicitud con las variaciones de cada voz adjunta e incluye la mejor coincidencia en el prompt. No necesitas parámetros adicionales.
{
"sourceLocale": "en",
"targetLocale": "de",
"data": {
"greeting": "Hey there! Ready to ship?",
"cta": "Get started"
}
}Con el texto en alemán de arriba, el motor genera traducciones informales y con orientación técnica, en lugar de una salida formal genérica.
| Llamada | Propósito |
|---|---|
POST /brand-voices | Crear una voz para la organización |
GET /organizations/:id/brand-voices | Listar las voces de la organización con conteos de idiomas y motores |
GET /brand-voices/:id/variations | Listar los textos por idioma de una voz |
POST /brand-voice-variations con brandVoiceId | Agregar un texto para un idioma |
PUT /brand-voice-variations/:id | Cambiar un texto o moverlo a otro idioma |
PUT /engines/:id/brand-voices | Reemplazar el conjunto de voces que aplica un motor |
DELETE /engines/:id/brand-voices/:brandVoiceId | Dejar de aplicar una voz a un motor |
GET /engines/:id/brand-voice-variations | Listar cada texto por idioma que un motor aplica actualmente |
POST /brand-voices sigue aceptando targetLocale y text juntos e inicializa la primera variación de la voz, y ownerEngineId sigue agregando al motor una voz que ya aplica, creando y aplicando una si no tiene ninguna.
Acceso#
org:brandvoice:read y org:brandvoice:edit controlan las voces y sus variaciones; para adjuntar una a un motor también se requiere engine:edit en ese motor. Un permiso por voz le da a alguien acceso de lectura y edición sobre una sola voz, en lugar de sobre todas las voces de la organización. Consulta Roles y permisos.
Gestionar voces de marca con MCP#
Si usas el servidor MCP de Lingo.dev, tu asistente de programación con IA puede crear y actualizar voces de marca directamente desde la conversación:
"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."