Keep terms consistent

Goal: decide once which words your project uses for its key terms (product names, UI actions, the words your domain depends on) and have kapi flag anything that drifts. In a project with one language, the terms store holds the word to use and the words to avoid, and kapi check fails a source file that uses a forbidden term, under the rule terms.vocabulary; a term marked advisory reports the use without failing. When the recipe declares a target language, the same terms store also says how each term carries into that language: it guides translation before and checks it after. The rest of the page is about that case. Concepts: Terminology; storage models: Memory & terms storage.

kapi keeps terms in a terms bundle (terms.json). To bring in a list your team already keeps elsewhere, such as a spreadsheet exported to CSV, import it:

terms.csv

source	target	domain
password	mot de passe	security
log in	se connecter	ui
dashboard	tableau de bord	ui
settings	paramètres	ui

Desktop

Context → Terms is where that list lives:

1. Bring in the list. Import the CSV from the CLI (kapi terms import, below) or land term operations through kapi apply; both write the project's terms store. The view lists terms by language pair and domain, ready to browse and search.
2. Spot-check a term. Look up an entry to confirm the approved target before a full pass, and open its occurrences to see where the project uses it.
3. Enforce it. With the terms store in the project, term findings surface in the findings count on the project's Overview, in the terminology gate of check --ship, and against each block in the Review queue.

Agent (Claude)

Ask for enforcement, or for curation:

Check the French files against our approved terms and fix what drifts.

The assistant looks up approved terms before writing (kapi terms lookup), runs term-check afterwards and corrects flagged targets through the format-aware writer. It can note the terms the files use with context_note, with the sentence each was seen in. Each note arrives as a suggestion; keep the ones you want enforced with kapi context review.

CLI

Import once into a named terms store, verify, then check deliveries:

kapi terms import terms.csv --name product-terms \
  --format csv --header -s en -t fr                 # once; persists across sessions
kapi terms lookup "log in" --name product-terms -s en -t fr
kapi exec term-check messages.json --target messages_fr.json \
  --source-lang en --target-lang fr --termstore product-terms

The term-check tool flags targets that don't use the approved equivalent for a source term ("code secret" where the terms store says "mot de passe"). It compares each source string with its translation, so name the source file and pass the translation with --target; a file that holds both languages, such as XLIFF, needs no --target, and over such files kapi exec takes globs and -j 4. kapi exec reports the findings and exits 0 whatever it finds. To fail a CI job on them, check the same pair with kapi check, which exits 3 while a finding fails (see Ship gates and CI):

kapi check messages.json --target messages_fr.json \
  --target-lang fr --termstore product-terms

Keep the terms store current with re-imports (concepts merge) and kapi terms export for vendor kits. Flags: kapi terms, kapi exec term-check, kapi check.

A source term counts in its plural and other regular forms, so "Alerts" uses the term "alert", while a longer word built on it, such as "workflow" for "flow", does not. A translation passes when it contains the approved term, any admitted term for the concept, or a word built around one of them ("kaiplassene" contains "kaiplass"). A form that changes the word, such as the Norwegian plural "varsler" for "varsel", passes once the term lists it as a form. kapi terms validate lists the translated terms that have no forms yet, and kapi terms expand proposes them for you to review before committing.

Two neighbours of term-check cover what a store alone cannot say:

• Rules without a store. term_rules: is the same shape as every word rule, including the terms: a voice file carries (one term, what to use instead, and advisory: true for a rule that reports without failing), and term-check, translate, recycle and pseudo-translate all take it in a flow step's config: or under defaults.tools. A rule can carry a concept_id that ties it to the concept in the store; a replacement rule requires a non-empty replacement. The fields are in the voice profile reference.
• Terms that must survive verbatim. kapi exec dnt-check (do-not-translate) fails a target where a product name, trademark or code identifier listed under --terms was translated, transliterated or dropped; the translate step masks those spans, so the model never sees them. The two routes differ in strength: a --terms string is masked and cannot be translated, while a concept the terms store marks do-not-translate is asked for in the prompt and then enforced, with term-check failing a target that does not keep it.

In a project, the check resolves the terms bound where each file sits and the recipe's languages automatically, with no flags, and the terminology gate folds into kapi check --ship. Terms bound on a profile with profiles.<name>.termstore hold the content at that profile's channels, and the project's own terms hold the rest. The term_rules: the recipe declares hold every file as well: a rule on a flow step or under defaults.tools holds every target language, and one under defaults.locales.<lang>.tools holds that language. So the rules the translate step is given are the rules the gate, kapi status and kapi up hold its output to, and where a recipe rule and a stored term name the same term, the recipe's rule applies. The gate counts content whose language neither source answers for as not_governed and holds it to nothing. A governed target kapi cannot read back counts as not_checked, and the gate does not pass while one remains. kapi terms occurrences "log in" (a term as written, or a concept id, with --locale and --collection to narrow) shows where the project's extracted content uses it, so you can see how much a retirement touches before you decide it.

Try it

The rail imports the list above into a terms store, inspects it and looks up terms, then pseudo-translates and runs term-check against the store:

Loading the walkthrough…

Next

• Reuse what you've translated: the terms store guiding translation as well as checking it.
• Memory & terms storage: the three places a terms store can live.
• Terminology: how discovery and enforcement work.