Per-site, locale-aware brand voice configuration that gets injected into every AI prompt — chat, agents, generation, SEO.
What it is
Brand Voice is a structured description of how your site should sound. It's a per-site config that the CMS injects into every AI prompt — chat, agents, AI content generation, SEO optimization, rewrites. Instead of repeating "write in a friendly tone, avoid jargon, mention our pillars" in every chat message, you describe your voice once and every downstream AI task inherits it.
The fields
| Field | What it captures |
|---|---|
name, industry, description | Basic brand metadata |
language, targetAudience | Localization context — who the site speaks to |
primaryTone | One-sentence voice summary (e.g. "Technical, neutral, factual") |
brandPersonality | 3–5 adjectives (e.g. ["pragmatic", "precise", "warm"]) |
contentGoals | What the content is trying to achieve |
contentPillars | Strategic topics the brand covers |
avoidTopics | Topics / phrasings the AI should steer clear of |
seoKeywords | Target keywords surfaced to the SEO optimizer |
examplePhrases | Voice samples — actual sentences that sound like the brand |
Configuring via interview
The fastest path is the guided AI interview at Settings → Brand Voice. Claude plays the role of a brand strategist and asks questions about your business, audience, and goals. At the end it generates the JSON, shows a preview, and saves it as a new version.
You can also edit fields directly in the admin form or paste in a JSON payload.
Locale-aware structure
Brand Voice has one primary record plus a cached variant per locale. When an AI consumer requests the voice for locale=da, the CMS:
- If the primary language matches
da, returns the primary record. - Otherwise, checks
brand-voice-da.jsonin_data/. - If no cache exists, calls
/api/cms/brand-voice/translateto auto-translate the primary record into Danish and writes the result tobrand-voice-da.json. - Returns the localized record.
This means editing the primary record can (optionally) invalidate locale caches — subsequent AI calls will regenerate the translation on demand.
What consumes Brand Voice
- Chat system prompt — the full Brand Voice block is injected at the top of every Chat conversation via
gatherSiteContext()andbuildChatSystemPrompt(). - Agent runner — long-running content agents (SEO, rewrite, translate, generate) include the brand voice in their prompts automatically.
- AI generate route —
/api/cms/ai/generatewraps the user request with the voice context before dispatching to the LLM. - SEO optimizer — uses
seoKeywordsas the keyword list to optimize against.
The injection format is a markdown ## Brand Voice block produced by brandVoiceToPromptContext(). Every AI consumer calls that helper — so adding a new consumer is one line.
Versions
Every save creates a new version. The admin shows the history and lets you roll back: activeId in brand-voice.json points to the current version, versions[] holds the full record of changes. Useful when you iterate on tone and want to revert — or A/B test two voice drafts.
Storage
- Primary:
{dataDir}/brand-voice.json— versioned store - Per-locale cache:
{dataDir}/brand-voice-{locale}.json— flat files, one per target locale
dataDir is the site's _data/ directory (sibling of content/).
API endpoints
| Route | Purpose |
|---|---|
GET /api/cms/brand-voice | Read primary. ?locale=xx returns the locale variant (auto-translating if needed) |
POST /api/cms/brand-voice | Save a new version |
POST /api/cms/brand-voice/chat | Stream the interview — Claude as brand strategist |
POST /api/cms/brand-voice/translate | Force regenerate a locale cache |
PATCH /api/cms/brand-voice/versions/[id] | Activate or edit a historical version |
All routes require an authenticated admin session.
When to revisit
- Launching a new locale → translate the voice first, review the auto-translation, edit the tone words (they often don't translate 1:1).
- Rebranding → create a new version, leave the old one in
versions[]for reference. - Noticing AI output drifting → check which version is active and whether a recent edit loosened a constraint.
Brand Voice is the single knob that tunes every AI surface at once. A 30-minute interview at project start pays off on every chat message and every agent run after that.