Languages, recordings and office appearance

Presentation packs can translate interface text, translate dialogue, add recordings, replace stock recordings and change approved office surfaces. They remain data packs: no remote stylesheets, scripts, web fonts, arbitrary interface replacement or model import is exposed through these features.

The player can choose UI language, subtitle language and audio language independently. A German interface with Spanish subtitles and English recordings is a valid combination. Creating a Portuguese dictionary does not automatically translate its recordings, and adding a French recording does not change the UI. Test the setting you are actually targeting.

Download the Office and Language demo ZIP for a small editable palette and Portuguese-language example. Import it through the hub, check its reuse terms, and clone to a new local ID when making a separately distributed derivative.

Locale descriptors

The following is a translations section fragment, not a complete pack:

[
  {
    "locale": "pt-br",
    "name": "Português (Brasil)",
    "direction": "ltr",
    "font": "system",
    "strings": {
      "title.newgame": "Novo jogo"
    },
    "phrases": {},
    "dialogue": {
      "A-GREET-WARM": "Olá! Obrigado por ligar. Como posso ajudar?"
    }
  }
]

Use a two- or three-letter base code with up to two hyphenated segments, such as ja, pt-br or a regional variant. Segments have 2–8 alphanumeric characters. Runtime registration normalizes codes to lowercase. Avoid inventing a code that collides with another language unless you intend to extend or override that same locale.

name is the native language label, up to 80 characters. direction is ltr or rtl. font chooses system, sans, serif or mono; these refer to approved system stacks. The pack cannot insert a custom CSS string, execute HTML or fetch a remote font. Test the actual glyph coverage on the target operating system.

Each descriptor may provide three dictionaries:

Each dictionary has at most 10,000 keys. Keys are nonempty and no longer than 240 characters; values are plain strings up to 16,000 characters. <, > and NUL are rejected in translations. Do not embed HTML or angle-bracket markup; literal text is the contract.

Translating faithfully

Copy real keys and phrase templates from the existing language references or the source dictionary when contributing a language. An invented key does not automatically attach to a screen. Preserve placeholders exactly, including spelling and braces: if the source uses {name}, {count} or {value}, the translated sentence must keep the required tokens even when their word order changes.

Missing keyed UI text falls back to the stock locale dictionary where available, then English, then the key itself. A visible raw key is useful evidence of a missing translation. Phrase translation applies only to registered interface phrases; arbitrary customer names, account numbers, addresses and authored community prose remain literal. Do not expect a phrase dictionary to automatically translate every sentence in another pack.

For your own calls, put dialogue translations under their raw authored catalogue IDs. The loader scopes IDs belonging to this pack's scenarios/articles. For stock lines, use the stock catalogue ID. This avoids collisions when two authors happen to use the same local voice key.

Later profile entries can replace earlier values in the same locale dictionary. A small correction pack can therefore extend an installed language, but authors should list dependencies and explain the intended order if the correction relies on another pack.

Disabling a community locale removes its active definitions. The saved preference is retained; the interface can render fallback text until the pack is re-enabled instead of permanently replacing that preference. Scratch tests temporarily override subtitle/audio choices and restore normal choices on exit. A language descriptor alone makes a locale selectable; recordings remain optional.

Stable recording catalogue

On Hold looks up a line's recording ID, then an actor and locale. Recording IDs belong to spoken lines; filenames are not arbitrary character names. Studio's Export recording script produces a CSV with columns line_id, speaker, text, covering supplied scenarios, branching nodes/choices/replies and knowledge explanations. CSV text is quoted, and formula-looking dialogue is protected as literal spreadsheet content.

Use that CSV as your production checklist. The speaker column distinguishes caller and agent, but does not choose every actor variant for you. Select the actor in coverage/import and create the exact basename shown for each target. Keep the catalogue ID unchanged between revisions of the same line.

Supported actor codes:

English filenames omit the locale prefix. Other languages prepend the lowercase locale:

f_A-GREET-WARM.mp3
fm_C-ROUTER_RESTART-OPEN-1.mp3
de_f_A-GREET-WARM.ogg
pt-br_fm_C-ROUTER_RESTART-OPEN-1.wav

Recordings use OGG, MP3 or WAV; when several ordinary files satisfy the same target the extension preference is OGG, then MP3, then WAV. Choose a sensible bitrate and avoid unnecessarily large WAV libraries. Each audio asset must stay below 32,000,000 bytes. The shared archive ceiling still applies to the complete pack.

Ordinary call filename patterns

Let VOICE be the raw scenario voice key and each token be its stable line ID:

Legacy opener tokens start 1, 2, …; clarification/resolution/reply tokens use 01, 02, …. A templated opener such as My connection failed {detail}. has one target for each detail. Its ID appends the detail token to the opener token: legacy details a, b, … produce IDs ending 1a, 1b, … and continue with spreadsheet-style suffixes after z.

Published lineIds and response lineId/replyLineIds prevent reordering from renaming the recordings. In Studio, delete/reorder moves tokens with text and new entries receive distinct monotonic tokens. In advanced JSON, move the corresponding token manually. Editing a sentence in place keeps identity; after a meaningful wording change, update its recording so the subtitle and speech still agree. Never assign a removed published token to unrelated new text.

Branching dialogue uses node and option identity instead of numeric pool positions:

fm_C-MIRA-DIALOG-start.mp3
f_A-MIRA-CHOICE-start-trace.mp3
fm_C-MIRA-REPLY-start-trace.mp3

Renaming start or trace changes those filenames and may affect saved branches. Keep node/option IDs stable when only changing their ordering or wording.

Import and coverage workflow

1. Save and validate the dialogue first. Generate the CSV from the release candidate, not an abandoned draft.
2. Choose the target locale and actor in Recording coverage. It lists target filenames and present/missing entries.
3. Use a per-line import if you want Studio to copy one selected recording to that target's basename.
4. Use Import recordings for a batch already named to the displayed convention. Bulk import preserves supplied basenames; it cannot infer the correct line from the words inside an audio file.
5. Refresh coverage and preview recordings. Repeat for other actors/locales rather than treating one actor's 100% as all voices complete.
6. Test in a real scratch call with the corresponding audio language and caller variant. Check pronunciation, clipping, dead air and the full wrap-up.

Coverage is a filename/target check. It does not prove that a file decodes, matches the text, has audible volume or contains the right language. A decodable but incorrect recording is a content defect even when coverage says complete.

Stock or explicit voice replacements

voiceOverrides can map a catalogue ID to an imported asset without requiring its filename to equal the catalogue basename. This section fragment replaces one stock agent line:

[
  {
    "lineId": "A-GREET-WARM",
    "actor": "f",
    "locale": "en",
    "file": "voice/warm-greeting.mp3"
  }
]

lineId accepts a catalogue identifier up to 180 characters using letters, digits, underscores, colon, period or hyphen. actor must be one of the supported codes. Omitted locale means English. Import the asset before publishing; the native service verifies that the referenced file exists within the pack.

Explicit replacements take priority for the requested actor/locale. Otherwise playback tries the selected non-English locale's exact actor, then its base gender for age variants, then English's exact actor, then English's base gender. Ordinary candidates use the codec order above. A missing readable override for a stock line may fall back to the stock recording; an unknown custom line with no usable recording uses timed subtitles. Playback failure also falls back to timed text rather than requiring a recording to proceed.

This fallback can produce an English line inside a partially recorded translated pack. State completeness honestly in the description, and test missing lines deliberately. Subtitles use their own setting and dictionary; they need not switch to English just because audio did.

Office appearance contract

There are eight approved surface names: walls, floor, partition, desk, mug, phone, keyboard, tower. palette assigns #RRGGBB colors. skins assigns a file/color descriptor to a surface. wallpaper addresses office walls, while monitorWallpaper addresses the PC desktop behind its windows. These do not mean a replacement web interface.

This is an office section fragment. It requires the listed image assets to be imported before native validation succeeds:

{
  "palette": {
    "walls": "#435160",
    "floor": "#28313A",
    "partition": "#35645B",
    "desk": "#AD8663",
    "mug": "#E5B552"
  },
  "wallpaper": {"file": "art/wall-pattern.png", "repeat": [4, 2]},
  "monitorWallpaper": {"file": "art/desktop.webp"},
  "skins": {
    "mug": {"file": "art/mug-stripes.png", "color": "#FFFFFF"}
  },
  "posters": [
    {"id": "queue-poster", "slot": "partition", "file": "art/queue-poster.png", "width": 0.4, "height": 0.6}
  ]
}

Descriptors need a valid file or color; they may have both. Texture repeat is two finite numbers from 0.1 to 64. The desktop uses a centered cover image rather than arbitrary desktop CSS. Poster IDs are unique, 1–64 portable characters. Up to 12 posters use fixed slots partition, leftWall, rightWall; optional width/height are 0.1–2 metres. Posters do not accept arbitrary coordinates or new wall geometry.

Use Import artwork and copy its returned art/... path into the descriptor. Images above 4,096 pixels in either dimension are rejected at scene loading even if their compressed file is below 8 MB. The asset cache is bounded; giant atlases and redundant textures are poor choices for a small office.

The Office editor previews palette, textures and fixed posters. Test this shift checks the actual 3D office and PC desktop. Switch profiles or disable the pack and verify that stock surfaces return; appearance changes reset with the active presentation registry. If several packs target the same surface, later profile entries take precedence.

Arbitrary GLB props, imported whole rooms, animation scripts, new interaction systems and replacement application layouts are outside this content API. Describe a surface/poster pack as an appearance pack rather than a new room. For installation and overlapping sources, see Profiles and saved games.