Configuration file

The CLI reads transglot.json from the folder you run it in. transglot init writes one for you; this page describes every field so you can write or change it by hand. Pass --config <path> to read a file from somewhere else.

{
  "url": "https://api.transglot.ai",
  "sources": [
    { "path": "locales/{locale}.json", "format": "json_nested" }
  ],
  "pull": [
    { "path": "locales/{locale}.json", "format": "json_nested" }
  ]
}

push uploads the files the sources rules name. pull writes the files the pull rules name. The two lists are independent, so you can pull into a different layout or format from the one you push.

Top-level fieldsCopy Anchor Link

The file must be a JSON object with only these three fields. Any other field stops the CLI with Unknown config field "<name>". Allowed fields: url, sources, pull.

url is required unless TRANSGLOT_URL is set. For transglot it is https://api.transglot.ai.

Rule fieldsCopy Anchor Link

Each entry in sources and pull is a rule: one path template, one file format, and the locales it applies to.

Locale placeholdersCopy Anchor Link

{locale} is replaced by each locale the rule covers, everywhere it appears in the path. With "locales": ["fr", "de"], the path locales/{locale}/common.json stands for locales/fr/common.json and locales/de/common.json.

When a pull rule leaves locales out, {locale} is filled with each locale's id as transglot stores it, such as fr or pt_BR. If your files spell locales differently, for example pt-BR, list them in your spelling. transglot accepts any letter case and either - or _ as the separator, so "locales": ["fr", "pt-BR"] writes pt-BR.json and still reads the project's pt_BR translations.

A locale used in a path must be a plain tag of letters, digits, - and _. Every planned path must stay inside the folder you run the CLI in, symbolic links included. Two locales that would land on the same file are refused before anything is sent: a rule that covers more than one locale needs {locale} in its path.

A sources rule can name a locale other than the source. push then uploads that file as existing translations for that locale. The locale must already be a language of the project: push never adds one, and answers Locale "<locale>" is not configured on this project. Push never adds locales.

FormatsCopy Anchor Link

Every rule names one of these formats. transglot init detects it from your files.

unity_csv and unreal_po are the game engine formats (Unity string tables and Unreal .po catalogs). Each format has its own page under File formats.

Several rulesCopy Anchor Link

A project can have as many rules as you have files. List one rule per file family; the same locale can appear in several rules.

{
  "url": "https://api.transglot.ai",
  "sources": [
    { "path": "locales/{locale}/common.json", "format": "json_nested" },
    { "path": "locales/{locale}/checkout.json", "format": "json_nested" }
  ],
  "pull": [
    { "path": "locales/{locale}/common.json", "format": "json_nested" },
    { "path": "locales/{locale}/checkout.json", "format": "json_nested" }
  ]
}

push uploads the files of one locale at a time, in the order the rules first mention each locale, so list your source locale first. Files of the same locale upload in parallel.

With several source files for one locale you cannot use push --sync-removals: each upload would delete the keys the other files define. The CLI refuses that combination before it uploads anything.

Key metadata sidecarCopy Anchor Link

A key's description is the context translators and Glossa read, and its max_length is the limit a translation is checked against. Formats such as json_flat, json_nested, android_xml or ios_strings have nowhere to store either, so a sources rule can name a sidecar file that does (CLI 0.5.0 and later).

{
  "url": "https://api.transglot.ai",
  "sources": [
    {
      "path": "messages/{locale}.json",
      "format": "json_nested",
      "metadata": "i18n/en.meta.json"
    }
  ],
  "pull": [
    { "path": "messages/{locale}.json", "format": "json_nested" }
  ]
}

{
  "cart.title": { "description": "Heading of the cart page", "max_length": 40 },
  "cart.items": { "description": "Item count under the cart heading" },
  "legacy.banner": { "description": null }
}

• Keys are the project's key names, dotted the way the project stores them.
• A field you leave out is not changed; null clears it.
• max_length is a whole number from 1 to 100000. description is at most 2,000 characters.
• The file is at most 1 MiB and 50,000 keys, and names each key once.

push reads and checks the sidecar before it uploads anything, so a bad sidecar stops the run with nothing sent. The sidecar travels with the rule's source-locale upload, which goes after that locale's other files, so keys a sibling file creates exist by the time their descriptions arrive.

The CLI refuses, as a configuration error:

• metadata on a pull rule;
• a sidecar path with a {locale} or any other {…} placeholder (a rule has exactly one sidecar);
• a rule that plans no upload, or more than one, for the source locale;
• a sidecar path outside the working folder, including through a symbolic link;
• a format that carries descriptions in the file itself: flutter_arb, xliff_12, ios_xcstrings, gettext_po, csv, xlsx, unity_csv and unreal_po.

ExamplesCopy Anchor Link

{
  "url": "https://api.transglot.ai",
  "sources": [
    { "path": "public/locales/{locale}/translation.json", "format": "json_nested" }
  ],
  "pull": [
    {
      "path": "public/locales/{locale}/translation.json",
      "format": "json_nested",
      "locales": ["fr", "de", "pt-BR"]
    }
  ]
}

Validation errorsCopy Anchor Link

The CLI checks the whole file before it sends a request and exits with code 1 on the first problem. The messages name the field, for example:

error: Config field "url" is required (or set TRANSGLOT_URL).
error: Unknown config field "sources[0].file". Allowed fields: path, format, locales, min_state, metadata.
error: Config field "pull[0].min_state" must be "human_edited" or "reviewed".
error: Config field "pull[0].metadata" is only allowed on a sources rule.

See Exit codes for how to handle them in a pipeline.