Translation JSON Format

The translation JSON format is used in File Mode and is produced by the export endpoints.

Full structure

{
  "languages": ["fr", "zh-CN", "es"],
  "languageNames": {
    "fr": "Français",
    "zh-CN": "Simplified Chinese",
    "es": "Español"
  },
  "translations": {
    "fr": [
      { "key": "Hello", "context": "", "value": "Bonjour" },
      { "key": "Delete", "context": "button", "value": "Supprimer" },
      { "key": "Welcome back, {{text:0}}", "context": "", "value": "Bon retour, {{text:0}}" }
    ],
    "zh-CN": [
      { "key": "Hello", "context": "", "value": "你好" }
    ]
  },
  "timestamp": 1715000000000
}

Fields

languages (string[])

Language codes present in the file. Drives the widget's language picker list.

languageNames (object)

Human-readable names for each language code.

translations (object)

Keys are language codes. Each value is an array of translation objects:

Field	Type	Description
key	string	Phrase text, possibly with slot tokens (e.g. "You have {{number:0}} tasks")
context	string	DOM context for disambiguation (empty string if none)
value	string	Translated text, with slot tokens preserved

timestamp (number)

Unix milliseconds. Used by Loco.pullLatest() to decide whether the cached file is stale.

Export endpoints

Endpoint	Description
GET /api/export	All languages, all approved phrases
GET /api/export/:lang	Single language only

Both require the X-API-Key header.

Context disambiguation

The same key can appear multiple times in the array with different context values. When looking up a translation, Loco checks key + context first, then falls back to key alone:

// lookup order:
translations["Delete\x00button"]  // context-specific
  ?? translations["Delete"]       // fallback

This lets you translate "Delete" differently in a button vs. a menu item.