Skip to main content
Every user-facing text field in ScreenJSON is a map keyed by BCP 47 language tag, not a plain string. 
{
  "text": {
    "en": "We have ninety seconds.",
    "fr": "Nous avons quatre-vingt-dix secondes.",
    "ja": "九十秒しかない。"
  }
}

​
Two map types

TypeMax length per valueWhere it’s used
name255 charactersShort identifiers — titles, display names, cover labels.
text10,000 charactersLong content — dialogue, action, descriptions, notes.

​
Key pattern

Both types use the BCP 47 regex from the schema: 
^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$
Valid examples: en, en-GB, fr-CA, zh-Hant, sr-Latn-RS.

​
Picking text at read time

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

​
Where maps appear

  • Root: title, logline
  • Cover: title, extra
  • Character: desc
  • Source: title
  • Slugline: desc
  • Element: text on action, dialogue, parenthetical, shot, transition, general
  • Note: text
  • Bookmark: title, desc
  • Ribbon: text
  • Summary / passage: text