Anatomy of a KBF document
The Kapi Bundle Format (.kbf.json) is the interchange format of the kapi toolchain: one deterministic JSON document that carries a source file’s translatable content as blocks of runs, its per-locale targets, and the provenance of every string. It exists so that extraction, translation, validation, and write-back can be separate steps — run by different tools, at different times — without losing structure or identity. This page reads one realistic document part by part, then round-trips it through the engine.
A worked example
One React component, CheckoutBanner, extracted to KBF: a heading with inline markup and a variable — already translated into Norwegian Bokmål — and a plural still awaiting translation. Select a line on the left, or a term on the right, to see what that part of the document is for.
1{2 "schemaVersion": "1.0",3 "kind": "kapi-bundle",4 "created": "2026-05-02T09:30:00Z",5 "generator": {6 "id": "@neokapi/kapi-format-examples",7 "version": "0.0.1",8 "capabilities": [9 "extract",10 "preview"11 ]12 },13 "project": {14 "id": "storefront",15 "sourceLocale": "en"16 },17 "vocabulary": {18 "extends": [19 "common-formatting",20 "rich-jsx"21 ]22 },23 "documents": [24 {25 "id": "checkout-banner",26 "documentType": "jsx",27 "path": "src/CheckoutBanner.tsx",28 "blocks": [29 {30 "id": "banner-heading",31 "hash": "8kQzTf",32 "translatable": true,33 "type": "jsx:element",34 "source": [35 {36 "text": "Your order "37 },38 {39 "pcOpen": {40 "id": "1",41 "type": "jsx:element",42 "subType": "strong",43 "data": "<strong>",44 "equiv": "emph",45 "disp": "strong"46 }47 },48 {49 "text": "#"50 },51 {52 "ph": {53 "id": "2",54 "type": "jsx:var",55 "subType": "string",56 "data": "{orderId}",57 "equiv": "orderId",58 "disp": "orderId"59 }60 },61 {62 "pcClose": {63 "id": "1",64 "type": "jsx:element",65 "subType": "strong",66 "data": "</strong>",67 "equiv": "emph"68 }69 },70 {71 "text": " has shipped."72 }73 ],74 "targets": {75 "nb": [76 {77 "text": "Bestillingen din "78 },79 {80 "pcOpen": {81 "id": "1",82 "type": "jsx:element",83 "subType": "strong",84 "data": "<strong>",85 "equiv": "emph",86 "disp": "strong"87 }88 },89 {90 "text": "#"91 },92 {93 "ph": {94 "id": "2",95 "type": "jsx:var",96 "subType": "string",97 "data": "{orderId}",98 "equiv": "orderId",99 "disp": "orderId"100 }101 },102 {103 "pcClose": {104 "id": "1",105 "type": "jsx:element",106 "subType": "strong",107 "data": "</strong>",108 "equiv": "emph"109 }110 },111 {112 "text": " er sendt."113 }114 ]115 },116 "placeholders": [117 {118 "name": "emph",119 "kind": "element",120 "jsType": "ReactNode",121 "sourceExpr": "<strong>...</strong>"122 },123 {124 "name": "orderId",125 "kind": "variable",126 "jsType": "string",127 "sourceExpr": "order.id"128 }129 ],130 "properties": {131 "file": "src/CheckoutBanner.tsx",132 "line": 12,133 "component": "CheckoutBanner",134 "jsxPath": "CheckoutBanner > h2",135 "element": "h2"136 }137 },138 {139 "id": "banner-items",140 "hash": "3mVd9c",141 "translatable": true,142 "type": "jsx:element",143 "source": [144 {145 "plural": {146 "pivot": "count",147 "forms": {148 "one": [149 {150 "text": "It contains 1 item."151 }152 ],153 "other": [154 {155 "text": "It contains "156 },157 {158 "ph": {159 "id": "1",160 "type": "jsx:var",161 "subType": "number",162 "data": "{count}",163 "equiv": "count",164 "disp": "count"165 }166 },167 {168 "text": " items."169 }170 ]171 }172 }173 }174 ],175 "placeholders": [176 {177 "name": "count",178 "kind": "icu-pivot",179 "jsType": "number",180 "sourceExpr": "order.items.length"181 }182 ],183 "properties": {184 "file": "src/CheckoutBanner.tsx",185 "line": 18,186 "component": "CheckoutBanner",187 "jsxPath": "CheckoutBanner > p > Plural",188 "element": "Plural"189 }190 }191 ]192 }193 ]194}File envelope
The top-level object of a .kbf.json file. kind is the magic string readers sniff to detect the format; schemaVersion carries the MAJOR.MINOR wire contract — a consumer must reject an unrecognized major version and should accept unknown minors, ignoring fields it does not recognize.
Serialization is deterministic: 2-space indent, fields in the pinned order shown here, all map keys sorted, trailing newline. Determinism is what keeps a file's content hash stable across runs, machines, and the two reference implementations.
Round-trip through the engine
The demonstration below runs core/kbf — the canonical Go implementation, compiled to WebAssembly — on a document you can edit. The engine parses the text, renders each block’s preview, validates the run structure against the rules of the specification, writes the document back in canonical form, and resolves a companion .overlays.jsonl annotation overlay anchor by anchor. Nothing is mocked; this is the code the CLI runs.
Conformance results: the KBF conformance suite runs the spec tests against both the Go engine and the TypeScript mirror in your browser. The full schema is in the specification; further editable examples are in Examples.