Þŕöĵéçţ ƒîļé

À ķàþî þŕöĵéçţ îš à þöŕţàƃļé kapi.yaml ŕéçîþé àţ à þŕöĵéçţ'š ŕööţ ţĥàţ çàþţüŕéš à çöñţéñţ ŵöŕķƒļöŵ: ŵĥîçĥ ƒîļéš çöüñţ àš çöñţéñţ, ţĥé ṽöîçé þŕöƒîļé, ţéŕḿš àñđ çööŕđîñàţéš ţĥàţ ĝöṽéŕñ ţĥéḿ, šöüŕçé àñđ ţàŕĝéţ ļàñĝüàĝéš, ţööļ þîþéļîñéš (ƒļöŵš), þļüĝîñ ŕéǫüîŕéḿéñţš, àñđ þŕöçéššîñĝ đéƒàüļţš. Îţ çàŕŕîéš ñö çŕéđéñţîàļš öŕ šţàţé, šö îţ îš àļŵàýš šàƒé ţö çöḿḿîţ. Ƒöŕ ŵĥéñ ţö üšé à þŕöĵéçţ ṽéŕšüš àñ àđ-ĥöç ŕüñ, šéé Þŕöĵéçţš.

Đîšçöṽéŕý

Ļîķé ĝîţ, kapi ŵàļķš üþ ţĥé đîŕéçţöŕý ţŕéé ƒŕöḿ ŵĥéŕé ýöü ŕüñ îţ àñđ üšéš ţĥé ñéàŕéšţ kapi.yaml ŕéçîþé, ŕüññîñĝ îñ þŕöĵéçţ ḿöđé ŵîţĥ ţĥàţ þŕöĵéçţ'š ļàñĝüàĝéš, đéƒàüļţš, àñđ ƒļöŵš. À đîŕéçţöŕý ĥöļđš àţ ḿöšţ öñé kapi.yaml, šö đîšçöṽéŕý îš üñàḿƃîĝüöüš. Àñ éẋþļîçîţ -p <path> öṽéŕŕîđéš đîšçöṽéŕý, àñđ KAPI_NO_PROJECT=1 đîšàƃļéš îţ šö ţĥé ÇĻÎ ŕüñš àđ-ĥöç.

Ƒöŕḿàţ

version: v1
id: prj_k3m7xq2vw9ta5r8ybn4dcp
name: My App

collections:
  - path: "src/locales/en/*.json"
    target: "src/locales/{lang}" # mirror each matched file under the per-language dir

preset: nextjs
plugins:
  okapi: "^1.47.0"

flows:
  translate:
    steps:
      - tool: translate
        config:
          provider: anthropic
          model: <provider-model-id>

  translate-and-qa:
    steps:
      - tool: translate
        config:
          provider: anthropic
      - tool: qa

  pseudo:
    steps:
      - tool: pseudo-translate
        config:
          expansionPercent: 30

defaults:
  source_language: en
  target_languages:
    - fr
    - de
    - ja
  concurrency: 4
  parallel_blocks: 3
  encoding: utf-8
  exclude:
    - "**/*.generated.json"
  merge:
    conflict_policy: translator-wins
  memory:
    fuzzy_threshold: 75
  segmentation:
    source: true
  voice:
    profile: acme-docs

Ƒîéļđš

Ŕéǫüîŕéđ

Ƒîéļđ	Ţýþé	Đéšçŕîþţîöñ
`version`	šţŕîñĝ	Šçĥéḿà ṽéŕšîöñ, ḿüšţ ƃé `"v1"`
`name`	šţŕîñĝ	Þŕöĵéçţ đîšþļàý ñàḿé

Öþţîöñàļ

Ƒîéļđ	Ţýþé	Đéšçŕîþţîöñ
`id`	šţŕîñĝ	Ţĥé þŕöĵéçţ'š šţàƃļé îđéñţîţý (šéé Þŕöĵéçţ îđéñţîţý)
`collections`	Çöļļéçţîöñ[]	Ţĥé çöñţéñţ ţĥîš þŕöĵéçţ ĝöṽéŕñš (šéé Çöļļéçţîöñš)
`profiles`	ḿàþ	Ĝöṽéŕñàñçé ƃöüñđ þéŕ þŕöđüçţ, ķéýéđ ƃý þŕöƒîļé ñàḿé (šéé Þŕöƒîļéš àñđ çĥàññéļš)
`places`	ḿàþ	Ţĥé þŕöĵéçţ'š öŵñ þļàçéš, šüçĥ àš à çîţý, à đîšţŕîçţ öŕ à šàļéš ţéŕŕîţöŕý, ķéýéđ ƃý þļàçé îđ. À ĝéö àẋîš ţàķéš ţĥéšé îñ àđđîţîöñ ţö ţĥé ƃüîļţ-îñ þļàçéš (šéé Þļàçéš)
`axes`	ḿàþ	Ţĥé ķîñđ öƒ éàçĥ đéçļàŕéđ àẋîš, ķéýéđ ƃý àẋîš ñàḿé: ĝéö, ŕàñĝé, öŕđéŕéđ öŕ à çļöšéđ çàţéĝöŕý (šéé Ţýþéđ àẋéš)
`preset`	šţŕîñĝ	À ƒŕàḿéŵöŕķ þŕéšéţ ñàḿé (šéé `kapi init` `--list-presets`) (é.ĝ., `nextjs`, `react-intl`) àþþļîéđ ţö ƒöŕḿàţš
`plugins`	ḿàþ	Þļüĝîñ ŕéǫüîŕéḿéñţš ķéýéđ ƃý ñàḿé (é.ĝ., `okapi: "^1.47.0"`). Ţĥé ļöñĝ ƒöŕḿ ţàķéš `version`, `framework_version` àñđ `format_priority` (šéé Ƒöŕḿàţ éñĝîñéš)
`requires`	ḿàþ	Þļüĝîñ ñàḿé → šéḿṽéŕ çöñšţŕàîñţ ţĥàţ ĝàţéš ļöàđîñĝ; ţĥé ŕéçîþé ŕéƒüšéš ţö ļöàđ ŵîţĥöüţ à ŕéĝîšţéŕéđ þļüĝîñ
`flows`	ḿàþ	Ñàḿéđ ƒļöŵ đéƒîñîţîöñš (šéé Ƒļöŵ Šţéþš)
`flows_dir`	šţŕîñĝ	À đîŕéçţöŕý, ŕéļàţîṽé ţö ţĥé ŕéçîþé, ĥöļđîñĝ öñé ÝÀḾĻ ƒîļé þéŕ ƒļöŵ (šéé Ƒļöŵ ƒîļéš). Ñö đéƒàüļţ
`defaults`	Đéƒàüļţš	Þŕöçéššîñĝ đéƒàüļţš (šéé Đéƒàüļţš; šöüŕçé/ţàŕĝéţ ļàñĝüàĝéš ļîṽé ĥéŕé)
`context`	ÇöñţéẋţƂàçķéñđ	Ŵĥéŕé ţĥé þŕöĵéçţ'š çöñţéẋţ îš šĥàŕéđ: `local` (ţĥé đéƒàüļţ), `file`, `git` öŕ `s3` (šéé Çöñţéẋţ ƃàçķéñđ)
`ship_gate`	Ĝàţé	À šîñĝļé çàţçĥ-àļļ šĥîþ ĝàţé (šéé Šĥîþ ĝàţéš)
`ship_gates`	ŠĥîþĜàţéŔüļé[]	Šçöþéđ šĥîþ-ĝàţé ŕüļéš; ţĥé ḿöšţ šþéçîƒîç ḿàţçĥîñĝ ŕüļé ŵîñš (šéé Šĥîþ ĝàţéš)
`gates`	ḿàþ	Ñàḿéđ ĝàţé ŕéĝîšţŕý à `ship_gates` ŕüļé çàñ ŕéƒéŕéñçé ƃý ñàḿé (šéé Šĥîþ ĝàţéš)
`source_gate`	Ĝàţé	Çöṽéŕàĝé ĝàţé öṽéŕ ţĥé šöüŕçé àüţĥöŕîñĝ ļàđđéŕ (šéé šöüŕçé_ĝàţé)
`established_gate`	Ĝàţé	À šîñĝļé çàţçĥ-àļļ àþþŕöṽàļ ĝàţé: ţĥé ƃàŕ à ļöçàļé ḿüšţ çļéàŕ ţö šĥîþ àþþŕöṽéđ ŕàţĥéŕ ţĥàñ ţŕàñšļàţéđ (šéé Šĥîþ ĝàţéš)
`established_gates`	ŠĥîþĜàţéŔüļé[]	Šçöþéđ àþþŕöṽàļ-ĝàţé ŕüļéš, îñ ţĥé šàḿé `when`/`gate` ƒöŕḿ àš `ship_gates`; ţĥé ḿöšţ šþéçîƒîç ŕüļé ŵîñš. Ŵîţĥ ñéîţĥéŕ ķéý šéţ, ñö ļöçàļé šĥîþš àþþŕöṽéđ

Þŕöĵéçţ îđéñţîţý

kapi init ŵŕîţéš àñ id: îñţö éṽéŕý ŕéçîþé îţ šçàƒƒöļđš:

version: v1
id: prj_k3m7xq2vw9ta5r8ybn4dcp
name: My App

Ţĥé îđ îš ŕàñđöḿļý ĝéñéŕàţéđ àñđ ŕéḿàîñš šţàƃļé ŵĥéñ ýöü ŕéñàḿé öŕ ḿöṽé ţĥé þŕöĵéçţ. Ļöçàļ çļöñéš àñđ ŵöŕķţŕééš ŵîţĥ ţĥé šàḿé îđ šĥàŕé à çöñţéẋţ šţöŕé. Öñ àñöţĥéŕ ḿàçĥîñé, îḿþöŕţ öŕ ŕéšţöŕé ţĥé çöñţéẋţ ţö ḿàķé îţ àṽàîļàƃļé ţĥéŕé.

name: îš ţĥé ļàƃéļ ýöü ŕéàđ îñ kapi status àñđ îñ Ķàþî Đéšķţöþ. Çĥàñĝé îţ ŵĥéñéṽéŕ ýöü ļîķé.

Ķééþ ţĥé id: ļîñé ŵĥéñ çöḿḿîţţîñĝ öŕ çļöñîñĝ ţĥé šàḿé þŕöĵéçţ. Ŵĥéñ çöþýîñĝ à ŕéçîþé ţö çŕéàţé à đîƒƒéŕéñţ þŕöĵéçţ, đéļéţé ţĥàţ ļîñé àñđ ŕüñ kapi init --mint-id. Ţĥîš àššîĝñš à ñéŵ îđéñţîţý ŵîţĥöüţ çĥàñĝîñĝ ţĥé ŕéšţ öƒ ţĥé ŕéçîþé.

À ŕéçîþé ŵîţĥ ñö id: ķééþš ŵöŕķîñĝ. ķàþî îđéñţîƒîéš šüçĥ à þŕöĵéçţ ƃý îţš name:, àñđ kapi init --mint-id ĝîṽéš îţ àñ îđ ŵĥéñéṽéŕ ýöü ŵàñţ öñé.

Ŕéļéàšéš ŵîţĥöüţ šüþþöŕţ ƒöŕ id: þŕéšéŕṽé îţ àš àñ üñķñöŵñ ţöþ-ļéṽéļ éẋţéñšîöñ àñđ çöñţîñüé ţö îđéñţîƒý ţĥé þŕöĵéçţ ƃý ñàḿé. Ḿîẋîñĝ ṽéŕšîöñš ŵîţĥ đîƒƒéŕéñţ îđéñţîţý ĥàñđļîñĝ çàñ ţĥéŕéƒöŕé þŕöđüçé đîƒƒéŕéñţ þŕöĵéçţ ķéýš.

Çöļļéçţîöñš

collections îš à ļîšţ. Éàçĥ éñţŕý îš éîţĥéŕ à ƃàŕé éñţŕý (öñé ĝļöƃ àñđ îţš ţàŕĝéţ, ŵŕîţţéñ îñļîñé) öŕ à ñàḿéđ çöļļéçţîöñ, ŵĥîçĥ ĝŕöüþš çöñţéñţ îţéḿš üñđéŕ à ñàḿé àñđ çàñ ƃîñđ ţĥéḿ ţö à þöîñţ îñ ţĥé þŕöĵéçţ'š çöñţéẋţ šþàçé.

collections:
  # Bare entry: a pattern and where it lands.
  - path: "src/locales/en/*.json"
    target: "src/locales/{lang}"

  # Named collection: a name, the directory it lives in, its items.
  - name: docs
    channel: sdk/docs
    base: web
    content:
      - path: "docs/**/*.mdx"
        target: "i18n/{lang}/{path}.mdx"

Ƒîéļđ	Ţýþé	Đéšçŕîþţîöñ
`name`	šţŕîñĝ	Çöļļéçţîöñ ñàḿé. Ŕéǫüîŕéđ ţö ƃîñđ à `channel:`, àñđ ŵĥàţ à šĥîþ-ĝàţé ŕüļé'š `collections:` šéļéçţöŕ ḿàţçĥéš
`base`	šţŕîñĝ	Ţĥé đîŕéçţöŕý ţĥîš çöļļéçţîöñ ļîṽéš îñ; éṽéŕý `path`, `target` àñđ îţéḿ `base` ƃéļöŵ îš ŵŕîţţéñ ŕéļàţîṽé ţö îţ
`channel`	šţŕîñĝ	Ţĥé þöîñţ îñ ţĥé çöñţéẋţ šþàçé ţĥîš çöļļéçţîöñ'š çöñţéñţ šîţš àţ, àļŵàýš `profile/channel` (šéé Þŕöƒîļéš àñđ çĥàññéļš)
`coordinates`	ḿàþ	Đéçļàŕéđ àẋéš (`brand`, `mode`) ţĥé çöļļéçţîöñ šîţš àţ, öṽéŕļàîđ þéŕ àẋîš öñ `defaults.coordinates`; þŕöđüçţ àñđ çĥàññéļ çöḿé ƒŕöḿ `channel:` àñđ àŕé ŕéĵéçţéđ ĥéŕé (šéé Đéçļàŕéđ àẋéš)
`content`	ÇöñţéñţÎţéḿ[]	Ţĥé çöļļéçţîöñ'š çöñţéñţ îţéḿš
`source_language`	šţŕîñĝ	Öṽéŕŕîđéš `defaults.source_language` ƒöŕ ţĥîš çöļļéçţîöñ
`target_languages`	šţŕîñĝ[]	Öṽéŕŕîđéš `defaults.target_languages` ƒöŕ ţĥîš çöļļéçţîöñ
`source_only`	ƃööļ	Ţĥé çöļļéçţîöñ ĥàš ñö ţàŕĝéţ ļàñĝüàĝé: `kapi up` šķîþš îţ àñđ ţàŕĝéţ-çöṽéŕàĝé ĝàţéš éẋçļüđé îţ. Ŕéĵéçţéđ îƒ ţĥé çöļļéçţîöñ öŕ àñý îţéḿ àļšö çàŕŕîéš à ţàŕĝéţ
`redaction`	ŔéđàçţîöñŠþéç	Ţĥé ŕéđàçţîöñ þöļîçý ƒöŕ ţĥé ƒîļéš ţĥîš çöļļéçţîöñ ĥöļđš, öñ à ñàḿéđ çöļļéçţîöñ öŕ à ƃàŕé éñţŕý. Îţ ŕéþļàçéš `defaults.redaction` ƒöŕ ţĥöšé ƒîļéš (šéé ŕéđàçţîöñ)
`path`	šţŕîñĝ	Ƃàŕé éñţŕîéš öñļý: ţĥé ĝļöƃ, ŵŕîţţéñ îñšţéàđ öƒ `content:`
`format`	šţŕîñĝ öŕ ḿàþ	Ƃàŕé éñţŕîéš öñļý
`target`	šţŕîñĝ	Ƃàŕé éñţŕîéš öñļý

À ñàḿéđ çöļļéçţîöñ ñééđš àţ ļéàšţ öñé îţéḿ üñđéŕ content: àñđ çàññöţ àļšö çàŕŕý à path:; à ƃàŕé éñţŕý ñééđš à path:.

Šéţ source_only: true öñ çöñţéñţ ķàþî ŕéàđš ƃüţ ñéṽéŕ ŵŕîţéš, šüçĥ àš þàçķàĝé đéšçŕîþţîöñš àñđ îñšţàļļéŕ šţŕîñĝš. Ţĥé ƒļàĝ çĥàñĝéš ñö ƃéĥàṽîöüŕ öñ îţš öŵñ, šîñçé à çöļļéçţîöñ ŵîţĥ ñö ţàŕĝéţ ŵàš àļŕéàđý šöüŕçé-öñļý. Îţ ŕéçöŕđš ţĥé îñţéñţ, àñđ ļöàđîñĝ ƒàîļš îƒ ţĥé çöļļéçţîöñ çöñţŕàđîçţš îţ. Šéé Çĥéçķ-öñļý çöñţéñţ îñ öţĥéŕ àššéţš.

ÇöñţéñţÎţéḿ

Ƒîéļđ	Ţýþé	Đéšçŕîþţîöñ
`path`	šţŕîñĝ	Ĝļöƃ þàţţéŕñ ƒöŕ šöüŕçé ƒîļéš, ŕéļàţîṽé ţö ţĥé çöļļéçţîöñ'š `base` (ŕéǫüîŕéđ)
`base`	šţŕîñĝ	Đîŕéçţöŕý à ḿàţçĥéđ ƒîļé'š þàţĥ îš ḿàđé ŕéļàţîṽé ţö; đéƒàüļţš ţö ţĥé ĝļöƃ'š ƒîẋéđ þŕéƒîẋ
`format`	šţŕîñĝ öŕ ḿàþ	Ƒöŕḿàţ ÎĐ; àüţö-đéţéçţéđ þéŕ ƒîļé îƒ öḿîţţéđ
`target`	šţŕîñĝ	Öüţþüţ þàţĥ ţéḿþļàţé (šéé Šöüŕçé àñđ ţàŕĝéţ þàţĥš)
`source_language`	šţŕîñĝ	Öṽéŕŕîđéš ţĥé çöļļéçţîöñ'š àñđ ţĥé þŕöĵéçţ'š šöüŕçé ļàñĝüàĝé
`target_languages`	šţŕîñĝ[]	Öṽéŕŕîđéš ţĥé çöļļéçţîöñ'š àñđ ţĥé þŕöĵéçţ'š ţàŕĝéţ ļàñĝüàĝéš
`channel`	šţŕîñĝ	Öṽéŕŕîđéš ţĥé çöļļéçţîöñ'š `channel:` ƒöŕ ţĥé ƒîļéš ţĥîš îţéḿ ḿàţçĥéš (šéé Þŕöƒîļéš àñđ çĥàññéļš)
`coordinates`	ḿàþ	Ţĥé đéçļàŕéđ àẋéš öƒ ţĥé ƒîļéš ţĥîš îţéḿ ḿàţçĥéš, öṽéŕļàîđ þéŕ àẋîš öñ ţĥé çöļļéçţîöñ'š `coordinates:`. Ƒöŕ éẋàḿþļé, öñé ñéîĝĥƃöüŕĥööđ îñšîđé à çàḿþàîĝñ'š çîţý (šéé Đéçļàŕéđ àẋéš)
`redaction`	ŔéđàçţîöñŠþéç	Ţĥé ŕéđàçţîöñ þöļîçý ƒöŕ ţĥé ƒîļéš ţĥîš îţéḿ ḿàţçĥéš. Îţ ŕéþļàçéš ţĥé çöļļéçţîöñ'š `redaction:` àñđ `defaults.redaction` ƒöŕ ţĥöšé ƒîļéš (šéé ŕéđàçţîöñ)
`comments`	ƃööļ öŕ ḿàþ	Đéçļàŕéš ţĥé çöḿḿéñţš îñ ţĥé ḿàţçĥéđ ƒîļéš àš çöñţéñţ ţö çĥéçķ: Ĝö šöüŕçé, ŕéàđ ƒöŕ îţš çöḿḿéñţš àļöñé, àñđ ÝÀḾĻ, ẊḾĻ-ƃàšéđ, ĤŢḾĻ, Ḿàŕķđöŵñ, ḾĐẊ, ÞÖ àñđ þŕöþéŕţîéš ƒöŕḿàţš, ŵĥöšé çöḿḿéñţš àŕé çĥéçķéđ ƃéšîđé ţĥé ṽàļüéš ţĥéîŕ ŕéàđéŕš éẋţŕàçţ. Ţĥé ḿàþ ƒöŕḿ đéçļàŕéš ţĥéḿ ţöö, àñđ îţš `directives` ļîšţ ñàḿéš ḿàŕķéŕš ýöüŕ öŵñ ţööļš ŕéàđ àţ ţĥé šţàŕţ öƒ à çöḿḿéñţ ļîñé, ŵĥîçĥ àŕé šéţ àšîđé ƃéšîđé ţĥöšé üñđéŕ `defaults.comments.directives`. Îţš `channel` þļàçéš ţĥé çöḿḿéñţš àţ à þöîñţ öƒ ţĥéîŕ öŵñ, à ǫüàļîƒîéđ `profile/channel`: éàçĥ çöḿḿéñţ îš çĥéçķéđ üñđéŕ ţĥàţ þöîñţ'š ṽöîçé àñđ ţéŕḿš, àñđ ţĥé ŕéšţ öƒ ţĥé ƒîļé šţàýš àţ ţĥé îţéḿ'š þöîñţ. Îţš `only: true` đéçļàŕéš ţĥé ƒîļéš ƒöŕ ţĥéîŕ çöḿḿéñţš àļöñé: ķàþî çĥéçķš ţĥé çöḿḿéñţš àñđ ŕéàđš ñöñé öƒ ţĥé ṽàļüéš, šö `kapi up`, ƒļöŵ ŕüñš, `kapi merge`, `kapi extract`, `kapi stats`, `kapi status` çöṽéŕàĝé àñđ ţĥé `--ship` ĝàţéš ļéàṽé ţĥé ṽàļüéš àļöñé, àñđ ţĥé îţéḿ çàññöţ àļšö šéţ `target`, `target_languages`, `redaction`, `format.config` öŕ `format.preset`. Ĝö šöüŕçé îš ŕéàđ ƒöŕ îţš çöḿḿéñţš àļöñé ŵîţĥ öŕ ŵîţĥöüţ `only`. À ƒöŕḿàţ ţĥàţ šüþþļîéš ñö çöḿḿéñţš ḿàķéš ţĥé çĥéçķ ŕéþöŕţ ţĥàţ îţ đîđ ñöţ ŕüñ (šéé Çöḿḿéñţš îñ šöüŕçé çöđé)

ƃàšé

À çöļļéçţîöñ'š base îš ŵĥéŕé ţĥé çöļļéçţîöñ ļîṽéš. Éṽéŕý path, target àñđ îţéḿ base ƃéñéàţĥ îţ îš ŵŕîţţéñ ŕéļàţîṽé ţö ţĥàţ đîŕéçţöŕý àñđ ĵöîñéđ öñţö îţ, šö à çöļļéçţîöñ ŕéàđš àš ţĥé ţŕéé îţ ĝöṽéŕñš, ŵîţĥ ñö þŕéƒîẋ ŕéþéàţéđ öñ éṽéŕý ļîñé:

collections:
  - name: docs
    base: web
    content:
      - path: "docs/**/*.mdx" # → web/docs/**/*.mdx
        target: "i18n/{lang}/{path}.mdx" # → web/i18n/{lang}/{path}.mdx

Àñ îţéḿ'š öŵñ base îš ţĥé šéþàŕàţé, ñàŕŕöŵéŕ ţĥîñĝ: ţĥé đîŕéçţöŕý à ḿàţçĥéđ ƒîļé'š þàţĥ îš ḿàđé ŕéļàţîṽé ţö, ŵĥîçĥ đŕîṽéš ţĥé {relpath} / {path} / {dir} ţöķéñš. Àñ îţéḿ ţĥàţ đéçļàŕéš ñöñé ķééþš ñöñé, àñđ ţĥé ţöķéñš ţĥéñ ŕéļàţîṽîžé àĝàîñšţ ţĥé ĵöîñéđ þàţţéŕñ'š öŵñ ƒîẋéđ þŕéƒîẋ.

Šöüŕçé àñđ ţàŕĝéţ þàţĥš

path îš à đöüƃļéšţàŕ ĝļöƃ: ** ḿàţçĥéš àçŕöšš đîŕéçţöŕîéš (é.ĝ. src/**/*.json) àñđ {a,b,c} ḿàţçĥéš àñý öƒ ţĥé ļîšţéđ àļţéŕñàţîṽéš (é.ĝ. input/store/*.{json,yaml,html}). Öñé ĝļöƃ çàñ ţĥéŕéƒöŕé çöṽéŕ à ŵĥöļé đîŕéçţöŕý öƒ ḿîẋéđ çöñţéñţ; ţĥé ƒöŕḿàţ îš àüţö-đéţéçţéđ þéŕ ƒîļé üñļéšš ýöü þîñ format. Þàţţéŕñš ŕéšöļṽé ŕéļàţîṽé ţö ţĥé þŕöĵéçţ ŕööţ. ** đöéš ñöţ ƒöļļöŵ à šýḿƃöļîç ļîñķ îñţö àñöţĥéŕ đîŕéçţöŕý, šö ţĥé ļîñķéđ þàçķàĝéš à þàçķàĝé ḿàñàĝéŕ ķééþš üñđéŕ node_modules šţàý öüţ öƒ à ḿàţçĥ. À ļîñķ ţö à ƒîļé ţĥàţ ţĥé þàţţéŕñ ḿàţçĥéš îš ŕéàđ, àñđ šö îš à ļîñķéđ đîŕéçţöŕý ţĥàţ ţĥé þàţţéŕñ ñàḿéš ƃéƒöŕé îţš ƒîŕšţ ŵîļđçàŕđ.

À ƒîļé ƃéļöñĝš ţö éẋàçţļý öñé îţéḿ. Îţéḿš àŕé ḿàţçĥéđ îñ ţĥé öŕđéŕ ţĥéý àŕé ŵŕîţţéñ, àçŕöšš àļļ çöļļéçţîöñš, àñđ ţĥé ƒîŕšţ îţéḿ ŵĥöšé path ḿàţçĥéš à ƒîļé çļàîḿš îţ; ļàţéŕ îţéḿš ñéṽéŕ šéé ţĥàţ ƒîļé, ĥöŵéṽéŕ šþéçîƒîç ţĥéîŕ þàţţéŕñ. Àñ îţéḿ đéçļàŕéđ comments: {only: true} çļàîḿš öñļý çöḿḿéñţš, ŵĥéŕéṽéŕ îţ îš ŵŕîţţéñ: ţĥé ƒîŕšţ öţĥéŕ îţéḿ ţĥàţ ḿàţçĥéš à ƒîļé çļàîḿš îţš ṽàļüéš, àñđ ţĥé çöḿḿéñţš šţàý ŵîţĥ ţĥé çöḿḿéñţš-öñļý îţéḿ üñļéšš ţĥàţ öţĥéŕ îţéḿ çöḿéš ƒîŕšţ àñđ đéçļàŕéš ţĥéḿ îţšéļƒ. Ţö þļàçé öñé ƒîļé àţ îţš öŵñ þöîñţ, öŕ üñđéŕ îţš öŵñ ƒöŕḿàţ öŕ ţàŕĝéţ, ļîšţ îţš îţéḿ ƃéƒöŕé ţĥé ĝļöƃ ţĥàţ ŵöüļđ öţĥéŕŵîšé çöṽéŕ îţ:

collections:
  - name: docs
    channel: acme/docs
    content:
      - path: "docs/api-reference.md" # claimed here, at the reference point
        channel: acme/reference
      - path: "docs/**/*.md"          # everything the item above did not claim

Ţĥé base îñ þļàý ĥéŕé îš ţĥé îţéḿ'š öŵñ: ţĥé đîŕéçţöŕý à ḿàţçĥéđ ƒîļé'š þàţĥ îš ḿàđé ŕéļàţîṽé ţö, àƒţéŕ àñý çöļļéçţîöñ base ĥàš ƃééñ ƒöļđéđ îñ. Îţ đéƒàüļţš ţö ţĥé ĝļöƃ'š ƒîẋéđ þŕéƒîẋ, ţĥé ļîţéŕàļ þàŕţ öƒ path ƃéƒöŕé ţĥé ƒîŕšţ ŵîļđçàŕđ (input/docs/ ƒöŕ input/docs/**/*.md). Ţĥé ŕéļàţîṽé þàţĥ đŕîṽéš ţĥé {relpath} / {path} / {dir} ţöķéñš àñđ ĥöŵ ḿüçĥ öƒ ţĥé šöüŕçé ţŕéé à đîŕéçţöŕý-ḿîŕŕöŕ ţàŕĝéţ ŕéþŕöđüçéš.

target îš ţĥé öüţþüţ-þàţĥ ţéḿþļàţé, éẋþàñđéđ þéŕ šöüŕçé ƒîļé àñđ ţàŕĝéţ ļàñĝüàĝé. Ţĥé šüþþöŕţéđ ţöķéñš àŕé:

Ţöķéñ	Ḿéàñîñĝ	Éẋàḿþļé (`base` `input/`, šöüŕçé `input/docs/api.md`)
`{lang}`	Ţàŕĝéţ ļàñĝüàĝé	`fr`
`{relpath}`	Šöüŕçé þàţĥ ŕéļàţîṽé ţö `base`, ŵîţĥ éẋţéñšîöñ	`docs/api.md`
`{path}`	Šöüŕçé þàţĥ ŕéļàţîṽé ţö `base`, ŵîţĥöüţ éẋţéñšîöñ	`docs/api`
`{dir}`	Đîŕéçţöŕý þöŕţîöñ öƒ `{relpath}` (éḿþţý àţ ţĥé ŕööţ)	`docs`
`{filename}`	Ƒîļéñàḿé ŵîţĥ éẋţéñšîöñ	`api.md`
`{name}`	Ƒîļéñàḿé ŵîţĥöüţ éẋţéñšîöñ (àļîàš `{basename}`)	`api`
`{ext}`	Éẋţéñšîöñ ŵîţĥöüţ ţĥé đöţ	`md`

À ƃàŕé * îš šĥöŕţĥàñđ ƒöŕ {name}.

Đîŕéçţöŕý-ḿîŕŕöŕ (ţĥé éàšý đéƒàüļţ). Ŵĥéñ target éñđš ŵîţĥ /, öŕ îţš ļàšţ šéĝḿéñţ ĥàš ñö éẋţéñšîöñ àñđ ñö ŵîļđçàŕđ/ţöķéñ, îţ ñàḿéš à đîŕéçţöŕý àñđ ţĥé šöüŕçé'š {relpath} (üñđéŕ base) îš ḿîŕŕöŕéđ ƃéñéàţĥ îţ. Šö target: output/{lang} ŕéþŕöđüçéš ţĥé šöüŕçé ţŕéé üñđéŕ éàçĥ þéŕ-ļàñĝüàĝé ŕööţ (input/docs/api.md → output/fr/docs/api.md) ŵîţĥ ñö * àñđ ñö ŕîšķ öƒ à đöüƃļéđ éẋţéñšîöñ:

collections:
  - path: "input/**/*.md"
    target: "output/{lang}"

Ţöķéñ ţéḿþļàţé (ţĥé éẋþļîçîţ ƒöŕḿ). Ŵĥéñ ýöü ñééđ ţö ŕéšĥàþé ţĥé ļàýöüţ, ñàḿé ţĥé ţöķéñš:

collections:
  - path: "src/locales/en/*.json"
    target: "src/locales/{lang}/{name}.{ext}" # api.json → src/locales/fr/api.json

Þŕöƒîļéš àñđ çĥàññéļš

Çöñţéñţ îš ŵŕîţţéñ ƒöŕ à þöîñţ îñ ţĥé çöñţéẋţ šþàçé. Ţŵö àẋéš àŕé šţŕüçţüŕàļ: ţĥé þŕöđüçţ îţ ƃéļöñĝš ţö àñđ ţĥé çĥàññéļ îţ šĥîþš öñ. À ķéý üñđéŕ profiles: îš à þŕöđüçţ, ţĥé çĥàññéļš ţĥàţ þŕöƒîļé ļîšţš àŕé ţĥé çĥàññéļš ţĥàţ þŕöđüçţ šĥîþš öñ, àñđ à çöļļéçţîöñ ñàḿéš ţĥé þöîñţ îţš çöñţéñţ šîţš àţ ŵîţĥ öñé channel: ŕéƒéŕéñçé. Ƒüŕţĥéŕ àẋéš àŕé đéçļàŕéđ üñđéŕ coordinates: (šéé Đéçļàŕéđ àẋéš). Çöñţéẋţ îš ţĥé çöñçéþţ; ţĥîš šéçţîöñ îš ţĥé šçĥéḿà.

profiles:
  console:
    channels: [app, docs]
    voice:
      profile: console-voice
  sdk:
    channels:
      - id: docs
        concept: term:9a1c0f42b7
      - cli
    voice:
      profile: acme-docs
    valid_to: 2026-12-01

collections:
  - name: console-app
    channel: console/app
    content:
      - path: "console/i18n/**/*.kbf.json"
  - name: sdk-docs
    channel: sdk/docs
    content:
      - path: "web/docs/**/*.mdx"
      - path: "web/docs/legal/**/*.mdx"
        channel: sdk/cli

Ƒîéļđ	Ţýþé	Đéšçŕîþţîöñ
`channels`	Çĥàññéļ[]	Ţĥé šüŕƒàçéš ţĥîš þŕöđüçţ šĥîþš öñ. À šļüĝ, öŕ `{id, concept}` îñ ļöñĝ ƒöŕḿ
`voice`	ṼöîçéƂîñđîñĝ	Ţĥé ṽöîçé þŕöƒîļé ĝöṽéŕñîñĝ ţĥîš þŕöđüçţ'š çöñţéñţ, îñ ţĥé šàḿé ƒöŕḿš àš `defaults.voice`. Üñšéţ ķééþš `defaults.voice`
`termstore`	šţŕîñĝ	Ţĥé ñàḿé öƒ à ţéŕḿš šţöŕé ĝöṽéŕñîñĝ ţĥîš þŕöđüçţ'š çöñţéñţ: à šţöŕé `kapi terms` ķééþš, ţĥé ñàḿé `--termstore` ţàķéš. À þàţĥ öŕ à ƒîļé ñàḿé (`.db`, `.json`) îš à ļöàđ éŕŕöŕ. Üñšéţ, ţĥé þŕöĵéçţ'š öŵñ ţéŕḿš ĝöṽéŕñ
`concept`	šţŕîñĝ	Ţĥé çöñçéþţ ţĥàţ ñàḿéš ţĥîš þŕöđüçţ, ƒöŕ đîšþļàý. Çàŕŕîéđ àñđ šĥàþé-çĥéçķéđ, ñéṽéŕ ŕéšöļṽéđ đüŕîñĝ ḿàţçĥîñĝ
`valid_from`	šţŕîñĝ	Đàţé (`YYYY-MM-DD`) öŕ ŔƑÇ3339 îñšţàñţ ţĥîš þŕöƒîļé šţàŕţš ĝöṽéŕñîñĝ, îñçļüšîṽé. Üñšéţ îš üñƃöüñđéđ (šéé Þŕöƒîļé ṽàļîđîţý)
`valid_to`	šţŕîñĝ	Đàţé öŕ ŔƑÇ3339 îñšţàñţ îţ šţöþš, éẋçļüšîṽé. Üñšéţ îš üñƃöüñđéđ

Ţĥé ḿàþ ķéý îš ţĥé þŕöƒîļé'š ñàḿé: ţĥé þŕöđüçţ-àẋîš ṽàļüé îţš çöļļéçţîöñš çàŕŕý, àñđ ţĥé ñàḿé ţĥé þŕöĵéçţ'š ṽöîçé šţöŕé àñšŵéŕš üñđéŕ ŵĥéñ ţĥé þŕöƒîļé ƃîñđš ñö voice: öƒ îţš öŵñ. À þŕöƒîļé ţĥàţ ƃîñđš ñéîţĥéŕ à ṽöîçé ñöŕ à ṽöçàƃüļàŕý îš šţîļļ à þŕöƒîļé, ĝöṽéŕñéđ ƃý ţĥé þŕöĵéçţ đéƒàüļţš.

Þŕöƒîļé ñàḿéš àñđ çĥàññéļš àŕé šļüĝš: ļöŵéŕçàšé ļéţţéŕš, đîĝîţš àñđ ĥýþĥéñš, šţàŕţîñĝ ŵîţĥ à ļéţţéŕ öŕ đîĝîţ. Ţĥéý àŕé ḿàçĥîñé îđéñţîƒîéŕš (šţàƃļé, ñéṽéŕ ţŕàñšļàţéđ, çöḿþàŕàƃļé ƃýţé ƒöŕ ƃýţé), ŵĥîçĥ îš ŵĥý à þŕöƒîļé öŕ à çĥàññéļ ḿàý çàŕŕý à çöñçéþţ ƒöŕ đîšþļàý ƃüţ ŕéšöļüţîöñ ñéṽéŕ ļööķš àţ îţ.

À çöļļéçţîöñ'š channel: îš àļŵàýš ŵŕîţţéñ profile/channel: ţĥé þŕöđüçţ öŵñš ţĥé šüŕƒàçé, àñđ ţĥé ƃîñđîñĝ ŕéàđš àš öñé. À ƃàŕé çĥàññéļ ñàḿé îš à ļöàđ éŕŕöŕ ţĥàţ šþéļļš öüţ ţĥé ǫüàļîƒîéđ ƒöŕḿ(š), éṽéñ ŵĥéñ éẋàçţļý öñé þŕöƒîļé đéçļàŕéš îţ. Ƃîñđîñĝ à çĥàññéļ ŕéǫüîŕéš à ñàḿéđ çöļļéçţîöñ. À çöļļéçţîöñ ţĥàţ ƃîñđš ñöñé îš ĝöṽéŕñéđ ƃý ţĥé þŕöĵéçţ đéƒàüļţ þöîñţ, defaults.voice àñđ ţĥé þŕöĵéçţ'š öŵñ ţéŕḿš.

À çöñţéñţ îţéḿ ḿàý çàŕŕý îţš öŵñ channel:, îñ ţĥé šàḿé ǫüàļîƒîéđ ƒöŕḿ àñđ üñđéŕ ţĥé šàḿé ļöàđ-ţîḿé ṽàļîđàţîöñ, ƒöŕ ţĥé ƒîļéš ţĥàţ îţéḿ ḿàţçĥéš. Îţ îš ţĥé ƒîñéšţ þöîñţ à ŕéçîþé çàñ ñàḿé, àñđ éṽéŕýţĥîñĝ ŕéšöļṽéš ţö îţ: à ƒļöŵ ŕüñ þàŕţîţîöñš ţĥöšé ƒîļéš öüţ öƒ ţĥé ŕéšţ öƒ ţĥé çöļļéçţîöñ àñđ ĝîṽéš ţĥéḿ ţĥéîŕ öŵñ ṽöîçé àñđ ţéŕḿš, kapi check ĝàţéš ţĥéḿ àĝàîñšţ ţĥàţ ṽöçàƃüļàŕý, àñđ kapi context search ŕéþöŕţš îţ àš ţĥé þöîñţ éàçĥ üšé šîţš àţ.

Öñ à çöññéçţéđ þŕöĵéçţ, ţĥé ŕéšöļṽéđ þŕöđüçţ àñđ çĥàññéļ ţŕàṽéļ ţö ţĥé šéŕṽéŕ àš ţĥé çöñţéñţ'š çööŕđîñàţéš, šö ƃöţĥ ṽéñüéš ŕéšöļṽé ţĥé šàḿé ṽöîçé ƒöŕ ţĥé šàḿé çöñţéñţ. À þŕöƒîļé'š termstore: đöéš ñöţ: îţ ñàḿéš à šţöŕé öñ ţĥîš ḿàçĥîñé, àñđ à çöññéçţéđ ŕüñ ŵàŕñš ţĥàţ ţĥé ƃîñđîñĝ àþþļîéš ļöçàļļý öñļý.

Ŕéšöļüţîöñ öŕđéŕ

Þŕöƒîļé ƃîñđîñĝš ţàķé þŕéçéđéñçé öṽéŕ þŕöĵéçţ đéƒàüļţš. Ŕéšöļüţîöñ ƒöŕ à çöļļéçţîöñ'š þöîñţ, ḿöšţ šþéçîƒîç ƒîŕšţ:

Šţöŕé	Öŕđéŕ
ṽöîçé	`profiles.<name>.voice` → ţĥé þŕöƒîļé ţĥé šţöŕé ĥöļđš üñđéŕ `<name>` → `defaults.voice`
ţéŕḿš	`--termstore` → `profiles.<name>.termstore` → ţĥé þŕöĵéçţ'š öŵñ ţéŕḿš

Ŕéšöļüţîöñ ŕéàđš šţöŕéđ çöñţéẋţ ƃý ñàḿé. Üšé kapi store import ţö ļöàđ çöñţéẋţ ƒîļéš ƒŕöḿ à çĥéçķöüţ ƃéƒöŕé ţĥéý àƒƒéçţ ĝöṽéŕñàñçé.

Ţĥé çĥàññéļ ţĥéñ ŕéƒîñéš ţĥé ṽöîçé ţĥàţ ŕéšöļṽéđ: à ḿàţçĥîñĝ éñţŕý üñđéŕ ţĥé ṽöîçé þŕöƒîļé'š öŵñ channels: ŕéþļàçéš îţš ţöñé, îţš šţýļé, öŕ ƃöţĥ. Ŵöŕđ ŕüļéš àŕé ţéŕḿš, ŵĥîçĥ àþþļý öñ éṽéŕý çĥàññéļ.

Đéçļàŕéđ àẋéš

Ƃéýöñđ þŕöđüçţ àñđ çĥàññéļ, à þŕöĵéçţ ñàḿéš ţĥé ƒüŕţĥéŕ àẋéš îţš çöñţéñţ ṽàŕîéš àļöñĝ üñđéŕ defaults.coordinates. Éṽéŕý çöļļéçţîöñ îñĥéŕîţš ţĥéḿ; à çöļļéçţîöñ ţĥàţ šîţš éļšéŵĥéŕé öñ öñé àẋîš šéţš ţĥàţ àẋîš îñ îţš öŵñ coordinates: àñđ ķééþš ţĥé ŕéšţ. À çöñţéñţ îţéḿ çàñ àļšö šéţ coordinates: ƒöŕ ţĥé ƒîļéš îţ ḿàţçĥéš. Þéŕ àẋîš, ţĥé ḿöšţ šþéçîƒîç ṽàļüé ŵîñš.

defaults:
  coordinates:
    brand: acme

collections:
  - name: sdk-docs
    channel: sdk/docs
    coordinates:
      mode: reference
    content:
      - path: "web/docs/tutorials/**/*.mdx"
        coordinates:
          mode: tutorial      # these files sit elsewhere on one axis
      - path: "web/docs/**/*.mdx"

Àẋîš	Çöñṽéñţîöñàļ ṽàļüéš	Ḿéàñîñĝ
`brand`	à šļüĝ	Ţĥé ƃŕàñđ à þöîñţ šîţš üñđéŕ, çöàŕšéŕ ţĥàñ þŕöđüçţ
`mode`	`tutorial`, `how-to`, `reference`, `explanation`	Ţĥé ķîñđ öƒ đöçüḿéñţ àţ ţĥé þöîñţ, îñ ţĥé Đîáţàẋîš šéñšé

Ţĥé ḿàþ îš öþéñ. Àñý öţĥéŕ àẋîš ñàḿé îš àççéþţéđ, àñđ îţš ṽàļüéš àŕé ƒŕéé šļüĝš üñļéšš axes: ţýþéš ţĥé àẋîš. product àñđ channel àŕé ŕéƒüšéđ üñđéŕ coordinates: àţ ļöàđ. Ƃöţĥ àŕé đéŕîṽéđ ƒŕöḿ channel:, àñđ à đéçļàŕéđ çöþý çöüļđ çöñţŕàđîçţ ţĥé đéŕîṽéđ ṽàļüé. À ƒîļé'š ŕéšöļṽéđ þöîñţ ḿéŕĝéš ƒöüŕ ļàýéŕš îñ öŕđéŕ: ţĥé đéƒàüļţš, ţĥé àẋéš channel: đéŕîṽéš, ţĥé çöļļéçţîöñ'š coordinates:, àñđ ţĥé îţéḿ'š coordinates:. kapi context ŕéþöŕţš ţĥîš þöîñţ, àñđ à çöññéçţéđ þŕöĵéçţ šéñđš îţ ţö ţĥé šéŕṽéŕ.

Ţýþéđ àẋéš

Ţĥé ţöþ-ļéṽéļ axes: ƃļöçķ šéţš ĥöŵ à đéçļàŕéđ àẋîš çöḿþàŕéš îţš ṽàļüéš. À ŕüļé öŕ à ţéŕḿ šçöþéđ ţö öñé ṽàļüé ţĥéñ ĥöļđš àţ éṽéŕý ṽàļüé îñšîđé îţ. À ŕüļé ķéþţ ƒöŕ market: nordics ĥöļđš ƒöŕ çöñţéñţ àţ market: no, àñđ öñé ķéþţ ƒöŕ age: 13-17 ĥöļđš àţ age: 14-16.

places:
  nordics:
    name: Nordics
    of: [no, se, dk, fi, is]

axes:
  market:
    kind: geo
    label: Market
  audience:
    values: [general, new-customers, specialists]
    labels:
      new-customers: New customers
  age:
    kind: range
    unit: years
  lifecycle:
    kind: ordered
    values: [preview, current, sunset]

defaults:
  coordinates:
    market: nordics
    audience: general

Ƒîéļđ	Ţýþé	Đéšçŕîþţîöñ
`kind`	šţŕîñĝ	`category` (ţĥé đéƒàüļţ), `geo`, `range` öŕ `ordered`
`label`	šţŕîñĝ	Ţĥé àẋîš'š đîšþļàý ñàḿé
`values`	šţŕîñĝ[]	Ţĥé ṽàļüéš ţĥé àẋîš ţàķéš, îñ đîšþļàý öŕđéŕ. À çàţéĝöŕý àẋîš ŵîţĥ `values` ŕéĵéçţš àñý öţĥéŕ ṽàļüé. Àñ öŕđéŕéđ àẋîš ŕéǫüîŕéš `values`. À ĝéö öŕ ŕàñĝé àẋîš ţàķéš ñöñé
`labels`	ḿàþ	Đîšþļàý ļàƃéļš þéŕ ṽàļüé. À ĝéö àẋîš ţàķéš ñöñé, ƃéçàüšé éàçĥ þļàçé đéçļàŕéš îţš öŵñ ñàḿé
`unit`	šţŕîñĝ	À ŕàñĝé àẋîš öñļý: ŵĥàţ ţĥé ñüḿƃéŕš çöüñţ, šüçĥ àš `years`

Àñ àẋîš ţàķéš ñö öţĥéŕ ķéý. À ḿîššþéļţ ķéý ƒàîļš ţĥé ļöàđ.

Ķîñđ	Ṽàļüéš	À ṽàļüé ĥöļđš àţ
`category`	àñý šļüĝ, öŕ ţĥé đéçļàŕéđ `values`	ţĥé šàḿé ṽàļüé
`ordered`	ţĥé đéçļàŕéđ `values`, îñ öŕđéŕ	ţĥé šàḿé ṽàļüé
`geo`	à þļàçé îđ: `world`, à ÜÑ Ḿ49 ŕéĝîöñ (`northern-europe`, `latin-america-and-the-caribbean`), àñ ÎŠÖ 3166-1 çöüñţŕý îñ ļöŵéŕ çàšé (`no`, `de`), àñ ÎŠÖ 3166-2 šüƃđîṽîšîöñ îñ ļöŵéŕ çàšé (`no-03`, `us-ca`), öŕ à þļàçé đéçļàŕéđ üñđéŕ `places:`	îţšéļƒ àñđ éṽéŕý þļàçé îñšîđé îţ
`range`	àñ îñţéŕṽàļ `13-17`, àñ öþéñ üþþéŕ ƃöüñđ `65-`, öŕ öñé ñüḿƃéŕ `18`	îţšéļƒ àñđ éṽéŕý îñţéŕṽàļ îñšîđé îţ

Éṽéŕý ṽàļüé üñđéŕ defaults.coordinates, à çöļļéçţîöñ'š coordinates: àñđ à çöñţéñţ îţéḿ'š coordinates: îš çĥéçķéđ àĝàîñšţ îţš àẋîš àţ ļöàđ. Ţĥé ļöàđ ƒàîļš öñ à ṽàļüé ţĥàţ à çļöšéđ àẋîš đöéš ñöţ đéçļàŕé, à ĝéö ṽàļüé ţĥàţ îš ñöţ à þļàçé îđ, öŕ àñ îñṽéŕţéđ ŕàñĝé. Ţĥé éŕŕöŕ ļîšţš ţĥé ṽàļîđ šþéļļîñĝš. Àñ àẋîš ţĥàţ axes: đöéš ñöţ ļîšţ îš àñ öþéñ çàţéĝöŕý. product àñđ channel çàññöţ ƃé đéçļàŕéđ üñđéŕ axes:.

Þļàçéš

À ĝéö àẋîš ţàķéš þļàçé îđš. Ţĥé ƃüîļţ-îñ þļàçéš àŕé ţĥé ŵöŕļđ, ţĥé ÜÑ Ḿ49 ŕéĝîöñš, éṽéŕý ÎŠÖ 3166-1 çöüñţŕý àñđ éṽéŕý ÎŠÖ 3166-2 šüƃđîṽîšîöñ. Ţö ļööķ üþ à þļàçé îđ, ŕüñ kapi context places:

kapi context places oslo

oslo          Oslo          locality     world › europe › northern-europe › no › no-03 › oslo
no-03         Oslo          subdivision  world › europe › northern-europe › no › no-03
greater-oslo  Greater Oslo  metro        world › europe › northern-europe › no › greater-oslo

Ţĥé ţöþ-ļéṽéļ places: ƃļöçķ àđđš ţĥé þŕöĵéçţ'š öŵñ þļàçéš, ķéýéđ ƃý îđ. Éàçĥ þļàçé šîţš ŵîţĥîñ öñé öŕ ḿöŕé þļàçéš (within:) öŕ îš ḿàđé öƒ þļàçéš (of:). Çöñţàîñḿéñţ îš çöḿþüţéđ ƒŕöḿ ţĥéšé đéçļàŕàţîöñš öñļý. À ŕüļé ķéþţ ƒöŕ Ñöŕŵàý àþþļîéš ţö çöñţéñţ àţ market: oslo, ƃéçàüšé Öšļö îš đéçļàŕéđ ŵîţĥîñ ţĥé çöüñţý no-03, ŵĥîçĥ šîţš ŵîţĥîñ Ñöŕŵàý.

places:
  oslo:
    name: Oslo
    type: locality
    within: no-03
    centroid: [59.91, 10.75]
    refs: [wikidata:Q585, geonames:3143244]
  grunerlokka:
    name: Grünerløkka
    type: neighbourhood
    within: oslo
    shape: places/grunerlokka.geojson
  greater-oslo:
    name: Greater Oslo
    names: { nb: Stor-Oslo }
    type: metro
    of: [no-03, no-32]

Ƒîéļđ	Ţýþé	Đéšçŕîþţîöñ
`name`	šţŕîñĝ	Ţĥé đîšþļàý ñàḿé. Đéƒàüļţš ţö ţĥé îđ
`names`	ḿàþ	Đîšþļàý ñàḿéš ķéýéđ ƃý ļöçàļé (`nb`, `en-GB`); à ļööķüþ ƃý ñàḿé ḿàţçĥéš ţĥéšé ţöö
`type`	šţŕîñĝ	`subdivision`, `territory`, `metro`, `locality`, `district`, `neighbourhood`, `postal-area` öŕ `area`. Đéƒàüļţš ţö `territory` ƒöŕ à þļàçé ŵîţĥ `of:` àñđ `area` ƒöŕ à þļàçé ŵîţĥ `within:`
`within`	šţŕîñĝ öŕ šţŕîñĝ[]	Ţĥé þļàçéš ţĥîš öñé šîţš îñšîđé. À þļàçé îñšîđé šéṽéŕàļ þļàçéš ļîšţš éàçĥ öƒ ţĥéḿ
`of`	šţŕîñĝ öŕ šţŕîñĝ[]	Ţĥé þļàçéš ţĥîš öñé îš ḿàđé öƒ, šüçĥ àš ţĥé çöüñţŕîéš öƒ à šàļéš ţéŕŕîţöŕý
`refs`	šţŕîñĝ[]	Ţĥé þļàçé'š îđš îñ öţĥéŕ ĝàžéţţééŕš, àš `scheme:value`: `wikidata:Q585`, `geonames:3143244`, `nuts:NO081`, `osm:relation/406091`, `wof:101752073`
`centroid`	[ļàţ, ļöñ]	Àñ àþþŕöẋîḿàţé çéñţŕé, ŵĥéŕé ţĥé Éẋþļöŕé ḿàþ îñ Ķàþî Đéšķţöþ đŕàŵš ţĥé þļàçé ŵĥéñ îţ ĥàš ñö šĥàþé
`shape`	šţŕîñĝ	À ĜéöĴŠÖÑ ƒîļé ĥöļđîñĝ ţĥé þļàçé'š öüţļîñé, ŕéļàţîṽé ţö ţĥé ŕéçîþé, éñđîñĝ `.geojson` öŕ `.json`. Ţĥé Éẋþļöŕé ḿàþ îñ Ķàþî Đéšķţöþ đŕàŵš îţ. Çöñţàîñḿéñţ îĝñöŕéš îţ

À þļàçé šéţš éẋàçţļý öñé öƒ within: àñđ of:. À þļàçé ḿàđé öƒ þļàçéš šîţš ŵîţĥîñ éṽéŕý þļàçé ţĥàţ çöñţàîñš àļļ öƒ îţš ḿéḿƃéŕš. Îţ çöñţàîñš éṽéŕý þļàçé ţĥàţ šîţš ŵîţĥîñ öñé öƒ îţš ḿéḿƃéŕš. Ţŵö þļàçéš öṽéŕļàþ ŵĥéñ öñé çöñţàîñš ţĥé öţĥéŕ, ŵĥéñ à ḿéḿƃéŕ öƒ öñé öṽéŕļàþš ţĥé öţĥéŕ, öŕ ŵĥéñ à đéçļàŕéđ þļàçé šîţš ŵîţĥîñ ƃöţĥ. À šüĝĝéšţîöñ àţ greater-oslo àñđ öñé àţ oslo ţĥéŕéƒöŕé öṽéŕļàþ, àñđ ŕéṽîéŵ šĥöŵš ţĥéḿ àš à çöñƒļîçţ ŵĥéñ ţĥéý đîšàĝŕéé.

Ţĥé ŕéçîþé ƒàîļš ţö ļöàđ ŵĥéñ à þļàçé îš îñṽàļîđ, àñđ ţĥé éŕŕöŕ ñàḿéš ţĥé ķéý:

Ŕéçîþé	Éŕŕöŕ
àñ îđ ţĥàţ à ƃüîļţ-îñ þļàçé üšéš	`places.no-03: no-03 is a built-in place (Oslo, Norway); a declared place takes an id of its own`
ƃöţĥ `within:` àñđ `of:`	`places.oslo: a place sits within places or is made of places, never both`
ñéîţĥéŕ	places.grunerlokka: a place names the places it sits within (`within:`) or is made of (`of:`)
àñ îđ ţĥàţ îš ñöţ à þļàçé	places.oslo.within: "no-3" is not a place. Did you mean no-31 (Østfold, Norway), no-32 (Akershus, Norway), no-33 (Buskerud, Norway)? Look a place up with `kapi context places no-3`
à çýçļé ţĥŕöüĝĥ `within:`	`places.grunerlokka: the place sits within itself through grunerlokka › grunerlokka-north › grunerlokka`
àñ üñķñöŵñ ţýþé	`places.oslo.type: "city" is not a type a declared place takes. Use one of subdivision, territory, metro, locality, district, neighbourhood, postal-area, area`
à ḿàļƒöŕḿéđ ŕéƒéŕéñçé	`places.oslo.refs: "wikidata:585" does not follow the wikidata scheme (write it as wikidata:Q585)`
à çéñţŕöîđ öƒƒ ţĥé ĝļöƃé	`places.oslo.centroid: [159.91, 10.75] is not on the globe: latitude runs from -90 to 90 and longitude from -180 to 180`
à šĥàþé öüţšîđé ţĥé þŕöĵéçţ	`places.oslo.shape: "../oslo.geojson": the path leaves the project`
à šĥàþé ƒîļé ţĥàţ îš ḿîššîñĝ	`places.oslo.shape: places/oslo.geojson: no such file beside the recipe`
àñ üñķñöŵñ ķéý üñđéŕ à þļàçé	`line 44: a place takes no key "parent" (it takes [name names type within of refs centroid shape])`

Îƒ à ĝéö ṽàļüé îš ñöţ à þļàçé îđ, ţĥé ŕéçîþé ƒàîļš ţö ļöàđ àñđ ţĥé éŕŕöŕ šüĝĝéšţš ţĥé çöŕŕéçţ îđ: "Oslo" is not a place. Write it in lower case: oslo, "no03" is not a place. Write it with a hyphen: no-03. Öţĥéŕŵîšé ţĥé éŕŕöŕ ļîšţš ţĥé çļöšéšţ ḿàţçĥéš ƃý ñàḿé, öŕ ţĥé ķîñđš öƒ þļàçé îđ ŵĥéñ ñöţĥîñĝ ḿàţçĥéš, ƒöļļöŵéđ ƃý ţĥé kapi context places çöḿḿàñđ ƒöŕ ţĥé ṽàļüé.

Þŕöƒîļé ṽàļîđîţý

valid_from àñđ valid_to ƃöüñđ à þŕöƒîļé'š ĝöṽéŕñàñçé îñ ţîḿé, ţĥé šàḿé ĥàļƒ-öþéñ ŵîñđöŵ à ţéŕḿ çàŕŕîéš, ŵîţĥ valid_from îñçļüšîṽé àñđ valid_to éẋçļüšîṽé, šö à valid_to đàţé éẋçļüđéš ţĥàţ ŵĥöļé đàý. À ƃöüñđ îš à đàţé (YYYY-MM-DD) öŕ àñ ŔƑÇ3339 îñšţàñţ; àñ üñþàŕšéàƃļé ƃöüñđ öŕ àñ îñṽéŕţéđ ŕàñĝé ƒàîļš àţ ļöàđ.

À þŕöƒîļé öüţšîđé îţš ŵîñđöŵ đöéš ñöţ ĝöṽéŕñ. Ŕéšöļüţîöñ ƒàļļš ţĥŕöüĝĥ ţö ţĥé ñéẋţ ƃîñđîñĝ (à çöļļéçţîöñ'š çĥàññéļ üñđéŕ àñ éẋþîŕéđ îţéḿ çĥàññéļ, ţĥéñ ţĥé þŕöĵéçţ đéƒàüļţ) éẋàçţļý àš îƒ ţĥé éẋþîŕéđ þŕöƒîļé ŵéŕé àƃšéñţ, àñđ ţĥé ŕüñ, çĥéçķ öŕ þüšĥ ţĥàţ àþþļîéđ ţĥé ƒàļļ-ţĥŕöüĝĥ ŕéþöŕţš îţ öñçé:

governance: profile "sdk" expired 2026-12-01; governing with the project default

Ţĥé îñšţàñţ îš ţĥé ŕüñ'š öŵñ ŵàļļ çļöçķ; ţĥéŕé îš ñö ƒļàĝ ţö ŕéšöļṽé ƒöŕ àñöţĥéŕ đàţé. kapi context search ŕéàđš éṽéŕý ƃöüñđéđ þŕöƒîļé àĝàîñšţ ţĥé çüŕŕéñţ ţîḿé àñđ ļàƃéļš îţ active, upcoming öŕ expired, šö à ŵîñđöŵ çàñ ƃé šééñ ƃéƒöŕé îţ çļöšéš.

Đéƒàüļţš

defaults ĥöļđš þŕöĵéçţ-ŵîđé þŕöçéššîñĝ šéţţîñĝš ţĥàţ îñđîṽîđüàļ çöñţéñţ îţéḿš çàñ öṽéŕŕîđé. Šéṽéŕàļ öƒ ţĥéšé àŕé ĝöṽéŕñéđ ƃý Ḿ-01.

Ƒîéļđ	Ţýþé	Đéšçŕîþţîöñ
`source_language`	šţŕîñĝ	ƂÇÞ-47 šöüŕçé ļöçàļé (é.ĝ., `en`)
`target_languages`	šţŕîñĝ[]	ƂÇÞ-47 ţàŕĝéţ ļöçàļéš. À ţàĝ ḿàý çàŕŕý à `-u-sd-` šüƃđîṽîšîöñ, šüçĥ àš `nb-NO-u-sd-no03`, ţö ñàḿé ţĥé þļàçé ţĥé çöñţéñţ îš ŵŕîţţéñ ƒöŕ
`locale_format`	šţŕîñĝ	Ļöçàļé šţýļé ƒöŕ ţĥé `{lang}` þļàçéĥöļđéŕ: `bcp-47` (đéƒàüļţ) öŕ `posix`
`concurrency`	îñţ	Ñüḿƃéŕ öƒ ƒîļéš ţö þŕöçéšš îñ þàŕàļļéļ
`parallel_blocks`	îñţ	Ñüḿƃéŕ öƒ ƃļöçķš ţö þŕöçéšš îñ þàŕàļļéļ ŵîţĥîñ à ƒîļé
`encoding`	šţŕîñĝ	Çĥàŕšéţ ţĥé ƒîļéš àŕé ŕéàđ îñ àñđ ŵŕîţţéñ ƃàçķ îñ (đéƒàüļţ: `utf-8`). À ƃýţé-öŕđéŕ ḿàŕķ îñ à ƒîļé ŵîñš öṽéŕ îţ; `--encoding` öñ ţĥé çöḿḿàñđ ļîñé ŵîñš öṽéŕ ţĥé ŕéçîþé. Ƃîñàŕý ƒöŕḿàţš (Öƒƒîçé đöçüḿéñţš, îḿàĝéš) àŕé ñöţ àƒƒéçţéđ
`exclude`	šţŕîñĝ[]	Ĝļöƃ þàţţéŕñš ñö çöļļéçţîöñ çļàîḿš: çöñţéñţ šçàññîñĝ šķîþš ţĥéḿ, àñđ à ƒîļé ýöü ñàḿé ţĥàţ öñé ḿàţçĥéš šîţš àţ ţĥé þŕöĵéçţ'š đéƒàüļţ þöîñţ (é.ĝ. `*/.generated.json`)
`engine`	šţŕîñĝ	Ţĥé ƒöŕḿàţ éñĝîñé þŕéƒéŕŕéđ ƒöŕ à ƒîļé ŵĥöšé éẋţéñšîöñ ƃöţĥ à ƃüîļţ-îñ ƒöŕḿàţ àñđ à þļüĝîñ'š çļàîḿ: `native` öŕ à đéçļàŕéđ þļüĝîñ'š ñàḿé (šéé Ƒöŕḿàţ éñĝîñéš)
`formats`	ḿàþ	Þéŕ-ƒöŕḿàţ `preset`, `config`, `engine` àñđ đéţéçţîöñ `priority` öṽéŕŕîđéš (šéé ƒöŕḿàţš)
`merge`	ḾéŕĝéĐéƒàüļţš	Ĥöŵ `kapi merge` ŕéšöļṽéš à ţŕàñšļàţöŕ'š ţàŕĝéţ àĝàîñšţ àñ éẋîšţîñĝ ţàŕĝéţ öŕ çöñţéñţ-ḿéḿöŕý éñţŕý (šéé ḿéŕĝé)
`memory`	ḾéḿöŕýĐéƒàüļţš	Çöñţéñţ-ḿéḿöŕý þŕé-ƒîļļ öñ `kapi extract` àñđ ŵŕîţé-ƃàçķ öñ `kapi merge` (šéé ḿéḿöŕý)
`segmentation`	ŠéĝḿéñţàţîöñĐéƒàüļţš	Öþţ-îñ šéñţéñçé-ļéṽéļ šéĝḿéñţàţîöñ öṽéŕļàý àþþļîéđ öñ éẋţŕàçţ (šéé šéĝḿéñţàţîöñ)
`redaction`	ŔéđàçţîöñŠþéç	Ŕéþļàçé šéñšîţîṽé çöñţéñţ ŵîţĥ þŕöţéçţéđ þļàçéĥöļđéŕš ƃéƒöŕé þŕöçéššîñĝ àñđ ŕéšţöŕé îţ àƒţéŕŵàŕđš (šéé ŕéđàçţîöñ)
`annotations`	ÀññöţàţîöñĐéƒàüļţš	`write:` ļîšţš ţĥé àññöţàţîöñ ţýþéš à ŵŕîţéŕ đŕàŵš îñţö ţĥé đöçüḿéñţ àš îñļîñé ḿàŕķš, öüţ öƒ ŵĥàţ ţĥé ƒöŕḿàţ đéçļàŕéš îţ çàñ çàŕŕý. Éḿþţý đŕàŵš éṽéŕý ţýþé ţĥé ƒöŕḿàţ šüþþöŕţš; ñàḿîñĝ à ţýþé à ƒöŕḿàţ çàññöţ çàŕŕý àšķš ƒöŕ ñöţĥîñĝ ţĥéŕé
`comments`	ḿàþ	`directives`: ḿàŕķéŕš ýöüŕ öŵñ ţööļš ŕéàđ àţ ţĥé šţàŕţ öƒ à çöḿḿéñţ ļîñé, šéţ àšîđé ŵĥéŕéṽéŕ ķàþî ŕéàđš ţĥé þŕöĵéçţ'š çöḿḿéñţš. `channel`: ţĥé þöîñţ, à ǫüàļîƒîéđ `profile/channel`, àţ ŵĥîçĥ éṽéŕý đéçļàŕéđ îţéḿ'š çöḿḿéñţš šîţ üñļéšš ţĥé îţéḿ ñàḿéš îţš öŵñ (šéé Çöḿḿéñţš îñ šöüŕçé çöđé)
`voice`	ṼöîçéƂîñđîñĝ	Ƃîñđ à ṽöîçé þŕöƒîļé àš šţàñđîñĝ þŕöĵéçţ çöñţéẋţ (šéé ṽöîçé). À þŕöƒîļé'š öŵñ `voice:` öṽéŕŕîđéš îţ ƒöŕ ţĥàţ þŕöđüçţ'š çöñţéñţ
`coordinates`	ḿàþ	Ţĥé þŕöĵéçţ'š đéƒàüļţ þöîñţ öñ ţĥé đéçļàŕéđ àẋéš (`brand`, `mode`), îñĥéŕîţéđ ƃý éṽéŕý çöļļéçţîöñ; `product` àñđ `channel` àŕé đéŕîṽéđ ƒŕöḿ `channel:` àñđ ŕéĵéçţéđ ĥéŕé (šéé Đéçļàŕéđ àẋéš)
`tools`	ḿàþ	Þŕöĵéçţ-ļéṽéļ ţööļ þŕéšéţš, ķéýéđ ƃý ţööļ ñàḿé: çöñƒîĝ àþþļîéđ ŵĥéŕéṽéŕ ţĥàţ ţööļ ŕüñš îñ à þŕöĵéçţ ƒļöŵ. À šţéþ'š öŵñ `config` öṽéŕŕîđéš à þŕéšéţ þéŕ ķéý. `term_rules:` îš ţĥé ķéý `term-check`, `translate`, `recycle`, `dnt-check` àñđ `pseudo-translate` ţàķé ĥéŕé (öñé ţéŕḿ, ŵĥàţ ţö üšé îñšţéàđ, àñđ `advisory: true` ƒöŕ à ŕüļé ţĥàţ ŕéþöŕţš ŵîţĥöüţ ƒàîļîñĝ), àñđ ţĥé ţéŕḿîñöļöĝý ĝàţé ĥöļđš éṽéŕý ţàŕĝéţ ļàñĝüàĝé ţö îţ (šéé Ţéŕḿ ŕüļéš)
`locales`	ḿàþ	Þéŕ-ţàŕĝéţ-ļàñĝüàĝé öṽéŕŕîđéš ķéýéđ ƃý ļöçàļé. Éàçĥ éñţŕý'š `tools:` þŕéšéţš ḿéŕĝé öṽéŕ `defaults.tools` àñđ üñđéŕ à šţéþ'š öŵñ çöñƒîĝ ŵĥéñéṽéŕ à ƒļöŵ ŕüñš ƒöŕ ţĥàţ ļöçàļé, šö öñé ļöçàļé çàñ éñàƃļé ŕéđàçţîöñ öŕ à đîƒƒéŕéñţ ḿöđéļ ŵîţĥöüţ ƒöŕķîñĝ ţĥé ƒļöŵ (šéé ţĥé ķàþî ļööþ). À `term_rules:` þŕéšéţ ĥéŕé ĝöṽéŕñš ţĥàţ ļöçàļé àţ ţĥé ţéŕḿîñöļöĝý ĝàţé
`flow`	šţŕîñĝ	Ţĥé þŕöĵéçţ'š đéƒàüļţ ƒļöŵ, ţĥé çöḿþöšéđ ƒļöŵ `kapi up` ŕüñš ţö çàţçĥ üþ éṽéŕý ļöçàļé. À ķéý îñ `flows:`, à ƒîļé îñ `flows_dir:`, öŕ à ƃüîļţ-îñ ñàḿé (é.ĝ. `translate`), ŕéšöļṽéđ àš `kapi run` ŕéšöļṽéš îţ. Éḿþţý ŕüñš ţĥé ƃüîļţ-îñ đéƒàüļţ (ŕéçýçļé → ţŕàñšļàţé)
`materialize`	šţŕîñĝ	Ŵĥö đéļîṽéŕš ţŕàñšļàţéđ ƒîļéš. `manual` (đéƒàüļţ) ļéàṽéš đéļîṽéŕý ţö `kapi merge` öŕ `kapi up --materialize`; `on-converge` ḿàķéš `kapi up` ŵŕîţé à ļöçàļé'š ƒîļéš ţö ţĥé çöļļéçţîöñ'š `target:` öñļý öñçé îţš ĝàţéđ çöļļéçţîöñš àŕé šĥîþþàƃļé, àñđ ķééþš ţĥé đŕàƒţš öƒ à ļöçàļé ŵàîţîñĝ ƒöŕ ŕéṽîéŵ îñ ţĥé þŕöĵéçţ'š ŵöŕķšþàçé üñţîļ ţĥéñ
`jobs`	îñţ	Ĥöŵ ḿàñý ţàŕĝéţ ļàñĝüàĝéš öñé `kapi up` þàšš ŕüñš çöñçüŕŕéñţļý. `0` (đéƒàüļţ) ļéàṽéš îţ ţö ţĥé ŕüññéŕ (4); `--jobs` öṽéŕŕîđéš þéŕ ŕüñ
`translate_after`	šţŕîñĝ	Ţĥé šöüŕçé šţàţüš à ƃļöçķ ḿüšţ ŕéàçĥ ƃéƒöŕé ţĥé ļööþ ţŕàñšļàţéš îţ (šéé ţŕàñšļàţé_àƒţéŕ)

À çöļļéçţîöñ àñđ à çöñţéñţ îţéḿ çàñ éàçĥ đéçļàŕé à redaction: öƒ ţĥéîŕ öŵñ (šéé ŕéđàçţîöñ).

ţŕàñšļàţé_àƒţéŕ

defaults.translate_after îš ţĥé šöüŕçé šţàţüš à ƃļöçķ ḿüšţ ŕéàçĥ ƃéƒöŕé ţĥé ļööþ ţŕàñšļàţéš îţ. Ţĥé ļööþ ĥöļđš éàçĥ ƃļöçķ'š ƒàñ-öüţ üñţîļ îţš šöüŕçé ĝéţš ţĥéŕé. Îţ îš à šéþàŕàţé šéţţîñĝ ƒŕöḿ ţĥé ţöþ-ļéṽéļ source_gate çöṽéŕàĝé ƃàŕ ţĥàţ kapi check --ship éṽàļüàţéš. Šöüŕçé-ƒîŕšţ çöñṽéŕĝéñçé šéţţļéš ţĥé šöüŕçé (ţéŕḿîñöļöĝý, ṽöîçé, šöüŕçé çĥéçķš) àñđ ĥöļđš ţĥé ƒàñ-öüţ öñ îţ, šö àñ üñšéţţļéđ, ñöñ-çöḿþļîàñţ šöüŕçé îš ţŕàñšļàţéđ îñţö éṽéŕý ļöçàļé öñçé îţ îš ŕéàđý ŕàţĥéŕ ţĥàñ ŕéđöñé ŵĥéñ îţ çĥàñĝéš. Šéé Çöñṽéŕĝéñçé: šöüŕçé ƒîŕšţ.

defaults:
  translate_after: written   # the default: written source whose checks pass
                             # translates (no human bottleneck)
  # translate_after: established  # wait until a person approves the source
  # translate_after: none         # opt out: raw fan-out, no hold

Ṽàļüé	Ḿéàñîñĝ
(üñšéţ)	Ŕüññéŕ àþþļîéš ţĥé đéƒàüļţ (`written`)
`written`	Đéƒàüļţ: ŵŕîţţéñ šöüŕçé ţŕàñšļàţéš öñçé îţš çĥéçķš þàšš
`established`	À þéŕšöñ àþþŕöṽéđ ţĥé šöüŕçé (ṽöîçé-çŕîţîçàļ öŕ ŕéĝüļàţéđ çöñţéñţ)
`none`	Đéļîƃéŕàţé öþţ-öüţ: ţŕàñšļàţé ŵîţĥöüţ šéţţļîñĝ ţĥé šöüŕçé ƒîŕšţ

Öñ à çöññéçţéđ þŕöĵéçţ, à šöüŕçé ƃéļöŵ ţĥîš ļéṽéļ ĥöļđš ţĥé çöñṽéŕĝéñçé ŕüñ (source_not_ready) àñđ öþéñš à šöüŕçé-ŕéṽîéŵ ţàšķ ŕàţĥéŕ ţĥàñ ţŕàñšļàţîñĝ; ţĥé šöüŕçé-šîđé çöṽéŕàĝé ƃàŕ àñđ ţĥîš çöñṽéŕĝéñçé ļéṽéļ àŕé îñđéþéñđéñţ çöñţŕöļš.

ƒöŕḿàţš

defaults.formats çöñƒîĝüŕéš ƒöŕḿàţš ƃý ñàḿé, šö à šîñĝļé ŵîļđçàŕđ çöñţéñţ îţéḿ (path: "input/*", ñö format:) çàñ ļéţ éàçĥ ƒîļé'š éñĝîñé ƃé àüţö-đéţéçţéđ ŵĥîļé ýöü šţîļļ ţüñé îñđîṽîđüàļ ƒöŕḿàţš îñ öñé þļàçé. Éàçĥ éñţŕý ţàķéš:

Ƒîéļđ	Ţýþé	Đéšçŕîþţîöñ
`preset`	šţŕîñĝ	À ñàḿéđ ƒöŕḿàţ þŕéšéţ àþþļîéđ ţö ţĥîš ƒöŕḿàţ (šéé `kapi formats`)
`config`	ḿàþ	Ŕéàđéŕ öþţîöñ öṽéŕŕîđéš ƒöŕ ţĥîš ƒöŕḿàţ (ḿéŕĝéđ üñđéŕ, àñđ öṽéŕŕîđàƃļé ƃý, à çöñţéñţ îţéḿ'š `format.config`)
`engine`	šţŕîñĝ	Ţĥé éñĝîñé ţĥàţ šéŕṽéš ţĥé éẋţéñšîöñš ţĥîš ƒöŕḿàţ çļàîḿš: `native` öŕ à đéçļàŕéđ þļüĝîñ'š ñàḿé. Ţĥé éñţŕý'š ķéý ñàḿéš à ƒöŕḿàţ (`json`) öŕ àñ éẋţéñšîöñ (`.json`)
`priority`	îñţ	Đéţéçţîöñ þŕîöŕîţý àḿöñĝ ţĥé ƒöŕḿàţš öƒ öñé éñĝîñé; ĥîĝĥéŕ ŵîñš ŵĥéñ šéṽéŕàļ çļàîḿ ţĥé šàḿé éẋţéñšîöñ

priority ƃŕéàķš à ţîé îñšîđé öñé éñĝîñé. Ḿöšţ éẋţéñšîöñš ḿàþ ţö öñé ƒöŕḿàţ, ƃüţ šöḿé àŕé çļàîḿéđ ƃý šéṽéŕàļ ƒöŕḿàţš öƒ ţĥé šàḿé þļüĝîñ: .srt ƃý ƃöţĥ okf_vtt àñđ okf_regex. Ƃüḿþîñĝ ţĥé þŕéƒéŕŕéđ öñé šţééŕš àüţö-đéţéçţîöñ ŵîţĥöüţ ñàḿîñĝ à ƒöŕḿàţ öñ éṽéŕý îţéḿ. engine ḿöṽéš àñ éẋţéñšîöñ ţö àñöţĥéŕ éñĝîñé:

plugins:
  okapi-bridge: "*"
defaults:
  formats:
    okf_vtt:
      priority: 110 # .srt → WebVTT engine (beats okf_regex)
    html:
      engine: okapi-bridge # .html → the bridge's okf_html, not the built-in html
    okf_json:
      config:
        useFullKeyPath: true
collections:
  - name: Source Files
    content:
      - path: "input/*" # every file; engine auto-detected, two pinned above
        target: "output/{lang}"

À þŕîöŕîţý ñéṽéŕ ḿöṽéš à ƒîļé ţö àñöţĥéŕ éñĝîñé: ţĥé éñĝîñé îš çĥöšéñ ƒîŕšţ (šéé Ƒöŕḿàţ éñĝîñéš), àñđ ţĥé þŕîöŕîţîéš ŕàñķ ţĥàţ éñĝîñé'š ƒöŕḿàţš.

Ƒöŕḿàţ éñĝîñéš

À ƒöŕḿàţ éñĝîñé îš à þŕöṽîđéŕ öƒ ƒöŕḿàţš: native (ţĥé ƒöŕḿàţš ķàþî šĥîþš) öŕ à þļüĝîñ, ñàḿéđ àš ţĥé ŕéçîþé đéçļàŕéš îţ (okapi-bridge). Ŵĥéñ à ƃüîļţ-îñ ƒöŕḿàţ àñđ à þļüĝîñ'š ƒöŕḿàţ çļàîḿ ţĥé šàḿé éẋţéñšîöñ, ţĥé éñĝîñé öŕđéŕ đéçîđéš ŵĥîçĥ ŕéàđš ţĥé ƒîļé. Ţĥé öŕđéŕ, ƒîŕšţ ţö ļàšţ:

Ţĥé éñĝîñé defaults.formats.<name>.engine þîñš ƒöŕ ţĥé éẋţéñšîöñ.
Ţĥé éñĝîñé --engine ñàḿéš öñ ţĥé ŕüñ.
Ţĥé éñĝîñé defaults.engine ñàḿéš.
Ţĥé éñĝîñé formats.engine ñàḿéš îñ ţĥé üšéŕ çöñƒîĝ.
native.
Ţĥé đéçļàŕéđ þļüĝîñš, ŕàñķéđ ƃý plugins.<name>.format_priority (ĥîĝĥéšţ ƒîŕšţ) àñđ ţĥéñ ƃý ñàḿé.

Ţĥé ƒîŕšţ éñĝîñé ŵîţĥ à ƒöŕḿàţ ƒöŕ ţĥé éẋţéñšîöñ ŵîñš; ŵĥéñ šéṽéŕàļ öƒ îţš ƒöŕḿàţš çļàîḿ ţĥé éẋţéñšîöñ, ţĥé ƒîļé'š çöñţéñţ àñđ ţĥéñ priority đéçîđé àḿöñĝ ţĥéḿ. Đéţéçţîöñ šţàýš ŵîţĥîñ ţĥé ŕéçîþé'š šöüŕçéš: ţĥé ƃüîļţ-îñ ƒöŕḿàţš àñđ ţĥé þļüĝîñš üñđéŕ plugins:. À þļüĝîñ îñšţàļļéđ öñ ţĥé ḿàçĥîñé ƃüţ ñöţ đéçļàŕéđ šéŕṽéš ñöñé öƒ ţĥé þŕöĵéçţ'š ƒîļéš, àñđ àñ éñĝîñé ñàḿéđ üñđéŕ defaults.engine öŕ defaults.formats.<name>.engine ḿüšţ ƃé native öŕ à đéçļàŕéđ þļüĝîñ.

plugins:
  okapi-bridge:
    format_priority: 200 # ahead of kapi-av where both claim an extension
  kapi-av: "*"
defaults:
  engine: okapi-bridge # the bridge reads every extension it claims
  formats:
    .json:
      engine: native # except JSON, which the built-in format reads

À ƒöŕḿàţ ñàḿéđ öüţŕîĝĥţ, ŵîţĥ --format, --map öŕ à çöñţéñţ îţéḿ'š format:, îš ŕéàđ ƃý ţĥàţ ƒöŕḿàţ ŵĥàţéṽéŕ ţĥé éñĝîñé öŕđéŕ šàýš, àñđ îţš ŵŕîţéŕ çöḿéš ƒŕöḿ ţĥé šàḿé éñĝîñé. Ţö ñàḿé ţĥé ƒöŕḿàţ öƒ öñé éñĝîñé ƒöŕ à ƒîļé šéṽéŕàļ éñĝîñéš ŕéàđ, àđđ ţĥé éñĝîñé ţö ţĥé ŕéƒéŕéñçé: html@okapi-bridge îš ţĥé ƃŕîđĝé'š ĤŢḾĻ ƒöŕḿàţ àñđ okf_html@native ţĥé ƃüîļţ-îñ öñé. Üñđéŕ à defaults.formats.<name>.engine þîñ, ţĥé ƃàŕé ñàḿé ŕéšöļṽéš ţö ţĥé þîññéđ éñĝîñé'š ƒöŕḿàţ. Ţĥé ṽéŕšîöñ àñđ þŕéšéţ þàŕţš ķééþ ţĥéîŕ þļàçéš: name[@engine][@version][:preset].

kapi formats ļîšţš éàçĥ ƒöŕḿàţ ŵîţĥ îţš éñĝîñé àñđ ḿàŕķš àñ éẋţéñšîöñ ḿöŕé ţĥàñ öñé éñĝîñé çļàîḿš. kapi formats explain <file> šàýš ŵĥîçĥ ƒöŕḿàţ ŕéàđš à ƒîļé, ƒŕöḿ ŵĥîçĥ éñĝîñé àñđ ƃý ŵĥîçĥ ŕüļé, üñđéŕ ţĥé ŕéçîþé îñ šçöþé.

ḿéŕĝé

Ƒîéļđ	Ţýþé	Đéšçŕîþţîöñ
`conflict_policy`	šţŕîñĝ	Ŵĥàţ `kapi merge` đöéš ŵîţĥ à ƃļöçķ ŵĥöšé ţŕàñšļàţîöñ çĥàñĝéđ îñ ţĥé þŕöĵéçţ šîñçé ţĥé éẋţŕàçţîöñ: `translator-wins` (đéƒàüļţ) ŕéþļàçéš îţ, `existing-wins` ķééþš îţ, `newest-wins` ţàķéš ţĥé ŕéţüŕñéđ ƒîļé ŵĥéñ îţ îš ñéŵéŕ ţĥàñ ţĥé ţŕàñšļàţîöñ'š ƒîļé

ḿéḿöŕý

Ƒîéļđ	Ţýþé	Đéšçŕîþţîöñ
`fuzzy_threshold`	îñţ	Ḿîñîḿüḿ ƒüžžý ḿàţçĥ šçöŕé (0–100) ţö þŕé-ƒîļļ ţĥé ţàŕĝéţ öñ éẋţŕàçţ (đéƒàüļţ: `75`)

šéĝḿéñţàţîöñ

Ƒîéļđ	Ţýþé	Đéšçŕîþţîöñ
`source`	ƃööļ	Ţöĝĝļé šéñţéñçé-ļéṽéļ šéĝḿéñţàţîöñ öƒ šöüŕçé ţéẋţ öñ éẋţŕàçţ
`srx`	šţŕîñĝ	Öþţîöñàļ ŠŔẊ ŕüļéš ƒîļé; ƃüîļţ-îñ đéƒàüļţ ŕüļéš àŕé üšéđ ŵĥéñ éḿþţý

ŕéđàçţîöñ

Ţĥé šéñšîţîṽé ţéŕḿ ļîšţ ļîṽéš îñ à šéþàŕàţé ŕüļéš ƒîļé ŕéƒéŕéñçéđ ƃý rules (šö îţ çàñ ƃé ĝîţîĝñöŕéđ); ţĥîš šþéç þöîñţš àţ îţ àñđ šéļéçţš đéţéçţîöñ ƃàçķéñđš.

À þöļîçý çàñ ƃé đéçļàŕéđ îñ ţĥŕéé þļàçéš: defaults.redaction, redaction: öñ à çöļļéçţîöñ, àñđ redaction: öñ à çöñţéñţ îţéḿ. Éàçĥ ƒîļé îš ŕéđàçţéđ üñđéŕ ţĥé ḿöšţ šþéçîƒîç đéçļàŕàţîöñ ţĥàţ çöṽéŕš îţ: îţš îţéḿ'š, éļšé îţš çöļļéçţîöñ'š, éļšé ţĥé đéƒàüļţš. Ţĥàţ đéçļàŕàţîöñ ŕéþļàçéš ţĥé öţĥéŕš ƒöŕ ţĥé ƒîļé. Îţš ƒîéļđš àŕé ñöţ ḿéŕĝéđ ŵîţĥ ţĥéîŕš, šö à çöļļéçţîöñ ţĥàţ ñàḿéš îţš öŵñ rules ƒîļé ŕéđàçţš ŵîţĥ ţĥàţ ƒîļé àļöñé, àñđ enabled: false öñ à çöļļéçţîöñ öŕ àñ îţéḿ ţüŕñš ŕéđàçţîöñ öƒƒ ƒöŕ îţš ƒîļéš. À redaction: àţ àñý öƒ ţĥé ţĥŕéé þļàçéš ţĥàţ šéţš rules, detectors öŕ placeholder ḿüšţ àļšö šéţ enabled: true, àñđ ţĥé ŕéçîþé ƒàîļš ţö ļöàđ öţĥéŕŵîšé; ŵŕîţé enabled: false ŵîţĥ ñö öţĥéŕ ķéý ţö šŵîţçĥ ŕéđàçţîöñ öƒƒ.

Ƒîéļđ	Ţýþé	Đéšçŕîþţîöñ
`enabled`	ƃööļ	Ţüŕñ ŕéđàçţîöñ öñ ƒöŕ ţĥé ƒîļéš ţĥé đéçļàŕàţîöñ çöṽéŕš
`rules`	šţŕîñĝ	Þàţĥ ţö à ŕéđàçţîöñ ŕüļéš ÝÀḾĻ ƒîļé
`detectors`	šţŕîñĝ[]	Đéţéçţîöñ ƃàçķéñđš: `rules` àñđ/öŕ `entities`
`placeholder`	šţŕîñĝ	Öṽéŕŕîđé ţĥé ṽîšîƃļé šţàñđ-îñ ţéḿþļàţé, é.ĝ. `[REDACTED:{category}]`

ṽöîçé

Ƃîñđ à ṽöîçé þŕöƒîļé üñđéŕ defaults.voice, ƃý ñàḿé. Éẋàçţļý öñé šöüŕçé îš éẋþéçţéđ:

Ƒîéļđ	Ţýþé	Đéšçŕîþţîöñ
`profile`	šţŕîñĝ	Ţĥé îđ (öŕ ñàḿé) öƒ à þŕöƒîļé îñ ţĥé þŕöĵéçţ'š ṽöîçé šţöŕé, àš `kapi voice profiles` ļîšţš îţ
`pack`	šţŕîñĝ	Ñàḿé öƒ à ƃüîļţ-îñ šţàŕţéŕ þàçķ

Ţĥé šĥöŕţ ƒöŕḿ îš ţĥé îđ àļöñé: voice: fernwell ŕéàđš àš voice: {profile: fernwell}.

Çöñţéẋţ ƒîļéš

À ŕéçîþé ñàḿéš ñö çöñţéẋţ ƒîļé. À þŕöĵéçţ'š ṽöîçé þŕöƒîļéš, ţéŕḿš àñđ çöñţéñţ ḿéḿöŕý ļîṽé îñ îţš šţöŕé, àñđ ţĥé ŕéçîþé ƃîñđš à ṽöîçé öŕ à ţéŕḿš šţöŕé ƃý ñàḿé. Ƒîļéš çàŕŕýîñĝ çöñţéẋţ (à voice.yaml, à terms.json, çöñţéñţ-ḿéḿöŕý ƃüñđļéš) àŕé ŕéàđ îñţö ţĥé šţöŕé ƃý kapi store import, ƒŕöḿ ţĥé þŕöĵéçţ'š .kapi/ đîŕéçţöŕý öŕ ƒŕöḿ à đîŕéçţöŕý ýöü ñàḿé, šüçĥ àš à šàḿþļé'š context/. Àñ éđîţ ţö öñé öƒ ţĥöšé ƒîļéš ţàķéš éƒƒéçţ ŵĥéñ ýöü îḿþöŕţ îţ àĝàîñ.

Ŵĥéñ ţĥé îḿþöŕţ ƃŕîñĝš à ṽöîçé þŕöƒîļé îñţö à þŕöĵéçţ ŵĥöšé ŕéçîþé ƃîñđš ñö ṽöîçé üñđéŕ defaults:, îţ àđđš ţĥé ƃîñđîñĝ ţö kapi.yaml àñđ šàýš šö:

Bound voice Fernwell in kapi.yaml (defaults.voice.profile: fernwell).

Ţĥé ţŵö ļîñéš îţ àđđš àŕé ţĥé öñļý çĥàñĝé ţö ţĥé ƒîļé. Ŵĥéñ ţĥé îḿþöŕţ ƃŕîñĝš šéṽéŕàļ þŕöƒîļéš, îţ ƃîñđš ñöñé àñđ ļîšţš ţĥéḿ ŵîţĥ ţĥé ļîñé ţö àđđ.

À ṽöîçé þŕöƒîļé üñđéŕ .kapi/profiles/<name>/voice.yaml ƃéļöñĝš ţö ţĥé þŕöƒîļé öƒ ţĥàţ ñàḿé. À þŕöƒîļé ţĥàţ ƃîñđš ñö ṽöîçé îš ĝöṽéŕñéđ ƃý ţĥé šţöŕéđ þŕöƒîļé öƒ îţš öŵñ ñàḿé, šö à ƒîļé đéçļàŕîñĝ id: <name> ñééđš ñö ƃîñđîñĝ. Ŵĥéñ ţĥé ƒîļé îš šţöŕéđ üñđéŕ àñöţĥéŕ îđ, ţĥé îḿþöŕţ ƃîñđš îţ üñđéŕ profiles.<name>.voice:

Bound voice Promo Voice for profile promo in kapi.yaml (profiles.promo.voice.profile: promo-voice).

À ŕéçîþé ţĥàţ šţîļļ ñàḿéš à ƒîļé ƒàîļš ţö ļöàđ, àñđ ţĥé ḿéššàĝé ñàḿéš ţĥé îḿþöŕţ ţĥàţ ŕéàđš ţĥé ƒîļé àñđ ţĥé ƃîñđîñĝ ţö ŵŕîţé îñšţéàđ. Ţĥé ŕéţîŕéđ ķéýš àŕé defaults.terms_source, defaults.memory_source, voice: {profile_file: …}, à voice: ţĥàţ îš à þàţĥ, àñđ à termstore: ţĥàţ îš à þàţĥ öŕ à ƒîļé ñàḿé.

À ŕéçîþé ţĥàţ ƃîñđš à ṽöîçé ţĥé šţöŕé đöéš ñöţ ĥöļđ, öñ à ḿàçĥîñé ŵĥéŕé ţĥé þŕöĵéçţ'š çöñţéẋţ ĥàš ñöţ ƃééñ îḿþöŕţéđ öŕ þüļļéđ, šàýš ŵĥîçĥ ƃîñđîñĝ îţ îš àñđ ţĥé çöḿḿàñđ ţĥàţ ƃŕîñĝš îţ: kapi context sync ŵĥéñ ţĥé þŕöĵéçţ šĥàŕéš îţš çöñţéẋţ, öŕ kapi store import îñ à çĥéçķöüţ çàŕŕýîñĝ ţĥé þŕöƒîļé. Šéé Ḿöṽîñĝ çöñţéẋţ.

Ƒļöŵ Šţéþš

Éàçĥ ƒļöŵ çöñţàîñš àñ öŕđéŕéđ ļîšţ öƒ šţéþš. Šéé Ƒļöŵ Šţéþš Ƒöŕḿàţ ƒöŕ ţĥé ƒüļļ šþéçîƒîçàţîöñ.

flows:
  my-flow:
    steps:
      - tool: translate # tool name (required)
        config: # tool-specific config (optional)
          provider: anthropic
        label: "Translate" # display label (optional)

Ţĥé šţéþš ŕüñ îñ ţĥé öŕđéŕ ļîšţéđ, éàçĥ ţööļ ŕéàđîñĝ ŵĥàţ ţĥé šţéþ ƃéƒöŕé îţ éḿîţţéđ. À šţéþ ĥöļđîñĝ à parallel: ļîšţ öƒ ţööļš îš þàŕšéđ ƃüţ çàññöţ ŕüñ: kapi run šţöþš ŵîţĥ àñ éŕŕöŕ ƃéƒöŕé þŕöçéššîñĝ ţĥé ƒļöŵ. Ļîšţ ţĥöšé ţööļš àš öŕđéŕéđ šţéþš îñšţéàđ.

À qa šţéþ šéļéçţš îţš ƃàçķéñđ ŵîţĥ mode: rules (ţĥé đéƒàüļţ) ŕüñš ţĥé đéţéŕḿîñîšţîç çĥéçķš, àñđ ai ŕüñš ţĥé ÀÎ ŕéṽîéŵ ŵîţĥ ţĥé šţéþ'š provider. À qa šţéþ öŕ þŕéšéţ ţĥàţ šéţš provider ḿüšţ àļšö šéţ mode, àñđ ţĥé ŕéçîþé ƒàîļš ţö ļöàđ öţĥéŕŵîšé. À mode öţĥéŕ ţĥàñ rules öŕ ai àļšö šţöþš ţĥé ļöàđ. À qa çöñƒîĝ ţĥàţ ĥöļđš checkTerminology àļšö ƒàîļš ţö ļöàđ: ţĥé ŕüļé çĥéçķš ŕéàđ ñö ţéŕḿš, šö ŕéḿöṽé ţĥé ķéý àñđ ŕüñ term-check ţö çĥéçķ ţŕàñšļàţîöñš àĝàîñšţ ţĥé ţéŕḿš šţöŕé.

flows:
  review:
    steps:
      - tool: qa
        config:
          mode: ai
          provider: anthropic

Ƒļöŵ ƒîļéš

À þŕöĵéçţ ŵîţĥ ḿàñý ƒļöŵš çàñ ķééþ éàçĥ îñ îţš öŵñ ÝÀḾĻ ƒîļé, ñàḿéđ ƒöŕ ţĥé ƒļöŵ, îñ à đîŕéçţöŕý ţĥé ŕéçîþé ñàḿéš ŵîţĥ flows_dir:. Ţĥé þàţĥ îš ŕéļàţîṽé ţö ţĥé ŕéçîþé, àñđ à çöḿḿîţţéđ đîŕéçţöŕý îš ţĥé ŕîĝĥţ þļàçé ƒöŕ îţ; ķàþî ŕéĵéçţš à flows_dir üñđéŕ .kapi/, šîñçé ţĥàţ đîŕéçţöŕý îš à çàçĥé ƒöŕ öñé çĥéçķöüţ.

# kapi.yaml
flows_dir: flows

# flows/guard.yaml, run with `kapi run guard`
description: Check the do-not-translate list
steps:
  - tool: dnt-check
    config:
      terms: [Acme Cloud]

À ƒļöŵ ƒîļé ĥöļđš ţĥé šàḿé šţéþš àš àñ éñţŕý üñđéŕ flows:, þļüš àñ öþţîöñàļ description:. Îţš šţéþš ñàḿé ñö îñþüţ öŕ öüţþüţ þàţĥš: kapi run ţàķéš ţĥé ƒîļéš ƒŕöḿ ţĥé ŕéçîþé'š çöļļéçţîöñš, öŕ ƒŕöḿ --input.

À ƒļöŵ ñàḿé ŕüñš ţĥé ḿöšţ šþéçîƒîç đéƒîñîţîöñ: ţĥé éñţŕý üñđéŕ flows:, ţĥéñ ţĥé ƒîļé öƒ ţĥàţ ñàḿé, ţĥéñ ţĥé ƃüîļţ-îñ ƒļöŵ öƒ ţĥàţ ñàḿé. Šö à ŕéçîþé ţĥàţ đéçļàŕéš translate ŕüñš îţš öŵñ ŵîţĥ kapi run translate àñđ àš defaults.flow, àñđ kapi flows ļîšţš îţ îñ þļàçé öƒ ţĥé ƃüîļţ-îñ. Ţĥé kapi translate àñđ kapi pseudo-translate çöḿḿàñđš àļŵàýš ŕüñ ţĥé ƃüîļţ-îñ ƒļöŵ.

ķàþî ŕéàđš ñö ƒļöŵ ƒîļéš ƒŕöḿ .kapi/flows/. Ŵĥéñ îţ ƒîñđš šöḿé ţĥéŕé, îţ þŕîñţš öñé ŵàŕñîñĝ ñàḿîñĝ ţĥéḿ; ḿöṽé ţĥéḿ ţö à çöḿḿîţţéđ đîŕéçţöŕý àñđ šéţ flows_dir:.

Ţéŕḿ ŕüļéš

term_rules: îñ à šţéþ'š config:, îñ à ƒļöŵ ƒîļé öŕ üñđéŕ defaults.tools ĝîṽéš ţĥé šţéþ ţĥé ŵöŕđîñĝ à ţŕàñšļàţîöñ ḿüšţ üšé. Ţĥé ţéŕḿîñöļöĝý ĝàţé ĥöļđš ţĥé ţŕàñšļàţîöñš ţö ţĥé šàḿé ŕüļéš, ƃéšîđé ţĥé ţéŕḿš ƃöüñđ ŵĥéŕé ţĥé çöñţéñţ šîţš, šö kapi check --ship, kapi status àñđ kapi up ţŕéàţ éṽéŕý ļàñĝüàĝé ţĥé ŕüļéš ñàḿé àš ĝöṽéŕñéđ. À ŕüļé öñ à ƒļöŵ šţéþ öŕ üñđéŕ defaults.tools àþþļîéš ţö éṽéŕý ţàŕĝéţ ļàñĝüàĝé; à ŕüļé üñđéŕ defaults.locales.<lang>.tools àþþļîéš ţö ţĥàţ ļàñĝüàĝé. À ḿîšš ƒàîļš ţĥé ĝàţé üñļéšš ţĥé ŕüļé îš ḿàŕķéđ advisory: true, ŵĥîçĥ ŕéþöŕţš îţ. Ŵĥéŕé à ŕéçîþé ŕüļé àñđ à šţöŕéđ ţéŕḿ ñàḿé ţĥé šàḿé ţéŕḿ, ţĥé ŕéçîþé'š ŕüļé àþþļîéš.

flows:
  converge:
    steps:
      - tool: translate
        config:
          term_rules: &term_rules
            - term: billing period
              replacement: période de facturation
            - term: reading
              replacement: relevé
              advisory: true
      - tool: term-check
        config:
          term_rules: *term_rules

Ţĥé ƒîéļđš àŕé îñ ţĥé ṽöîçé þŕöƒîļé ŕéƒéŕéñçé.

Çöñţéẋţ ƃàçķéñđ

context: šàýš ŵĥéŕé ţĥé þŕöĵéçţ'š çöñţéẋţ îš šĥàŕéđ, šö éṽéŕý çĥéçķöüţ öƒ ţĥé þŕöĵéçţ, öñ éṽéŕý ḿàçĥîñé, šĥàŕéš ţĥé šàḿé þļàçé ţĥŕöüĝĥ kapi context sync:

context:
  backend: git                  # local (default), file, git or s3
  ref: refs/kapi/context        # git: a ref in this repository, outside every branch

Ƒîéļđ	Ƃàçķéñđ	Đéšçŕîþţîöñ
`backend`	àļļ	`local` ķééþš ţĥé çöñţéẋţ öñ éàçĥ ḿàçĥîñé; `file`, `git` àñđ `s3` šĥàŕé îţ
`ref`	`git`	Ţĥé ŕéƒ ţĥé çöñţéẋţ îš ķéþţ öñ. Đéƒàüļţ `refs/kapi/context`; à ƃŕàñçĥ öŕ à ţàĝ îš ŕéƒüšéđ
`remote`	`git`	Ţĥé ĝîţ ŕéḿöţé ƒéţçĥéđ ƒŕöḿ àñđ þüšĥéđ ţö. Đéƒàüļţ `origin`
`path`	`file`	Ţĥé đîŕéçţöŕý ţĥé çöñţéẋţ îš ķéþţ îñ, šüçĥ àš à ḿöüñţéđ ţéàḿ šĥàŕé. À ŕéļàţîṽé þàţĥ îš ŕéàđ àĝàîñšţ ţĥé ŕéçîþé'š đîŕéçţöŕý
`bucket`	`s3`	Ţĥé ƃüçķéţ. Ŕéǫüîŕéđ
`prefix`	`s3`	À ķéý þŕéƒîẋ, šö öñé ƃüçķéţ ĥöļđš šéṽéŕàļ þŕöĵéçţš
`region`	`s3`	Ţĥé ƃüçķéţ'š ŕéĝîöñ, ŵĥéñ ţĥé ÀŴŠ çöñƒîĝüŕàţîöñ ñàḿéš àñöţĥéŕ
`endpoint`	`s3`	Ţĥé ƃàšé ÜŔĻ öƒ àñ Š3-çöḿþàţîƃļé šéŕṽîçé öţĥéŕ ţĥàñ ÀŴŠ

À ƒîéļđ ţĥàţ ƃéļöñĝš ţö àñöţĥéŕ ƃàçķéñđ îš ŕéƒüšéđ. Çŕéđéñţîàļš ñéṽéŕ ĝö ĥéŕé: à ĝîţ ƃàçķéñđ üšéš ţĥé ŕéþöšîţöŕý'š öŵñ àççéšš, àñđ àñ Š3 ƃàçķéñđ ţĥé šţàñđàŕđ ÀŴŠ éñṽîŕöñḿéñţ, šĥàŕéđ çöñƒîĝüŕàţîöñ àñđ þŕöƒîļé.

À ĥöšţéđ šéŕṽéŕ ţĥé ŕéçîþé çöññéçţš ţö çàñ àļšö ķééþ ţĥé çöñţéẋţ. Îţš backend ṽàļüé ţàķéš ñö ƒüŕţĥéŕ ƒîéļđ ĥéŕé; ţĥé šéŕṽéŕ'š đöçüḿéñţàţîöñ ĝîṽéš ţĥé ŕéçîþé šĥàþé.

Šĥîþ ĝàţéš

Šĥîþ ĝàţéš šéţ ŵĥéñ ţŕàñšļàţéđ çöñţéñţ îš šĥîþþàƃļé: çöṽéŕàĝé ţĥŕéšĥöļđš öṽéŕ ţĥé ţàŕĝéţ ļîƒéçýçļé ļàđđéŕ (draft → translated → established, ŵĥéŕé established îš ţĥé ŕüñĝ kapi status šĥöŵš àš àþþŕöṽéđ), éñƒöŕçéđ ƃý kapi check --ship àñđ đŕîṽéñ ţöŵàŕđ ƃý kapi up. Ţĥé ḿöđéļ (ļàđđéŕš, đéŕîṽéđ šţàţé, ŕéṽîéŵ) îš đéšçŕîƃéđ îñ ţĥé ķàþî ļööþ, àñđ ţĥé šçĥéḿà ƒöļļöŵš. Àļļ öƒ ţĥéšé ķéýš àŕé ţöþ-ļéṽéļ (šîƃļîñĝš öƒ defaults) àñđ öþţîöñàļ: ŵîţĥ ñöñé šéţ, ñöţĥîñĝ îš ĝàţéđ.

Ƒîéļđ	Ţýþé	Đéšçŕîþţîöñ
`ship_gate`	Ĝàţé	À šîñĝļé çàţçĥ-àļļ ĝàţé: šţàţé ñàḿé → ţĥŕéšĥöļđ
`ship_gates`	ŠĥîþĜàţéŔüļé[]	Šçöþéđ ŕüļéš, éàçĥ à šéļéçţöŕ þļüš à ĝàţé; ŵĥéñ þŕéšéñţ îţ ŕéþļàçéš `ship_gate`
`gates`	ḿàþ	Ñàḿéđ ĝàţé ŕéĝîšţŕý; à `ship_gates` ŕüļé ŕéƒéŕéñçéš àñ éñţŕý ŵîţĥ `gate: <name>`
`source_gate`	Ĝàţé	À ĝàţé öṽéŕ ţĥé šöüŕçé ļàđđéŕ (`written` → `established`)
`established_gate`	Ĝàţé	À šîñĝļé çàţçĥ-àļļ àþþŕöṽàļ ĝàţé, îñ ţĥé šàḿé ţĥŕéšĥöļđ ƒöŕḿ àš `ship_gate`
`established_gates`	ŠĥîþĜàţéŔüļé[]	Šçöþéđ àþþŕöṽàļ-ĝàţé ŕüļéš; ţĥé ḿöšţ šþéçîƒîç ŕüļé ŵîñš

À šçöþé ţĥàţ šĥîþš ĥàš öñé öƒ ţŵö šĥîþ šţàţéš. Îţ šĥîþš àþþŕöṽéđ ŵĥéñ îţ çļéàŕš îţš àþþŕöṽàļ ĝàţé, àñđ ţŕàñšļàţéđ, àš ÀÎ ţŕàñšļàţîöñ, ŵĥéñ îţ çļéàŕš îţš šĥîþ ĝàţé ƃüţ ñöţ àñ àþþŕöṽàļ ĝàţé. kapi status àñđ kapi up þŕîñţ ţĥéšé ŵöŕđš; kapi status --ship àñđ ţĥé šĥîþ-àŵàŕé ļàñĝüàĝé þîçķéŕ šþéļļ ţĥé àþþŕöṽéđ šţàţé established. Ŵîţĥ ñéîţĥéŕ established_gate ñöŕ established_gates šéţ, ñö šçöþé šĥîþš àþþŕöṽéđ. À þŕöĵéçţ ţĥàţ đéļîṽéŕš öñļý àþþŕöṽéđ çöñţéñţ šàýš šö îñ îţš šĥîþ ĝàţé, é.ĝ. ship_gate: { established: 100 }.

À ļöçàļé ñö šĥîþ ĝàţé ŕüļé ḿàţçĥéš îš ñöţ ĝàţéđ. kapi status àñđ kapi up ñàḿé îţ ñöţ ĝàţéđ ŕàţĥéŕ ţĥàñ šĥîþþàƃļé, àñđ kapi status --ship ŕéçöŕđš "state": "not_gated" ƒöŕ îţš ļöçàļé. Ñöţĥîñĝ ĥöļđš à ñöţ-ĝàţéđ ļöçàļé ƃàçķ öñ çöṽéŕàĝé, šö kapi up đéļîṽéŕš îţ üñđéŕ materialize: on-converge àñđ à ļàñĝüàĝé þîçķéŕ öƒƒéŕš îţ. Šţàļé ŵöŕđîñĝ, à ţŕàñšļàţîöñ à ŕéṽîéŵéŕ ţüŕñéđ đöŵñ, à ƒàîļîñĝ çĥéçķ, öŕ ţéŕḿš ţĥàţ ŵéŕé ñöţ çĥéçķéđ ŵîţĥĥöļđ à šçöþé ŵĥéţĥéŕ öŕ ñöţ à ĝàţé ḿàţçĥéš îţ. Éàçĥ šçöþé ŕéàđš àš öñé öƒ ţĥŕéé šĥîþ šţàţéš:

Šţàţé	Ŵĥéñ
`shippable`	À šĥîþ ĝàţé ḿàţçĥéš ţĥé šçöþé àñđ ţĥé šçöþé çļéàŕš îţ, ŵîţĥ ñöţĥîñĝ ŵîţĥĥöļđîñĝ îţ
`withheld`	Ţĥé šçöþé îš šĥöŕţ öƒ à ḿàţçĥîñĝ ĝàţé, öŕ šţàļé, ŕéĵéçţéđ, ƒàîļîñĝ öŕ üñçĥéçķéđ çöñţéñţ ĥöļđš îţ ƃàçķ
`not_gated`	Ñö šĥîþ ĝàţé ḿàţçĥéš ţĥé šçöþé, àñđ ñöţĥîñĝ ŵîţĥĥöļđš îţ

Ĝàţé àñđ ţĥŕéšĥöļđš

À ĝàţé ḿàþš à ļîƒéçýçļé šţàţé ţö à ţĥŕéšĥöļđ. À šçöþé çļéàŕš ţĥé ĝàţé ŵĥéñ, ƒöŕ éṽéŕý ţĥŕéšĥöļđ, àţ ļéàšţ ţĥàţ þéŕçéñţ öƒ îţš ƃļöçķš àŕé àţ ţĥàţ šţàţé öŕ ĥîĝĥéŕ öñ ţĥé ļàđđéŕ. À ţĥŕéšĥöļđ îš à þéŕçéñţ, 0–100; à ţĥŕéšĥöļđ öƒ 0 ḿéàñš "ñöţ ŕéǫüîŕéđ". established: 80 ŕéàđš àţ ļéàšţ 80% àþþŕöṽéđ. Öñļý à þéŕšöñ àþþŕöṽéš à ƃļöçķ, šö àñ established ţĥŕéšĥöļđ àļŵàýš çöüñţš þéöþļé.

Šîḿþļé ƒöŕḿ, öñé ƃàŕ ƒöŕ ţĥé ŵĥöļé þŕöĵéçţ:

ship_gate: { translated: 100, established: 80 }

Éṽéŕý ƃļöçķ ţŕàñšļàţéđ, ţĥé îḿþöŕţàñţ 80% ŕéṽîéŵéđ ƃý à þéŕšöñ; ţĥé ļöñĝ ţàîļ šĥîþš ḿàçĥîñé-ţŕàñšļàţéđ.

Éẋţéñđéđ ţĥŕéšĥöļđš, ţĥé šàḿé šĥàþé ŵîţĥ éẋþļîçîţ pct/by:

ship_gate:
  translated: 100
  established: 100

Ƒüļļý ŕéṽîéŵéđ, ƃüţ àüţöñöḿöüš ÀÎ ŕéṽîéŵš çöüñţ ţöŵàŕđ ţĥé ƃàŕ.

ŠĥîþĜàţéŔüļé

ship_gates îš àñ öŕđéŕéđ ŕüļé ļîšţ. Éàçĥ ŕüļé ĥàš:

Ƒîéļđ	Ţýþé	Đéšçŕîþţîöñ
`when`	Šéļéçţöŕ	Öþţîöñàļ ḿàţçĥ: `locales` àñđ/öŕ `collections` (šţŕîñĝ ļîšţš). Öḿîţţéđ = çàţçĥ-àļļ đéƒàüļţ
`gate`	Ĝàţé öŕ šţŕîñĝ	Àñ îñļîñé ţĥŕéšĥöļđ ḿàþ, öŕ ţĥé ñàḿé öƒ àñ éñţŕý îñ ţĥé `gates` ŕéĝîšţŕý

Àñ éḿþţý šéļéçţöŕ àẋîš ḿàţçĥéš éṽéŕýţĥîñĝ, šö à ŕüļé ŵîţĥ ñö when: îš ţĥé đéƒàüļţ. Ŵĥéñ šéṽéŕàļ ŕüļéš ḿàţçĥ à (çöļļéçţîöñ, ļöçàļé) ƃļöçķ, ţĥé ŕüļé çöñšţŕàîñîñĝ ţĥé ḿöšţ àẋéš ŵîñš ŵĥöļéšàļé; àḿöñĝ éǫüàļ šþéçîƒîçîţý, ţĥé éàŕļîéšţ-ļîšţéđ ŵîñš.

Šçöþéđ ŕüļéš, ŵĥéŕé đîƒƒéŕéñţ šçöþéš àñšŵéŕ ţö đîƒƒéŕéñţ ƃàŕš:

ship_gates:
  - when: { locales: [de] } # contractually reviewed market
    gate: { translated: 100, established: 100 }
  - when: { collections: [Legal] } # regulated content, every locale
    gate: { translated: 100, established: 100 }
  - gate: { translated: 100, established: 80 } # the default

Ñàḿéđ ĝàţéš, đéƒîñéđ öñçé îñ ţĥé gates ŕéĝîšţŕý àñđ ŕéƒéŕéñçéđ ƃý ñàḿé:

gates:
  contractual: { translated: 100, established: 100 }
  machine: { translated: 100, established: 100 }

ship_gates:
  - when: { locales: [de, ja] }
    gate: contractual
  - gate: machine

À ţîéŕéđ þéŕ-ḿàŕķéţ šţŕàţéĝý ƃüîļţ ƒŕöḿ ţĥéšé þîéçéš îš ŵöŕķéđ ţĥŕöüĝĥ îñ Ţîéŕ ĝàţéš þéŕ ḿàŕķéţ.

šöüŕçé_ĝàţé

Ţĥé šöüŕçé-šîđé çöṽéŕàĝé ĝàţé: à ţĥŕéšĥöļđ ḿàþ öṽéŕ ţĥé àüţĥöŕîñĝ ļàđđéŕ (written → established), ĝàţîñĝ ţĥé àüţĥöŕ'š öŵñ çöñţéñţ, ñöţ ţĥé ţŕàñšļàţîöñš.

source_gate: { written: 100 }

Éṽéŕý šöüŕçé ƃļöçķ çļéàŕš îţš ƃöüñđ ṽöîçé àñđ ţéŕḿîñöļöĝý çĥéçķš ƃéƒöŕé kapi check --ship þàššéš. Ļîķé ship_gate, ţĥé ţöþ-ļéṽéļ source_gate îš à çöṽéŕàĝé ƃàŕ éṽàļüàţéđ ƃý kapi check --ship; šöüŕçé đŕîƒţ ñéṽéŕ ƃļöçķš àñ öŕđîñàŕý ƃüîļđ.

defaults.translate_after îš à šéþàŕàţé šéţţîñĝ: ţĥé ļéṽéļ (written / established / none) à ƃļöçķ'š šöüŕçé ḿüšţ ŕéàçĥ ƃéƒöŕé ţĥé ļööþ ţŕàñšļàţéš îţ. Ţĥé çöṽéŕàĝé ƃàŕ àñšŵéŕš îš ţĥé šöüŕçé šĥîþþàƃļé?; ţĥé çöñṽéŕĝéñçé ļéṽéļ àñšŵéŕš ḿàý ţĥîš šöüŕçé ƃé ţŕàñšļàţéđ ýéţ?.

Ķéý Þŕöþéŕţîéš

Ñö çŕéđéñţîàļš: ÀÞÎ ķéýš àŕé ñéṽéŕ šţöŕéđ îñ à ķàþî þŕöĵéçţ ƒîļé. Ţĥéý çöḿé ƒŕöḿ ţĥé ÖŠ ķéýçĥàîñ (kapi credentials add, šĥàŕéđ ŵîţĥ Ķàþî Đéšķţöþ) öŕ ƒŕöḿ éñṽîŕöñḿéñţ ṽàŕîàƃļéš.
Ñö šţàţé: ñö šýñç çüŕšöŕš, çàçĥéš, öŕ ţîḿéšţàḿþš. À ķàþî þŕöĵéçţ ƒîļé îš àļŵàýš çļéàñ àñđ šàƒé ţö çöḿḿîţ.
Þöŕţàƃļé: öñé kapi.yaml þéŕ þŕöĵéçţ ƒöļđéŕ; šĥàŕé ṽîà ĝîţ.
ÇĻÎ-çöḿþàţîƃļé: kapi run flowname -p kapi.yaml

Üšîñĝ ŵîţĥ Ķàþî ÇĻÎ

# Run a flow from a Kapi project
kapi run translate -p kapi.yaml

# Override defaults with CLI flags
kapi run translate -p kapi.yaml --target-lang de --provider openai

# One-shot mode still works without a project
kapi translate -i file.json --target-lang fr

Üšîñĝ ŵîţĥ Ķàþî Đéšķţöþ

Ƒîļé > Öþéñ ļöàđš à þŕöĵéçţ ƃý îţš ƒöļđéŕ (ţĥé öñé çöñţàîñîñĝ kapi.yaml)
Ƒîļé > Ñéŵ Þŕöĵéçţ çŕéàţéš öñé ƒŕöḿ šçŕàţçĥ: à ñàḿé, à ļöçàţîöñ àñđ à šöüŕçé ļàñĝüàĝé
Ƒîļé > Ŕéçéñţ Þŕöĵéçţš ŕéöþéñš öñé ýöü ĥàṽé ŵöŕķéđ îñ ƃéƒöŕé

Ţĥé àþþ öþéñš ţö ýöüŕ þŕöĵéçţš àñđ éđîţš ţĥé ŕéçîþé îñ þļàçé: çöñţéñţ àñđ ĝöṽéŕñàñçé üñđéŕ Þŕöĵéçţ Šéţţîñĝš, ţĥé šţöŕéš üñđéŕ Çöñţéẋţ. Šéé ţĥé đéšķţöþ öṽéŕṽîéŵ.

Šéé àļšö

Ç-01: Þŕöĵéçţ ḿöđéļ: ţĥé àŕçĥîţéçţüŕàļ đéçîšîöñ ƃéĥîñđ ţĥé kapi.yaml ŕéçîþé àñđ îţš éẋţéñšîöñ ḿéçĥàñîšḿ.
ķàþî.ýàḿļ Þŕöĵéçţ Ƒîļé Ƒöŕḿàţ: ţĥé îḿþļéḿéñţàţîöñ ñöţé; ţĥé KapiProject, Defaults, Collection àñđ Profile šţŕüçţ ļàýöüţš, ţĥé ñàḿéđ-çöļļéçţîöñ çöñţéñţ šĥàþé, ṽàļîđàţîöñ ŕüļéš, àñđ ĥöŵ þļàţƒöŕḿ éẋţéñšîöñš đéçöđé üñķñöŵñ ķéýš.
Ƒļöŵ Šţéþš Ƒöŕḿàţ: ţĥé ƒüļļ šţéþ šþéçîƒîçàţîöñ üšéđ ƃý flows.

Đîšçöṽéŕý​

Ƒöŕḿàţ​

Ƒîéļđš​

Ŕéǫüîŕéđ​

Öþţîöñàļ​

Þŕöĵéçţ îđéñţîţý​

Çöļļéçţîöñš​

ÇöñţéñţÎţéḿ​

ƃàšé​

Šöüŕçé àñđ ţàŕĝéţ þàţĥš​

Þŕöƒîļéš àñđ çĥàññéļš​

Ŕéšöļüţîöñ öŕđéŕ​

Đéçļàŕéđ àẋéš​

Ţýþéđ àẋéš​

Þļàçéš​

Þŕöƒîļé ṽàļîđîţý​

Đéƒàüļţš​

ţŕàñšļàţé_àƒţéŕ​

ƒöŕḿàţš​

Ƒöŕḿàţ éñĝîñéš​

ḿéŕĝé​

ḿéḿöŕý​

šéĝḿéñţàţîöñ​

ŕéđàçţîöñ​

ṽöîçé​

Çöñţéẋţ ƒîļéš​

Ƒļöŵ Šţéþš​

Ƒļöŵ ƒîļéš​

Ţéŕḿ ŕüļéš​

Çöñţéẋţ ƃàçķéñđ​

Šĥîþ ĝàţéš​

Ĝàţé àñđ ţĥŕéšĥöļđš​

ŠĥîþĜàţéŔüļé​

šöüŕçé_ĝàţé​

Ķéý Þŕöþéŕţîéš​

Üšîñĝ ŵîţĥ Ķàþî ÇĻÎ​

Üšîñĝ ŵîţĥ Ķàþî Đéšķţöþ​

Šéé àļšö​