Gå til hovedinnhold

Choosing a format

Most of the time the answer follows from one question: is this file staying inside kapi, or leaving it?

Native or interchange​

kapi's own formats are lossless. The industry interchange formats it also reads and writes (XLIFF and PO for content, TMX for content memory, TBX for terms) are a deliberately lossy tier. They drop the fields that make kapi's data useful inside kapi: entity and concept cross-links, per-entry provenance, the term-source (brand_vocabulary) and competitor flags, and free-form properties.

On the command line the native tier is spelled bundle, not json. kapi terms export --format json also produces JSON, but it carries no relations at all and has no kind marker, so a reader cannot identify it by sniffing. The two names keep the two outputs apart.

You are…Reach for
Moving content between kapi commandsThe native bundle
Putting terminology in a pull request.kapi/terms.json, written by kapi terms export
Handing one task to a translatorA kapi-interchange .kpz
Archiving or transferring a whole projectA kapi-project .kpz
Feeding a third-party CAT tool or TMSXLIFF
Feeding a third-party memory or terminology toolTMX or TBX
Loading strings in a running applicationNeither; compile to a runtime catalog

Use an interchange format when the recipient is outside this project, and accept the loss knowingly. Use a native format everywhere else.

Bundle or project archive​

Both are native and lossless. Choose by asking whether the recipient already shares your project context. Size does not decide it.

A content bundle is one document's blocks and targets. A project archive is a manifest plus one member per content type, so it additionally carries the content memory, the terms, the skeletons, the source bytes, and a Merkle root hash over all of it.

  • Reach for a bundle when the recipient already has the same memory and terms (another step in your own pipeline, say).
  • Reach for a .kpz when they do not: a handoff, an archive, or a resumable run.

Unpacking a .kpz can seed a fresh content memory, terms store and block store, and the regenerable caches rebuild faithfully. A bundle carries none of that context, so it cannot seed them.

Content bundle versus XLIFF​

XLIFF is the OASIS standard for exchanging content between translation tools. KBF serves the same purpose inside the neokapi toolchain. Most concepts map cleanly between the two, but they differ in structure, segmentation and serialization.

The comparison targets XLIFF 2.2, which is published in two parts: Part 1 (Core), the structural and inline model every conformant tool understands, and Part 2 (Extended), a set of optional modules (Translation Candidates, Glossary, Validation, Plural/Gender/Select, and more). The table below marks each capability that lives in an Extended module, because older XLIFF 2.0 / 2.1 tools and some CAT tools support only some of the modules.

neokapi has two interchange formats, for different recipients. A task-scoped bilingual .kpz (the kind: kapi-interchange profile of the package) is the native one. It is lossless and holds inline codes, content memory and term context in one file, for a translator or reviewer working in kapi or the neokapi review tool. XLIFF is the industry-interop tier. neokapi reads and writes it for third-party CAT tools and TMS platforms that cannot read .kpz. Both travel through kapi extract / kapi merge (see the bilingual workflow); --format picks the carrier. KBF is also the internal content representation the pipeline operates on.

Concept mapping​

KBFXLIFF 2.2Notes
File envelope<xliff> rootKBF carries generator/project/vocabulary metadata; XLIFF carries version/srcLang/trgLang.
Document<file>One source artifact's worth of content.
(no structural grouping)<group>XLIFF can nest <group>s for hierarchy; KBF blocks are flat within a Document.
Block<unit>What translation tracking follows.
source edition (editions[""])<segment><source> contentKBF has no structural segment; XLIFF wraps source/target in one or more structural <segment>s per <unit>.
editions map (key → Edition)<segment><target>KBF holds every edition in one file: many languages, and tone or channel editions of one; XLIFF is bilingual: one trgLang per document.
edition status<segment state>KBF records one state per edition (draft → translated → established, shown as approved); XLIFF one per segment (initial → translated → reviewed → final, + subState).
text runcharacter data
ph run<ph> (standalone code)KBF carries the original token inline in data; XLIFF references native data via <originalData>/dataRef.
pcOpen / pcClose<pc> (or <sc> / <ec>)A paired code wrapping content. XLIFF distinguishes well-formed <pc> from overlapping <sc>/<ec> spans.
RunConstraints (per-run)canCopy / canDelete / canReorder / canOverlapBoth formats encode per-code editing rules; XLIFF's are a standardized inline-code attribute set.
sub runsubFlows / subFlowsStart/subFlowsEnd (referenced <unit> ids)Embedded content extracted by a subfilter.
plural / select runPlural, Gender, and Select Module (Extended, urn:…:xliff:pgs:1.0)First-class in KBF Core; in XLIFF an Extended module added in 2.2, with no standard representation before 2.2.
Placeholder metadatacode metadata + <originalData>KBF declares every placeholder once per block for validation.
BlockProperties (file/line/…)<note> / Metadata moduleProvenance for translators and tools.
.overlays.jsonl annotations<mrk> / <sm>/<em> inline markers + Metadata moduleKBF keeps annotations stand-off in a separate file; XLIFF inlines them.
Validation kindsValidation Module (Extended)Different scope; KBF's built-in checks are placeholder- and paired-code-centric.
(none)Translation Candidates, Glossary, Format Style, Resource Data, Size/Length Restriction, ITSXLIFF's Extended modules; KBF has no equivalents (see below).

Design differences​

JSON vs XML. KBF is JSON with a deterministic serializer (sorted map keys, fixed field order, 2-space indent, no HTML escaping, trailing newline), so a document hashes stably and diffs cleanly in git. XLIFF is XML, where equivalent documents can serialize many ways (attribute order, whitespace, namespace prefixes), which makes content hashing and line-diffing harder.

Inline model. A KBF Run carries its original token inline (data), so a block's runs are self-contained. XLIFF separates the displayed code from its native data (<originalData>/<data> referenced by dataRef, dataRefStart/dataRefEnd), which de-duplicates repeated codes and is robust, at the cost of a layer of indirection.

Segmentation is an overlay. XLIFF makes <segment> a structural child of <unit>, and gives each segment its own translation state. KBF has no Segment type. Segmentation is an opt-in stand-off overlay anchored to run-index ranges (F-02). A block is always a flat Run[], and its segmentation is metadata on top of that sequence.

Plural and select. ICU plural and select constructs are first-class Core runs in KBF (a pivot plus a map of Run[] per form), so markup and placeholders inside a clause stay first-class and any tool can reason about the whole group. XLIFF gained an equivalent only in 2.2, as the optional Plural, Gender, and Select Module in Part 2 (Extended); XLIFF 2.0 / 2.1 had no standard plural representation, and Core-only or older tooling still does not understand the module. Every KBF reader handles plural and select; an XLIFF tool handles them only if it implements the module.

Stand-off annotations. KBF annotations live in a companion .overlays.jsonl JSON-Lines file, anchored to blocks by block / run / range / form anchors. They sit outside the .kbf.json content, so re-extracting source leaves them in place and a validator can detect orphaned anchors. XLIFF expresses annotations inline with <mrk>/<sm>/<em> and through the Metadata module, interleaved with the content.

Multi-target. A single KBF file can hold translations for many locales, and tone or channel editions of one language, in each block's editions map. XLIFF is bilingual by design: a document declares one srcLang and one trgLang.

Where XLIFF is the stronger choice​

KBF is a deterministic content-exchange format for the pipeline, with a narrow scope. XLIFF is a mature, broad industry standard, and it is the better choice in these areas:

  • Industry interoperability. XLIFF is the lingua franca of translation vendors, CAT tools (Trados, memoQ, Phrase, …) and TMS platforms. Handing off to a human translation supply chain means XLIFF.
  • A translation workflow state machine. XLIFF's per-segment state (initial → translated → reviewed → final) plus subState models the lifecycle of a translation through review, segment by segment. KBF records one coarser status per edition and carries no review sub-states.
  • Inline memory and MT match suggestions. The Translation Candidates module carries scored translation suggestions (<mtc:matches>) right next to the block they apply to. KBF has no inline match-candidate representation; matches stay in the content memory.
  • A rich, standardized module ecosystem. XLIFF 2.2 Extended defines Glossary, Format Style, Metadata, Resource Data, Size and Length Restriction (enforce length limits on translations), Validation (declare validation rules in the file), and an ITS Module that bridges to the W3C Internationalization Tag Set. KBF has none of these. Separate neokapi subsystems and .overlays.jsonl annotations cover the same concerns outside the file format.
  • Formal conformance and processing requirements. XLIFF specifies how a conformant Agent must behave, e.g. an agent MUST preserve XLIFF-defined elements it does not understand, and MUST NOT alter the <skeleton>. These rules let a chain of independent tools work safely on the same document.
  • Standardized skeleton handling. XLIFF's <skeleton> and original-data model is part of the standard, so any conformant merger can reconstruct the source. KBF's skeleton is an opaque, neokapi-internal payload.

When to use which​

Use KBF when you are operating inside the kapi/neokapi pipeline: feeding blocks to an AI or MT step, exchanging content between tools, hashing or diffing extractions, or carrying several target locales in one artifact. Its JSON shape and deterministic serialization suit programmatic and AI-driven workflows.

Use XLIFF when you need to interoperate with the wider translation industry (handing content to a translation vendor, or round-tripping through an external CAT tool or TMS), or when you need the workflow state, match candidates, or Extended modules described above. kapi extract can write XLIFF and kapi merge can read it, so one project can use both formats.

See also​