Þŕöĵéçţš

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

Àđ-ĥöç: öñé-öƒƒ, ñöţĥîñĝ šàṽéđ

Ŕüñ à ţööļ öŕ ƒļöŵ đîŕéçţļý öñ ţĥé ƒîļéš ýöü ñàḿé. Ñöţĥîñĝ îš ķéþţ àƒţéŕ ţĥé ŕüñ.

Ţŕàñšļàţé ţĥîš öñé ƒîļé ţö Ƒŕéñçĥ. · Çĥéçķ ţĥîš ƒöļđéŕ ƒöŕ öƒƒ-ƃŕàñđ ţéŕḿš.

Ţĥîš îš ţĥé ǫüîçķ þàţĥ ƒöŕ à öñé-ţîḿé ĵöƃ, à šçŕîþţ, öŕ à ÇÎ šţéþ. Îñ ţĥé ÇĻÎ ýöü ñàḿé ţĥé ƒîļéš ŵîţĥ ƒļàĝš; îñ Ķàþî Đéšķţöþ ýöü þîçķ ţĥéḿ àš ǫüîçķ ţööļš.

Þŕöĵéçţ: à ŕéçîþé þļüš à ḿéḿöŕý

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

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

	Àđ-ĥöç	Þŕöĵéçţ
Šéţüþ	ñöñé	à kapi.yaml ŕéçîþé (çöḿḿîţ îţ)
Ḿéḿöŕý	ñöţĥîñĝ šàṽéđ	à šţöŕé àççüḿüļàţéš ŵöŕķ (çöñţéñţ ḿéḿöŕý, ţéŕḿš, àþþŕöṽàļš)
Ƒîñđš ýöüŕ ƒîļéš	ýöü ñàḿé ţĥéḿ	đîšçöṽéŕéđ àüţöḿàţîçàļļý
Ţĥé ḿàîñ ṽéŕƃ	kapi <tool> <file>	kapi up, ƃŕîñĝ ţĥé þŕöĵéçţ üþ ţö đàţé
Ƃéšţ ƒöŕ	öñé-öƒƒš, šçŕîþţš, ÇÎ	à ŕéþö ýöü ŵöŕķ öñ ŕéþéàţéđļý

Šéţ öñé üþ: ýöüŕ ƒîŕšţ þŕöĵéçţ. Îñ à þŕöĵéçţ, kapi up ŕüñš ţĥé đéƒàüļţ ƒļöŵ üñţîļ éṽéŕý ĝàţéđ ļöçàļé îš šĥîþþàƃļé öŕ ŵàîţš ƒöŕ ŕéṽîéŵ, kapi status šĥöŵš šţàñđîñĝ, àñđ kapi check --ship éñƒöŕçéš ţĥé ĝàţéš; ţĥé ḿöđéļ ƃéĥîñđ ţĥöšé ṽéŕƃš îš ţĥé ķàþî ļööþ.

Ţĥé ḿéçĥàñîçš: šöüŕçé → ƒļöŵ → šîñķ

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

Ƃîñđîñĝ	Àš šöüŕçé	Àš šîñķ
file (đéƒàüļţ)	ŕéàđ + þàŕšé à ƒîļé	ŵŕîţé ţĥé ƒîļé ƃàçķ (ŕöüñđ-ţŕîþ ṽîà šķéļéţöñ)
store	ţĥé þŕöĵéçţ šţöŕé (ƃļöçķš + öṽéŕļàýš)	çöḿḿîţ öṽéŕļàýš, ñö ƒîļé
îñţéŕçĥàñĝé	îḿþöŕţ ẊĻÎƑƑ / ÞÖ / à ƃîļîñĝüàļ .kpz	éḿîţ öñé ƒöŕ à ţŕàñšļàţöŕ
none	ñ/à	đîšçàŕđ (çĥéçķš/àñàļýšîš öñļý)

• Àđ-ĥöç = ţĥé file ƃîñđîñĝ: ýöü ñàḿé -i/-o.
• Îñ à þŕöĵéçţ, ţĥé đéƒàüļţ šîñķ îš ţĥé šţöŕé (à þŕöçéšš-öñļý ŕüñ); àñ éẋþļîçîţ -o ƒöŕçéš à ƒîļé îñšţéàđ.

À þŕöçéšš-öñļý ŕüñ ķééþš öñļý ŵöŕķîñĝ öüţþüţ: ţĥé ţàŕĝéţ öṽéŕļàýš îţ þŕöđüçéđ, îñ .kapi/work/store.db, üñţîļ ýöü ḿéŕĝé ţĥéḿ. À ŕéṽîéŵ đéçîšîöñ îš ķéþţ éļšéŵĥéŕé: kapi apply ŕéçöŕđš îţ îñ ţĥé þŕöĵéçţ'š çöñţéẋţ šţöŕé, àñđ à ƒļöŵ'š šîñķ ñéṽéŕ ŵŕîţéš đéçîšîöñš. ķàþî çàñ ŕéƃüîļđ ţĥé ŵöŕķîñĝ öüţþüţ ƒŕöḿ ýöüŕ ƒîļéš. Ţĥé đéçîšîöñš àŕé ŵĥàţ þéöþļé àüţĥöŕéđ. Šéé ţĥé þŕöĵéçţ šţöŕé.

--explain þŕîñţš ţĥé ŕéšöļṽéđ ƃîñđîñĝ ŵîţĥöüţ ŕüññîñĝ:

kapi run translate-qa -i app.json -o app.fr.json --explain
#   → flow translate-qa: file(app.json) → file(app.fr.json)
kapi run translate-qa -i app.json --explain          # inside a project
#   → flow translate-qa: file(app.json) → store

Ţŵö þŕöĵéçţ ļööþš, ƃöţĥ éñđîñĝ àţ merge

1. Ţĥé ķàþî ļööþ (ţĥé éṽéŕýđàý öñé): kapi up ŕüñš ţĥé đéƒàüļţ ƒļöŵ öṽéŕ éṽéŕý ļöçàļé šĥöŕţ öƒ îţš ĝàţé àñđ ḿàţéŕîàļîžéš ţĥé ţŕàñšļàţéđ ƒîļéš; ŵĥàţ à ḿàçĥîñé çàñ'ţ ƒîñîšĥ ŵàîţš ƒöŕ ŕéṽîéŵ.

2. Îñţéŕçĥàñĝé ļööþ (ĥàñđ ƃîļîñĝüàļ ƒîļéš ţö à ţŕàñšļàţöŕ öŕ ÇÀŢ ţööļ):

kapi extract --target-lang fr,de     # → out/*.xliff (or --format kpz)
#   …translate the bilingual files…
kapi merge -i out/                   # apply back onto sources, absorb into memory

Šéé ţĥé ƃîļîñĝüàļ ŵöŕķƒļöŵ ƒöŕ ţĥé îñţéŕçĥàñĝé ļööþ îñ đéþţĥ.

Ţĥé .kpz þàŕçéļ: ḿöṽé ŵöŕķ ŵîţĥöüţ à šéŕṽéŕ

À .kpz îš à þöŕţàƃļé šîñĝļé ƒîļé ţĥàţ çàŕŕîéš ŵöŕķ ƃéţŵééñ ḿàçĥîñéš öŕ þéöþļé ŵîţĥöüţ à šéŕṽéŕ. Îţ çöḿéš îñ ţŵö þŕöƒîļéš:

# Whole-project snapshot: a runnable "project in a file"
kapi pack -o snapshot.kpz        # recipe + content + memory & terms
kapi unpack snapshot.kpz         # rehydrate elsewhere

# Bilingual interchange: for a kapi-equipped reviewer
kapi extract --format kpz --target-lang fr
kapi merge bundle.fr.kpz

Šöüŕçé ţŕàṽéļš àš îđéñţîţý + à ŕöüñđ-ţŕîþ šķéļéţöñ ƃý đéƒàüļţ; --with-source éḿƃéđš ţĥé ŕàŵ öŕîĝîñàļš. Þàüšé & ŕéšüḿé à ƃîĝ ŕüñ ŵàļķš ţĥé .kpz ŵöŕķšþàçé ļîƒéçýçļé.

Ŵĥàţ à šñàþšĥöţ çàŕŕîéš

kapi info àñšŵéŕš ţĥîš ƒöŕ ţĥé þŕöĵéçţ ýöü àŕé šţàñđîñĝ îñ (ƃéƒöŕé ýöü þàçķ îţ) àñđ ƒöŕ àñ àŕçĥîṽé ýöü ĥàṽé ƃééñ ĥàñđéđ. Ƃöţĥ ļîšţ ţĥé šàḿé þàŕţš:

Þàŕţ	Ŵĥàţ îţ îš
recipe	ţĥé þŕöĵéçţ'š kapi.yaml, ŵîţĥ ţĥé ṽéñüé ƃîñđîñĝ, hooks àñđ automations šţŕîþþéđ šö ţĥéý ţŕàṽéļ îñéŕţ
sources	šöüŕçé îđéñţîţý + þéŕ-ƒîļé ŕöüñđ-ţŕîþ šķéļéţöñš (ŕàŵ ƃýţéš öñļý ŵîţĥ --with-source)
blocks	ţĥé éẋţŕàçţéđ çöñţéñţ ƃļöçķš (.kbf.json)
overlays	çöḿḿîţţéđ ţàŕĝéţ öṽéŕļàýš, öñé þéŕ ļöçàļé
memory	ţĥé àüţĥöŕîţàţîṽé çöñţéñţ ḿéḿöŕý (.memory.json)
terms	ţĥé àüţĥöŕîţàţîṽé ţéŕḿš (.terms.json)
history	àñ àđṽîšöŕý þŕöṽéñàñçé çĥàîñ (--log)

À šñàþšĥöţ ļéàṽéš öüţ .kapi/work/cache/ (þàŕšé çàçĥé, éẋţŕàçţîöñš àñđ çöļļéçţîöñš, ŵĥîçĥ ķàþî ŕéĝéñéŕàţéš), çŕéđéñţîàļš (ţĥéý ļîṽé îñ ţĥé ÖŠ ķéýçĥàîñ) àñđ šéŕṽéŕ šýñç ţöķéñš. Îţ ĥöļđš öñļý šţàţé ķàþî çàññöţ ŕéçöḿþüţé, ŵîţĥ ñö šéçŕéţš àñđ ñö đéŕîṽéđ đàţà. À þàŕţ ŵîţĥ ñöţĥîñĝ îñ îţ îš àƃšéñţ ƒŕöḿ ţĥé àŕçĥîṽé.

kapi info                        # this project: what a snapshot would capture
kapi info handoff.kpz            # this archive: what it holds
kapi info --output-format json   # either form, machine-readable

Éàçĥ þàŕţ ŕéþöŕţš ŵĥéţĥéŕ îţ îš þŕéšéñţ àñđ ĥöŵ ḿàñý îţéḿš îţ ĥöļđš, ḿéàšüŕéđ ţĥé ŵàý pack çöļļéçţš îţ. sources çöüñţš ŵĥàţ ţĥé éẋţŕàçţîöñ ḿàñîƒéšţš ŕéçöŕđ, ñöţ ŵĥàţ ţĥé ŕéçîþé ţŕàçķš, šö à þŕöĵéçţ ţĥàţ ĥàš ñéṽéŕ ƃééñ éẋţŕàçţéđ ŕéþöŕţš ñöñé. À þàŕţ ţĥàţ îš àƃšéñţ šàýš ŵĥàţ ŵöüļđ þŕöđüçé îţ.

À ŵöŕķšþàçé .kpz îš ţĥé àđ-ĥöç þàŕçéļ ŵîţĥ à šĥàđöŵ çàçĥé. kapi info work.kpz öñ öñé ŕéþöŕţš îţš đöçüḿéñţš, ļöçàļéš àñđ ŵĥéţĥéŕ ţĥé çàçĥé ĥöļđš ŵöŕķ ñöţ ýéţ þàçķéđ ƃàçķ îñţö ţĥé ƒîļé.

pack ŵŕîţéš éẋàçţļý ţĥé þàŕţš info ļîšţš àñđ unpack ŕéšţöŕéš éẋàçţļý ţĥöšé þàŕţš: ţĥé çöñţéñţ ḿéḿöŕý, ţĥé ţéŕḿš, ţĥé ƃļöçķš àñđ öṽéŕļàýš, ţĥé šķéļéţöñš, àñđ, ŵîţĥ --with-source, ţĥé ŕàŵ šöüŕçé ƒîļéš, ŵĥîçĥ unpack ŵŕîţéš ƃàçķ îñţö ţĥé ţŕéé ŵîţĥöüţ öṽéŕŵŕîţîñĝ àñýţĥîñĝ àļŕéàđý ţĥéŕé. Ţö çĥéçķ ţĥé ŕöüñđ ţŕîþ, çöḿþàŕé kapi info öñ à þŕöĵéçţ ŵîţĥ kapi info öñ îţš šñàþšĥöţ. pack ŕéƒüšéš ţö ŵŕîţé àñ àŕçĥîṽé ŵîţĥ ñö çöñţéñţ.

Đö ţĥé ḿöđéš ḿîẋ?

Ýéš: šàḿé çöḿḿàñđš, đéŕéñţ ƃîñđîñĝš:

Ýöü ŵàñţ…	Üšé
À ţĥŕöŵàŵàý ĵöƃ öñ öñé ƒîļé	àđ-ĥöç (kapi <tool> öŕ run -i -o)
À ŕéþö ýöü ŵöŕķ öñ ŕéþéàţéđļý (àççüḿüļàţîñĝ ḿéḿöŕý)	þŕöĵéçţ (add / up / merge)
Ţö ḿöṽé ŵöŕķ ƃéţŵééñ ḿàçĥîñéš/þéöþļé	.kpz þàŕçéļ (pack öŕ extract --format kpz)

À ţööļ ŕüñ îñšîđé à þŕöĵéçţ (kapi translate src/app.json) šţîļļ þîçķš üþ ţĥé þŕöĵéçţ'š đéƒàüļţš àñđ çöñţéñţ ḿéḿöŕý ŵĥîļé ŵöŕķîñĝ öñ öñé ƒîļé. Ţĥé öñé ţĥîñĝ ţö àṽöîđ: ţŵö šţàţéƒüļ šţöŕéš öṽéŕ ţĥé šàḿé çöñţéñţ, àñ àđ-ĥöç .kpz ŵöŕķšþàçé àñđ à ķàþî þŕöĵéçţ ƒöŕ ţĥé šàḿé ƒîļéš. Îñšîđé à þŕöĵéçţ, àñ éẋþļîçîţ -o ŵŕîţéš à ƒîļé àñđ šķîþš ţĥé šţöŕé öñ þüŕþöšé; --explain šĥöŵš ŵĥîçĥ ýöü ĝöţ.

Šéé àļšö

• Ţĥé ķàþî ļööþ: ţĥé đéŕîṽéđ-šţàţé ḿöđéļ ƃéĥîñđ up, status, ĝàţéš, àñđ ŕéṽîéŵ.
• Šĥîþ ĝàţéš & ÇÎ: éñƒöŕçé ţĥé ĝàţéš ŵîţĥ kapi check --ship.
• Ƒļöŵš: àüţĥöŕîñĝ çöḿþöšéđ ƒļöŵš àñđ ţĥé šöüŕçé/šîñķ éñđš.
• kapi.yaml þŕöĵéçţ ƒîļé: ţĥé ŕéçîþé ƒöŕḿàţ.