Gå til hovedinnhold

Kapi Localization Format (KLF)

The Kapi Localization Format is the JSON wire serialization of neokapi's content model. Where the in-memory model carries the full runtime Block — skeleton, overlays, annotations, identity — KLF is the on-disk, language-neutral form of the same data: a set of Documents, each holding Blocks whose translatable content is a flat sequence of Runs, with optional per-locale targets. It plays the role XLIFF plays in other toolchains: a structured exchange format that moves extracted content between an extractor, a translation step, and a merge step without losing inline markup, placeholders, or plural/select structure.

KLF files use the .klf extension and the MIME type application/vnd.neokapi.klf+json. Stand-off annotations live in a companion .klfl overlay file.

What it is for​

Use KLF when you need a faithful, diff-friendly, hashable representation of translatable content:

  • feeding extracted blocks to an AI or MT translation step,
  • exchanging content between tools,
  • persisting an extraction for later merge.

The serializer is deterministic — 2-space indent, no HTML escaping, sorted map keys, trailing newline — so the byte output is stable for content hashing and for reviewing changes in git.

What it is not for​

KLF is an authoring and exchange format, not a runtime catalog. It is intentionally heavy: it carries the data shape that lets translators work, that tools like kapi pseudo-translate round-trip, and that a review platform can persist. That richness is waste at runtime, where the only operation is (scope, source) → translated. Compile KLF down to an established runtime catalog format (gettext MO, compact per-locale JSON, ICU) for the running application; keep KLF on the pipeline side.

Two implementations, one format​

KLF has two reference implementations kept byte-for-byte equivalent by shared golden fixtures:

  • Go — canonical. core/klf in the framework module. Where the two sides differ, the Go source governs.
  • TypeScript — mirror. The @neokapi/kapi-format package, used by the React extractor and the in-browser tooling.

You can watch the two engines agree, live, on the KLF conformance page — it runs the spec conformance suite against both implementations in your browser.

In this section​

  • Specification — the normative schema: the file envelope, the run discriminated union, per-locale targets, validation rules, and the .klfl annotation overlay.
  • Examples — worked examples of every run kind, a full .klf + .klfl pair, and an embedded lab to edit them live.
  • KLF vs XLIFF — how KLF maps onto XLIFF 2.x, and where the two formats differ in philosophy.
  • The KLF family & .klz package — the native lossless formats for translation memory and termbase, and the .klz package that bundles a whole project — versus the lossy interchange formats (XLIFF/PO, TMX, TBX).
  • KLF Lab — edit a .klf document and watch the real engine parse, canonicalize, render, validate, and resolve annotations against it.
  • KLF Tests — the cross-engine conformance suite.