JSON

Translate nested string values while controlling which paths are copied, retained, omitted, or updated.

In a JSON catalog, the application looks up a key and displays its value. The json file handler changes string values while keeping object keys, array positions, numbers, booleans, and null values as data. It reconstructs the target from the current source, inserting new translations or retained target text.

The handler supports nested object and array catalogs, as well as a string at the root. The CLI infers json from .json. Configure the source through CLI configuration or the GitHub App.

What becomes a translation task #

For example:

json
{
  "checkout": {
    "title": "Complete your order",
    "delivery": "Delivery within {days} days"
  },
  "plans": [
    { "name": "Personal", "seats": 1 },
    { "name": "Team", "seats": 10 }
  ],
  "enabled": true
}

The handler selects checkout.title, checkout.delivery, plans[0].name, and plans[1].name. It leaves the seats numbers and enabled boolean unchanged. Protect string-valued identifiers explicitly: a value's JSON type tells the handler that it is text, not whether people should read it.

The short path form uses dots for object traversal and brackets for array positions: checkout.title selects a nested value and plans[0].name selects the first plan's name. For a literal key named checkout.title, use the quoted JSONPath form $['checkout.title']. See key controls for selection syntax.

How updates reuse existing translations #

An incremental run uses three distinct inputs:

InputRole
Current sourceDefines the structure and strings for the new output.
Previous sourceEstablishes whether a source string at a matching path changed.
Existing targetSupplies translations that can be retained.

When the previous source and existing target are available, a new or changed source string becomes a translation task. An unchanged source string can reuse the existing target value at the corresponding path. Two keys with the same English text remain separate records; they may have different accepted translations because their contexts differ.

For example, changing checkout.title does not by itself require translating checkout.delivery again. If the latter's source value is unchanged and its target value is available, the target can carry forward. A change to a number or other structural data can still require reconstructing the file even when there are no new strings to translate.

Keep the previous source paired with the accepted target. If either is missing, the handler treats the strings as a first pass. The CLI's lockfile and cache connect those inputs across runs.

Choose what happens to protected paths #

These controls have different output consequences:

ControlTranslation behaviorOutput behavior
Locked pathExcluded from translation.Takes the value from the current source.
Preserved pathExcluded from translation.Keeps the existing target value when that path exists; otherwise the source value remains.
Ignored pathExcluded from translation.Removes the path from the produced target.
Locale injectionThe configured locale field is excluded from translation.Writes the target locale into that field.

Lock a shared identifier when every locale must use the source value. Preserve a target-specific URL when each locale owns its destination. Ignore a source-only note when it must not appear in the translated file. These choices are not synonyms for “do not translate.”

At the same path, locking takes precedence over preservation, so a value in both lists comes from the source. Ignoring removes the value even when it is also locked, preserved, or selected for locale injection. An injected locale takes precedence over locking and preservation at its location. Prefer one owner for each value and inspect the output when rules overlap across an object or array.

Removing an array element shifts the positions of later elements. Review the resulting array as data, not only as translated text. Locale injection can create missing object containers. When writing into an array, use an existing element or the next position after its end; a path that creates gaps or crosses an incompatible value fails.

Set these controls with the CLI file-entry fields or GitHub file-entry options.

Scope and reconstruction limits #

A key refresh merges the selected translations into the existing target. Unselected target values, target-only keys, and omissions remain; source-only keys outside the scope are not added. Array writes must not create gaps. For example, selecting a second array element cannot fill an absent first element for you. Inspect the complete target after a partial update.

JSON output is serialized with two-space indentation and a trailing newline. Do not expect byte-for-byte preservation of whitespace or comments. For comment-bearing source files, read JSONC, and check the consuming system's requirements before treating a rewritten file as equivalent.

The translation workflow checks supported placeholder and ICU structure, including changed or missing arguments. Inspect reported warnings or failures, then render the accepted template with the application's values. These checks do not assess whether the translated message expresses the intended meaning.

Load the output in the application with representative values. Check that protected paths retain the intended source or target data, and that the delivery message still expresses the same promise after substitution. Parsing verifies JSON syntax; rendering and reading verify the message people receive.