Una voz de marca define cómo habla tu producto —tono, nivel de 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 adjuntarlo.
Una voz, muchos idiomas
Antes, una voz de marca era el texto de un único idioma, propiedad de un solo motor. Ahora es una sola voz con un texto por idioma. Los motores que tenían una voz por idioma se consolidaron en una única 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 la voz. |
Cuando el motor procesa una solicitud para un idioma de destino, resuelve la única variación que mejor encaja entre todas las voces adjuntas e incluye ese texto en el prompt del LLM, dando forma a la elección de palabras, la estructura de las frases 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 (p. ej., de, fr-CA, ja) o * para cualquier idioma |
| Texto de la voz | Instrucciones en formato libre que describen el tono, el nivel de formalidad y el estilo para ese idioma |
Una voz por idioma en cada motor#
Un motor lee una voz de marca por idioma, y tres salvaguardas garantizan que siga siendo así:
| Intento | Resultado |
|---|---|
Adjuntar dos voces que ambas incluyen un texto para de | Rechazado (400), indicando los idiomas que se solapan |
Añadir un texto de a una voz mientras otra voz del mismo motor ya cubre de | Rechazado (409) |
Añadir un segundo texto de a la misma voz | Rechazado (409): una voz contiene un texto por idioma |
Una variación * es la opción predeterminada para cualquier idioma que no tenga texto propio. Un texto específico de un idioma siempre tiene prioridad sobre ella, y la resolución regional se aplica como de costumbre: un texto de-DE responde a una solicitud genérica 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 todos ellos: editas una vez y todos los motores la siguen |
| Adjuntar varias voces a un motor | Permitido 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: desvincúlala primero. Al eliminarla, sus variaciones también se eliminan. |
| Eliminar un motor | Las voces de marca sobreviven. Pertenecen a la organización, no al motor. |
Gestiona las voces en Brand voices en la barra lateral de la organización: la lista muestra cuántos idiomas cubre cada voz y a cuántos motores se aplica, 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 redactar un texto de voz de marca#
El texto de voz es lenguaje natural en formato libre. Escríbelo como si dieras indicaciones a un traductor que nunca ha trabajado con tu producto.
Una voz de marca eficaz incluye:
- Nivel de formalidad: "Sie" frente a "du" en alemán, "vous" frente a "tu" en francés
- Tono: profesional, conversacional, desenfadado, técnico
- Público: desarrolladores, responsables de compra en empresas, consumidores, equipos internos
- Convenciones: cómo tratar números, fechas, monedas o terminología específica del producto
Ejemplo#
Para un idioma alemán dirigido a un público 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).Deja 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.
Uso de 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 en el prompt la coincidencia más adecuada. No hacen falta 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 orientadas a lo técnico, en lugar de una salida formal genérica.
| Llamada | Finalidad |
|---|---|
POST /brand-voices | Crear una voz para la organización |
GET /organizations/:id/brand-voices | Enumerar las voces de la organización con el recuento de idiomas y motores |
GET /brand-voices/:id/variations | Enumerar los textos por idioma de una voz |
POST /brand-voice-variations con brandVoiceId | Añadir un texto para un idioma |
PUT /brand-voice-variations/:id | Cambiar un texto o moverlo a otro idioma |
PUT /engines/:id/brand-voices | Sustituir 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 | Enumerar todos los textos de idioma que un motor aplica actualmente |
POST /brand-voices sigue aceptando targetLocale y text juntos, y crea la primera variación de la voz; y ownerEngineId sigue añadiendo a la voz un motor que ya aplica, creándola y aplicándola si aún no tiene ninguna.
Acceso#
org:brandvoice:read y org:brandvoice:edit controlan las voces y sus variaciones; adjuntar una a un motor también requiere engine:edit en ese motor. Un permiso por voz permite a alguien leer y editar una sola voz en lugar de todas las voces de la organización. Consulta Roles y permisos.
Gestionar voces de marca con MCP#
Si utilizas 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."