JSON language pack formats supported by the importer

JSON is a generic file format that can have any structure. Loco tries to detect specific schemas automatically, but recognizes the following structures by default:

Flat

A flat structure will be imported as simple key/value pairs, for example:

{ 
    "hello" : "Hello World", 
}

This will import a single asset with ID "hello" and source text "Hello World"

Nested

Loco supports key folding of nested structures, and will collapse them into flat identifiers. For example:

{
    "pleasantry": { 
        "hello" : "Hello World", 
        "goodbye" : "So long!" 
    }
}

This will import two assets with dot-separated IDs "pleasantry.hello" and "pleasantry.goodbye". The depth of this structure is only limited by our JSON parser (512 levels).

Plurals

Loco identifies plural definitions as either arrays, or objects with keys zero, one, two, few, many, other. In the case of generic schemas, both of these will be detected automatically:

{
    "foo" : [ "%d foo", "%d foos" ],
    "bar" : { "one":"%d bar", "other":"%d bars" }
}

This will import two singular assets with IDs "foo" and "bar" linked to their respective plural forms "foo-plural" and "bar-plural". Read more about how Loco handles plurals.

Warning: Arrays can be misidentified as plurals. If you need to import arrays of translations under the same key, consider using a known schema that supports this feature.

Multiple locales

JSON files containing multiple locales can be imported, as long as there's a top-level key that looks like your locale code. For example:

{
  "fr": {
    "greeting": {
      "hello": "Bonjour tout le Monde"
    }
  }
}

This will import a single asset with ID "greeting.hello". The same key collapsing rules as above are applied, but the top-level locale keys will be discarded.

Be aware that if you specify a locale that does not exactly match a top-level key, Loco will treat the structure as if it were a single locale. That means that if you told Loco that the above example was in Spanish (locale=es) it would not see "fr" as a locale code, and would import an asset called "fr.greeting.hello".

Tip: You can import multiple locales at once via the API if you specify ?locale=auto&format=multi.

Key mapping

Your JSON file may by mapped by Asset IDs or by full source text.

By default Loco assumes object keys are Asset IDs, so if you want to map keys to your source locale you must tell Loco what to do. For example:

{
    "Hello World" : "Bonjour",
}

This will import an English translation and a French translation, but only if you tell Loco that the keys are English and the values are French. See General notes on importing for how to specify the locales.

JSON schemas

The specific formats below are supported in addition to Loco's generic JSON handling.

Some of these schemas can be detected automatically, but not all. It's advised to always tell Loco the specific format of your file. This can be done via the Import API using the format parameter.

ARB

You can import ARB format by using the .arb file extension instead of .json.

Without a file extension, Loco will automatically detect ARB schema if it contains at least one of the standard @@ header keys. Here's an example with the @@locale header:

{
    "@@locale":"en",
    "foo": "Foo",
    "@foo": {
        "description": "This is a foo"
    },
}

Jed

You can import Jed formatted JSON by specifying format=jed, or by letting Loco auto-detect the schema. The latter requires a single outer key that matches the text domain declared in the header message. Here's an example for the "foo" domain:

{
    "foo": {
        "": {
            "domain": "foo",
            "lang": "es-ES",
        },
        "Hello World": [
            "Hola Mundo"
        ]
    }
}

Note that Jed is modelled on Gettext, which means the JSON keys are your source locale. If that's what you intend then you would import this file with index=text&locale=es to map the keys from English to Spanish correctly.

Chrome

Loco supports the format used in messages.json files for Chrome extensions. This can be automatically detected based on the JSON structure, but it's recommended to specify format=chrome.

See Chrome extension docs

i18next

Versions 3 and 4 of the i18next JSON schema can be imported by specifying format=i18next3 and format=i18next4 respectively. Older formats are deprecated in Loco, but for backward compatibility you can specify format=i18next for legacy behaviour.

Although i18next supports context internally, Loco won't parse this into its own context field, because the syntax is ambiguous. Context here can be considered simply a part of the Asset ID.

Warning: This schema cannot be detected automatically so importing without the format parameter can produce unexpected results, particularly if your file contains plural forms.

See i18next docs