LocJSON is a JSON-based file format that Smartcat uses for integration purposes. It is extendable, and allows external integrations to pass a list of units (keys + source text + optional translations), and associate metadata with each unit. Smartcat will automatically identify this format by file extension, .locjson.

Source and target text are represented as an array of strings — you can split long lines arbitrarily for the file to be easier to read.

In its simplest form, a LocJSON file looks like this:

{
    "units": [
        {
            "key": "key1",
            "source": ["String 1"],
        },
        {
            "key": "key2",
            "source": ["String 2"],
        }
    ]
}

Passing comments and additional properties

Each unit in a LocJSON file can have an optional properties object used to pass extra properties. These properties will be preserved in translated documents, allowing external integrations to keep their own metadata. One standard property that is recognized in LocJSON is comments — an arbitrary text that can be displayed to a translator for extra context. All custom property names must start with x-. For example, An external tool MyTool can use something like x-mytool-id to provide internal identifier with each key:

{
    "units": [
        {
            "key": "key1",
            "properties": {
                "comments": ["This is a comment for String 1"],
                "x-mytool-id": "128736688956"
            },
            "source": ["String 1"],
        },
        {
            "key": "key2",
            "properties": {
                "comments": ["This is a comment for String 2"],
                "x-mytool-id": "126406508112"
            },
            "source": ["String 2"],
        }
    ]
}

Smartcat-specific properties

Smartcat recognizes a set of Smartcat-specific properties, all of them start with x-smartcat-.

Unit format: plain text or HTML

// Unit text represents a plain text; Smartcat will display all characters
// in it verbatim, without tag highlighting. This is the default format
// Smartcat will use if this property is not provided
"x-smartcat-format": "plain"   // default

// Unit text is HTML-formatted. Smartcat will parse it and highlight HTML tags
// in the editor
"x-smartcat-format": "html"

Segment splitting mode

// Unit text should be displayed as a single segment, even if it contains
// multiple sentences. This is the default format Smartcat will use if this
// property is not provided
"x-smartcat-split": "none" // default

// Unit must be split into paragraphs. This mode works only with
// "x-smartcat-format": "html"
"x-smartcat-split": "paragraphs"

// Unit must be split by paragrahs and sentences. This mode works for
// plain-text and HTML-formatted units
"x-smartcat-split": "full"

Maximum segment length

// Maximum length of the translation, in Unicode characters.
// If specified, the unit will not be split into sentences
// ("x-smartcat-split": "none" setting will be forced)
"x-smartcat-max-length": <int>

Labels