JSONC
Translate comment-bearing catalogs with context hints, and know which comments the translated output keeps.
JSONC lets you keep a message and its explanation together. The jsonc file handler reads the comment before a string as a translation hint and translates nested string values by the same paths as JSON.
Maintain those comments in the source catalog. Target reconstruction writes two-space-indented JSON with a trailing newline. It keeps @orphan marks on the same entries as the source and drops every other comment, so a consumer that depends on other metadata needs a separate way to retain it.
Put context next to the intended value #
This catalog explains what “Back” asks the reader to do:
{
/* @context Button that returns to the previous checkout step */
"back": "Back",
"product": "Acme",
}The comment applies to the next string value. It does not apply to every descendant of a containing object. An intervening number, boolean, or null clears the pending hint. Place the comment immediately before the string it describes, and protect fixed identifiers through the selected interface's controls.
With @context, the hint is the rest of that line. Without it, the whole comment becomes the hint, so any nonempty comment placed before a string reaches the translator. When several comments precede a string, the last nonempty hint is used, even if an earlier comment has @context. @orphan marks catalog metadata; the string can still be selected for file translation.
File translation and React catalogs #
React catalog extraction writes flat JSONC catalogs with metadata attached to entries. Its reader understands @context, @src, and @orphan; extraction uses those fields to maintain source locations and mark messages no longer found. That is a catalog-management workflow, separate from translating an arbitrary JSONC document.
Use React catalogs and types when maintaining extracted messages. Do not delete metadata from the source catalog on the assumption that general file output will regenerate it.
Configure file translation #
The CLI infers jsonc from .jsonc; the GitHub App accepts the configured file kind. Select the source and target paths in CLI configuration or GitHub configuration.
Retain the right values #
Incremental comparison, locked and preserved paths, ignored paths, and locale injection follow the JSON file handler's distinctions. Locking copies source data; preserving retains target data; ignoring removes a path. Read JSON for precedence and partial-scope consequences rather than treating these as interchangeable exclusions.
Check keys and protected values in the reconstructed file, then load the target through the application's catalog reader. For React catalogs, keep source metadata available to extraction: the translated target keeps @orphan but not @context or @src.
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 values your application supplies. Review meaning and completeness alongside those structural checks.