JSON format (.json)

The JSON format reads JSON documents, extracts string values as translatable blocks, and writes the translated values back into the same structure. It is the common format for web and application resource files (i18next, Chrome extension messages, generic key/value catalogues).

By default every key/value string pair is extracted. From there you can narrow extraction with a key-exception or extraction pattern, control how block names are derived from keys, route specific keys to notes, IDs, or metadata, and hand embedded markup (HTML inside a value) to a subfilter. Two presets are provided — Chrome Extension and i18next — as starting points for those layouts.

IDjson

SourceBuilt-in

Extensions.json

MIME Typesapplication/json

CapabilitiesRead + Write

How kapi reads it

Parameters

Parameter	Type	Default	Description
`codeFinderRules`	array		Regex patterns that match inline codes within translatable text.
`escapeForwardSlashes`	boolean	true	Escape forward slashes in output JSON (\/).
`exceptions`	string		Regex pattern for key names. When extractAllPairs is true, matching keys are excluded. When false, matching keys are included.
`extractAllPairs`	boolean	true	Extract all key-value pairs for translation. When false, use extractionRules to specify which paths to extract.
`extractionRules`	string		Regex pattern for JSON paths to extract. Overrides extractAllPairs when specified.
`extractIsolatedStrings`	boolean	false	Extract string values in arrays (without keys) as translatable blocks.
`genericMetaRules`	string		Regex for keys whose values become generic metadata.
`idRules`	string		Regex for keys whose values become Block IDs (overrides useKeyAsName).
`maxwidthRules`	string		Regex for keys whose values set max width constraints.
`maxwidthSizeUnit`	string	pixel	Size unit for maxwidth.
`noteRules`	string		Regex for keys whose values become translator notes.
`subfilter`	string		Global subfilter format name (e.g., 'html') applied to all or matching extracted strings.
`subfilterRules`	string		Regex matching keys for which values should be processed with the sub-filter.
`subfilters`	array		Array of {pattern, format} mappings for embedded content in specific keys.
`useCodeFinder`	boolean	false	Enable pattern-based detection of inline codes (placeholders, tags, etc.).
`useFullKeyPath`	boolean	false	Use full path (/key1/key2) instead of immediate key as name.
`useIdStack`	boolean	false	Build TextUnit IDs from nested key stack.
`useKeyAsName`	boolean	true	Use JSON key as the Block (TextUnit) name for reference.
`useLeadingSlashOnKeyPath`	boolean	true	Include leading slash in key path names.

Configure these parameters interactively and copy the YAML on the Format Reference.

Examples

Extract a subset of keys

Translate only keys under the messages and labels objects.

extractionRules: "/messages/.*|/labels/.*"

Notes from description keys

Attach description values as translator notes (Chrome extension style).

extractAllPairs: false
exceptions: "^message$"
noteRules: "^description$"

HTML inside values

Parse HTML markup within values whose key ends in _html (i18next style).

subfilter: html
subfilterRules: "_html$"
useFullKeyPath: true

Processing notes

String values become translatable blocks; objects, arrays, and non-string scalars form the surrounding non-translatable structure.
Note, ID, generic-metadata, and max-width rules attach to the next translatable block rather than producing content of their own.

Limitations

The match target for the rule-based regex patterns is either the immediate key or the full key path, depending on useFullKeyPath — not both.

← Back to the Format Reference