# Glossaries

Controlled terminology: concepts, term types and matching flags, QA checks in the editor, how terms reach machine translation, and import/export.

Canonical: https://comvi.io/docs/platform/glossaries

A glossary is the approved way to translate specific source terms, so "account" does not
become `cuenta` on one screen and `perfil` on the next. Glossaries are term-level; for
segment-level reuse of whole phrases, see [Translation memory](/docs/platform/translation-memory).

Build one as soon as a product-specific concept is translated inconsistently, a brand name
gets translated, or legal or domain wording is fixed. A handful of UI strings with no
specialist vocabulary does not need one.

## Model

Glossaries belong to the organization. A new organization gets a **Main Glossary**, each
project gets its own writable glossary the first time it needs one, and projects link to
glossaries through an assignment with a priority. A project glossary takes the project's
source language. The Main Glossary takes English (`en`) when available, otherwise the first
configured locale, so shared terms only match in projects that author in that language.
When a project term and a shared term have the same text, the project term wins.

A glossary holds **concepts**. A concept is one meaning and carries a source-language term,
one or more terms per target language, a plain-language **definition** translators rely on,
and a **Translatable** flag to turn off for brand names that must appear unchanged. Each
term carries a type and two matching flags, all optional.

| Type | Shown as | Meaning |
|---|---|---|
| `preferred` | **Correct** | Use this translation |
| `forbidden` | **Forbidden** | Never use this translation |

| Flag | Default | Effect |
|---|---|---|
| **Case sensitive** | Off | Matching ignores case unless on |
| **Exact match** | Off | Off also matches inflected forms ("dashboard" matches "dashboards"); on restricts to whole-word hits. Terms under three characters get no inflection tolerance, three- and four-letter terms allow a short suffix |

Forbidden terms always match on whole-word boundaries, so a forbidden "form" does not flag
"format".

## Add terms

1. Open **Glossary** in the sidebar, under Resources. The **Terms** tab lists everything in
   scope, and the scope filter shows project terms, shared terms or both.

2. Turn on the organization glossary to share terms across every project.

3. Click **Add Term**, pick the scope, and fill in the term, its type and the definition.
   Set part of speech, gender, **Case sensitive**, **Exact match** and **Translatable** as
   needed.

4. Open the term and add a target term for each language.

Start with brand and product nouns: verbs and adjectives are harder to keep consistent at
the term level. Write real definitions, because "dashboard" can be the home screen, a widget
panel or a BI report, each with a different correct translation.

## In the editor

When a translator opens a key, matched source terms are highlighted inline, the correct
translations appear in the glossary panel, and QA checks run on every save of a target
value. Hits never write themselves into the target; the translator decides what to type.

| Check | Default severity | Fires when |
|---|---|---|
| **Forbidden Term Used** | Error | A forbidden target term appears in the translation |
| **Missing Glossary Term** | Warning | The expected target term is absent |
| **Non-translatable Modified** | Warning | A term marked not translatable is not verbatim in the target |
| **Case Mismatch** | Info | A case-sensitive term appears with different casing |

Set each severity to Error, Warning, Info or Disabled on the glossary **Settings** tab. An
error asks for confirmation before the save and lets you go ahead; warnings and info never
interrupt.

## With machine translation

| Provider type | How the glossary is applied |
|---|---|
| **AI** (OpenAI, Anthropic Claude) | Matching terms are injected into the prompt with their correct translations, and non-translatable terms are listed as must-keep-verbatim. Reliable, not guaranteed |
| **Traditional MT** (Google Translate, DeepL, Amazon Translate, Azure Translator) | Terms are not sent to the provider. They appear as hints to the reviewer in the editor |

> **Traditional providers do not enforce terms**
>
> Comvi does not integrate the providers' own glossary APIs. For enforced terminology during
> bulk MT, use an AI provider or run a find-and-replace pass over the output before review.

## Import and export

Import accepts **CSV** and **JSON**, and the dialog previews the first rows of a CSV. Comvi
reads a CSV by its column headers; the REST API accepts a column mapping, the dashboard does
not. Files that use the older `admitted` and `deprecated` term types are read as `preferred`
and `forbidden`. Export produces **CSV**, **TBX** or **JSON**.

## Troubleshooting

- **Terms are not matching.** Check **Case sensitive** against the source casing, and
**Exact match**, which makes "dashboard" miss "dashboards". Missing shared terms usually
mean the Main Glossary's source language differs from the project's.
- **A shared term and a project term disagree.** The project term wins. Filter the scope to
**Project only** and edit or delete the project term.

## Next steps

- [Machine translation](/docs/platform/machine-translation): Prompt injection and hint-only behaviour end to end.
- [Translation memory](/docs/platform/translation-memory): Segment-level reuse for matches longer than a term.
- [Translations](/docs/platform/translations): Where highlights and QA checks surface.