Skip to content
screenjson

Schema & data

Localise dialogue into multiple languages

Add translated text to a ScreenJSON document by merging language-keyed entries into each element's text map.

Last updated January 2026

The merge pattern

Every text field in ScreenJSON is a map. To add French, merge a new key alongside the existing "en":

{
  "text": {
    "en": "We have ninety seconds.",
    "fr": "Nous avons quatre-vingt-dix secondes."
  }
}

Produce a translation bundle

Emit a flat, TMS-friendly bundle keyed by element UUID:

jq '[
  .document.scenes[].body[]
    | select(.text != null)
    | { id, en: .text.en }
]' screenplay.json > bundle-en.json

Ingest a completed translation

Assume your TMS returns bundle-fr.json, a map of { id: text }:

jq -s '
  (.[0]) as $doc | (.[1]) as $fr
  | $doc
  | .document.scenes |= map(
      .body |= map(
        if .text != null and $fr[.id]
        then .text += { fr: $fr[.id] }
        else .
        end
      )
    )' screenplay.json bundle-fr.json > screenplay-multilang.json

Render in a specific language

screenjson export -i screenplay-multilang.json -f fdx --lang fr -o script-fr.fdx

Picking the right key at read time

function pickText(map: Record<string, string>, preferred: string, fallback = 'en') {
  return map[preferred] ?? map[fallback] ?? Object.values(map)[0] ?? '';
}

Next