브랜드 보이스는 제품이 어떤 말투로 말할지 정의합니다. 톤, 격식, 스타일을 포함하며, 대상 로캘마다 하나의 텍스트를 둡니다. 브랜드 보이스는 조직이 소유하는 이름 있는 컨테이너로, 지원하는 각 로캘별 variation을 담고 있고, 연결을 통해 로컬라이제이션 엔진에 적용됩니다.
하나의 보이스, 여러 로캘
예전의 브랜드 보이스는 하나의 엔진에 속한 단일 로캘용 텍스트였습니다. 이제는 로캘별 텍스트를 담는 하나의 보이스입니다. 로캘마다 보이스 하나를 갖고 있던 엔진은 이제 로캘별 variation을 담은 단일 보이스로 통합되었으며, 모든 로캘과 모든 텍스트는 기존 위치에 그대로 있습니다.
작동 방식#
| 객체 | 필드 |
|---|---|
| 브랜드 보이스 | 이름, 설명. 대상 로캘마다 텍스트 1개를 담습니다. |
| Variation | 대상 로캘(또는 *), 보이스 텍스트. |
엔진이 대상 로캘에 대한 요청을 처리할 때는 연결된 모든 보이스를 통틀어 가장 잘 맞는 variation 하나를 찾아 그 텍스트를 LLM 프롬프트에 포함합니다. 이 텍스트가 단어 선택, 문장 구조, 문체를 좌우합니다.
요청마다 적용되는 브랜드 보이스 텍스트는 정확히 하나뿐입니다. 규칙과 용어집 항목은 함께 적용되지만, 브랜드 보이스는 합쳐지지 않습니다.
| 필드 | 설명 |
|---|---|
| 대상 로캘 | 이 텍스트가 적용되는 로캘(예: de, fr-CA, ja) 또는 모든 로캘에 적용되는 * |
| 보이스 텍스트 | 해당 로캘의 톤, 격식, 스타일을 설명하는 자유 형식 지침 |
엔진마다 로캘별 보이스는 하나#
엔진은 각 로캘에 대해 브랜드 보이스 하나만 읽도록 되어 있으며, 이를 보장하는 세 가지 안전장치가 있습니다:
| 시도 | 결과 |
|---|---|
둘 다 de용 텍스트를 담고 있는 보이스 두 개를 연결 | 거부됨 (400), 겹치는 로캘을 함께 표시 |
같은 엔진의 다른 보이스가 이미 de를 다루고 있는 상태에서, 한 보이스에 de 텍스트 추가 | 거부됨 (409) |
같은 보이스에 두 번째 de 텍스트 추가 | 거부됨 (409) - 보이스는 로캘마다 텍스트를 하나만 담을 수 있습니다 |
* variation은 자체 텍스트가 없는 모든 로캘의 기본값입니다. 로캘별 텍스트가 있으면 항상 그쪽이 우선하며, 지역 해석도 평소처럼 적용됩니다. 즉, de-DE 텍스트는 로캘이 지정되지 않은 de 요청에 응답합니다. 자세한 내용은 로캘 해석을 참고하세요.
브랜드 보이스는 조직 소유입니다#
| 작업 | 효과 |
|---|---|
| 브랜드 보이스 만들기 | 조직 수준에 생성되며, 연결되기 전까지는 어디에도 적용되지 않습니다 |
| 엔진에 연결 | 각 variation이 해당 엔진의 일치하는 로캘에 적용됩니다 |
| 여러 엔진에 연결 | 같은 보이스가 모두에 적용됩니다 - 한 번 수정하면 모든 엔진에 반영됩니다 |
| 하나의 엔진에 여러 보이스 연결 | 서로 같은 로캘을 다루지만 않으면 허용됩니다 |
| 엔진에서 연결 해제 | 엔진은 더 이상 이를 적용하지 않습니다. 보이스와 그 variation은 유지됩니다. |
| 브랜드 보이스 삭제 | 아직 이를 적용 중인 엔진이 하나라도 있으면 거부됩니다 - 먼저 연결을 해제하세요. 삭제하면 해당 variation도 함께 삭제됩니다. |
| 엔진 삭제 | 브랜드 보이스는 그대로 남습니다. 엔진이 아니라 조직에 속하기 때문입니다. |
보이스는 조직 사이드바의 Brand voices에서 관리할 수 있습니다. 목록에는 각 보이스가 다루는 로캘 수와 이를 적용하는 엔진 수가 표시되고, 각 보이스의 상세 페이지에는 로캘별 텍스트가 나열됩니다. 엔진의 Brand Voice 탭에는 로캘별로 한 줄씩 표시되며, 보이스 단위로 전체 연결을 해제할 수 있습니다.
브랜드 보이스 텍스트 작성하기#
보이스 텍스트는 자유 형식의 자연어입니다. 제품을 한 번도 다뤄본 적 없는 번역가에게 브리핑하듯 작성하세요.
효과적인 브랜드 보이스에는 다음 요소가 포함됩니다:
- 격식 수준 - 독일어의 격식체 "Sie"와 비격식체 "du", 프랑스어의 "vous"와 "tu"
- 톤 - 전문적, 대화체, 유쾌한, 기술 중심
- 대상 독자 - 개발자, 엔터프라이즈 구매자, 소비자, 내부 팀
- 표기 규칙 - 숫자, 날짜, 통화, 제품별 용어를 어떻게 처리할지
예시#
개발자 대상 독일어 로캘의 예시는 다음과 같습니다:
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).컨테이너의 name과 description은 사람을 위한 정보로 남겨두세요. 조직 목록에서 보이스를 식별하고, 무엇을 위한 것인지 설명하는 역할을 합니다. 모델에 전달되는 것은 variation 텍스트뿐입니다.
API에서 브랜드 보이스 사용하기#
브랜드 보이스는 localize endpoint를 호출하면 자동으로 적용됩니다. 엔진은 요청의 targetLocale을 연결된 모든 보이스의 variation과 대조해 가장 잘 맞는 항목을 프롬프트에 포함합니다. 별도의 추가 매개변수는 필요하지 않습니다.
{
"sourceLocale": "en",
"targetLocale": "de",
"data": {
"greeting": "Hey there! Ready to ship?",
"cta": "Get started"
}
}위의 독일어 텍스트를 사용하면 엔진은 일반적인 격식체 출력이 아니라, 비격식적이고 기술 지향적인 번역을 생성합니다.
| 호출 | 목적 |
|---|---|
POST /brand-voices | 조직용 보이스 생성 |
GET /organizations/:id/brand-voices | 조직의 보이스 목록을 로캘 수와 엔진 수와 함께 표시 |
GET /brand-voices/:id/variations | 보이스의 로캘별 텍스트 목록 표시 |
POST /brand-voice-variations with brandVoiceId | 한 로캘용 텍스트 추가 |
PUT /brand-voice-variations/:id | 텍스트를 변경하거나 다른 로캘로 이동 |
PUT /engines/:id/brand-voices | 엔진이 적용하는 보이스 집합 교체 |
DELETE /engines/:id/brand-voices/:brandVoiceId | 엔진에 보이스 하나 적용 중지 |
GET /engines/:id/brand-voice-variations | 엔진이 현재 적용 중인 모든 로캘 텍스트 목록 표시 |
POST /brand-voices는 여전히 targetLocale와 text를 함께 받아 보이스의 첫 variation을 만들고, ownerEngineId도 여전히 엔진이 이미 적용 중인 보이스에 텍스트를 추가합니다—보이스가 없으면 새로 만들고 적용합니다.
액세스#
org:brandvoice:read와 org:brandvoice:edit는 보이스와 그 variation을 관리하며, 이를 엔진에 연결하려면 해당 엔진에 대한 engine:edit 권한도 필요합니다. 보이스별 권한 부여를 사용하면 조직의 모든 보이스가 아니라 특정 보이스 하나에 대해서만 읽기 및 편집 권한을 줄 수 있습니다. 자세한 내용은 Roles & Permissions를 참고하세요.
MCP로 브랜드 보이스 관리하기#
Lingo.dev MCP server를 사용하면 AI 코딩 어시스턴트가 대화 중에 직접 브랜드 보이스를 생성하고 업데이트할 수 있습니다:
"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."