Skip to main content

Kapi Bundle Format (KBF) format (.kbf.json, .klf)

This format reads and writes the Kapi Bundle Format (.kbf.json), a structured JSON envelope for translatable strings extracted from source code such as JSX / React components. A KBF document is a kind: kapi-bundle envelope holding one or more documents, each carrying blocks. Every block has a structured run sequence: text plus placeholders, paired inline codes, plurals, and selects.

On read, each KBF block becomes one translatable block. Its source text is the flattened run sequence: placeholders contribute their equivalent (wrapped in braces), paired codes elide their wrappers, and plural forms collapse to the other branch. The block ID is carried verbatim, and the full structured run graph travels alongside in an annotation so the writer can reassemble the original document. The writer reverses the process; a block that arrives without that annotation (for example one inserted by an intermediate tool) is written as a minimal text-only run sequence so the file stays well-formed.

IDkbf
SourceBuilt-in
Extensions.kbf.json, .klf
MIME Typesapplication/vnd.neokapi.kbf+json
CapabilitiesRead + Write

This format has no configurable parameters.

Examples

Round-trip a KBF document

No configuration is required. Declare the format to read a .kbf.json envelope and write it back after translation.

format:
  name: jsx

Processing notes

  • One translatable block per KBF block; the block ID is preserved verbatim.

  • Source text is the flattened run sequence, where placeholders become brace-wrapped equivalents, paired codes elide their wrappers, and plurals collapse to the other branch.

  • Translator-facing context (file, component, element, JSX path, line, notes) and the structured runs travel in a block annotation for faithful round-tripping.

  • A catalog extracted by @neokapi/i18n-react 1.2.3 carries the suffix .klf and that release's own root marker. It reads as any other bundle, and the current kapi-bundle envelope is written back.

Limitations

  • This is a neokapi-specific exchange format; the okapi-bridge daemon ships no equivalent filter.

  • Blocks that lose their structured-run annotation in the pipeline are written back as plain text, without the original placeholder or paired-code structure.

← Back to the Format Reference