# Market definitions

> Define voice, tone, grammar, and cultural conventions for each locale.

**Category:** Markets | **Tab:** features

---

## What are market definitions?

Market definitions are structured guidelines attached to each market that describe **how** content should sound there. They go beyond translation rules to capture voice, cultural expectations and brand conventions specific to a region.

Each market's *Market Definitions* box starts with **ten default sections**, each designed to give translators, copywriters and AI tools the context they need. Owners and admins can customise these sections for the whole workspace — see [Customising the template](#customising-the-template).

## The ten default sections

| Section | What it captures |
|---------|-----------------|
| **Market Snapshot** | Competitive landscape, audience segments, and market expectations |
| **Voice & Locale DNA** | Core personality traits, brand keywords, and anti-patterns for this market |
| **Tone & Style Rules** | Sentence structure, active/passive voice, formality level, and preferred patterns |
| **Culture & Pragmatics** | Implicit cultural expectations, communication norms, and sensitivity areas |
| **Grammar & Mechanics** | Spelling conventions, contractions, sentence length, and punctuation rules |
| **UX Microcopy Rules** | CTA patterns, system message tone, error handling, and UI label conventions |
| **Locale Conventions** | Currency format, date/time format, number separators, and pricing psychology |
| **Terminology Rules** | Preferred and avoided terms specific to this market |
| **Golden Examples** | Reference copy — headlines, subheadings, feature descriptions — that exemplify the right tone |
| **Output Constraints** | Hard rules: never claim X, always include Y, mandatory disclaimers |

Owners and admins can hide, rename, add or reorder these sections. Each section is free-form text: write as little or as much as you need, from a single line to detailed multi-paragraph guidance.

## Customising the template

Every workspace starts with the ten default sections above. Owners and admins can change them for the whole workspace: open **Markets**, then click **Definition template**.

![The Definition template editor, where owners and admins hide, rename, add and reorder Market Definition sections](/__l5e/assets-v1/aa53d497-597a-420a-ad4f-f88b41114195/market-definition-template.png)

- **Hide** any default section you don't use. Text already written in a hidden section is never deleted. It stays with the market, appears under *Hidden sections with content* when you edit it, and is left out of exports, GitHub Sync and the AI connection until you restore it.
- **Rename** a section heading to match your team's vocabulary.
- **Add your own sections**, with an optional hint for writers, such as *Audience: patients vs professionals*.
- **Reorder** sections with the up and down arrows.
- **Reset to the Black Ice default** at any time. Text already written in markets is kept.

Editors and viewers can see the template but can't change it.

### Step by step

1. Go to **Markets**. The **Definition template** button is at the top right, next to the search box. (It is not inside a market's Edit window, which only uses the template.)
2. Hide, rename, add or reorder sections.
3. Click **Save**. The template now applies to every market in the workspace.
4. Open any market with **Edit**. Its *Market Definitions* box follows the new sections and order.

Custom sections and your order carry through to Markdown and PDF exports, GitHub Sync, the Claude Code bundle, the read API and the AI connection (`get_market_profile` returns them in `definitionSections`).

## Editing market definitions

1. Go to **Markets** in the sidebar.
2. Click **Edit** on the market's row.
3. Write your guidelines in the *Market Definitions* box. It shows one heading per section, in your workspace template's order.
4. Click **Save**.

> Market definitions are workspace-scoped. Each workspace keeps its own definitions per market.

## Download and upload .md

You can draft definitions outside the app and load them in, or take them with you — useful for review in a repo, handing a draft to an agency, or copying one market's structure into another.

In a market's Edit window:

- **Download .md** writes one `## Heading` per section, in your template order. If the market has no definitions yet, you get an empty file with your workspace's headings, ready to fill in.
- **Upload .md** reads a `.md` or `.txt` file back:
  - Headings are matched to your sections, including renamed ones. Files that still use the original ten names load too.
  - Headings the template doesn't know become extra sections instead of being dropped.
  - Text in hidden sections is kept.
  - Files saved on Windows load correctly.
  - If the market already has text, Black Ice asks before replacing it.

**No text is lost.** If you type or import a heading the template doesn't know, it is kept as an extra section in that market instead of being dropped.

## Source market vs. target markets

Your workspace has one designated **source market** (typically your primary locale, e.g., English US). The source market's definitions capture your canonical brand voice — the baseline that target markets adapt from.

Target market definitions describe how to **adapt** that voice for each region. For example:

- **Source (en-US)**: Casual, direct, uses contractions, second-person address
- **Target (de-DE)**: Formal register, no contractions, third-person where culturally expected
- **Target (ja-JP)**: Polite form (です/ます), indirect phrasing, honorific conventions

## How market definitions power AI agents

When you sync your ontology to GitHub via **GitHub Sync**, market definitions are exported as structured Markdown files in the `markets/` directory — one file per market, with your template's sections and order.

AI agents (Claude Code, Cursor, custom pipelines) read these files to understand **how** to write for each market. Instead of guessing tone and style, the agent follows your explicit guidelines:

```
ontology/
├── markets/
│   ├── en-us.md    ← Source voice: casual, direct
│   ├── de-de.md    ← Formal register, legal disclaimers
│   └── pt-br.md    ← Warm, conversational, adapted brand terms
```

This means every AI-generated translation or adaptation follows the same rules your human translators would — without re-briefing.

## Best practices

- **Start with Voice & Locale DNA** — This is the most impactful section. Define personality traits, keywords to use, and patterns to avoid.
- **Add Golden Examples early** — Concrete examples are more useful than abstract rules. Show what good copy looks like in each market.
- **Keep Output Constraints tight** — Use this for non-negotiable rules (legal requirements, brand mandates) that must never be violated.
- **Review quarterly** — Markets evolve. Revisit definitions as your product, audience, or regulatory landscape changes.
- **Don't duplicate terminology rules** — Term-level governance (preferred/allowed/forbidden variants) belongs in concept terms, not in market definitions. Use the Terminology Rules section for market-wide patterns only.

If your workspace has renamed or hidden these sections, apply the same advice to their equivalents.