Þŕöĵéçţš

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

--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 ļööþ (ţĥé éṽéŕýđàý öñé): 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 öñ à þŕöĵéçţ àñđ öñ îţš šñàþšĥöţ îš ţĥéŕéƒöŕé ţĥé ŕöüñđ-ţŕîþ çĥéçķ. pack ŕéƒüšéš ţö ŵŕîţé à çöñţéñţ-ļéšš àŕçĥîṽé ŕàţĥéŕ ţĥàñ ĥàñđ öṽéŕ àñ éḿþţý ƒîļé.

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

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

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

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

Šéé àļšö

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