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-.

Dealing with ICU-style plurals

These properties are defined on a document or unit level:

// How to handle strings with ICU MessagFormat syntax

// Do not parse, display raw ICU MessagFormat strings
"x-smartcat-icu-messageformat-mode": "raw"   // default

// Convert a subset of ICU MessagFormat strings to regular plural segments.
// If parsing fails, we will fall back to "raw" behavior
"x-smartcat-icu-messageformat-mode": "parse"

// Should we try to autodetect ICU messageformat strings?

// Do no automatic detection
"x-smartcat-autodetect-icu-messageformat": "no"   // default

// Autodetect ICU MessageFormat strings.
"x-smartcat-autodetect-icu-messageformat": "yes"

Unit format: plain text, HTML or ICU MessageFormat

// 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"

// Unit text represents an ICU MessageFormat string that contains plurals. This skips any autodetection, but whether the plural string will be parsed and represented as multiple segments in Smartcat is defined by "x-smartcat-icu-messageformat-mode" setting
"x-smartcat-format": "icu-messageformat"

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"