Dialogue Director V1 Localization Workflow

Review draft. This source page has not completed website editorial and release-specific verification.

Authority and scope

Unreal Engine’s Localization Dashboard and localization pipeline are authoritative for Localization Targets, cultures, gathering, manifests and archives, PO export/import, compiled LocRes resources, and runtime culture lookup. Dialogue Director provides source identity, readiness checks, and validation. It does not own translations, edit PO files, create targets, or prove target package inclusion from configured path patterns.

The host game project owns its Localization Targets. Configure a game target in Unreal’s Localization Dashboard and include the game Content paths that contain the DialogueDefinition and any LineDelivery companion. Review the actual gathered assets in Unreal; Dialogue Director reports package inclusion as Not verified by Dialogue Director. An invalid or incomplete target configuration is reported separately from Dialogue content validation. Use Open Localization Dashboard to review target setup. If Unreal reports that settings are saved in a read-only DefaultEditor.ini, the project owner must check out or otherwise make the relevant Unreal config writable before editing it.

Current V1 DialogueDefinitions receive their stable TextIdentityGuid and current text-identity schema when constructed. Current authoring allocates each Line, Choice option, and Interjection TextId and applies the expected localization identity as part of creation. Developers do not run Text Identity Migration during normal authoring. Repair Text Identities is shown only when a development asset has missing or inconsistent identity data; opening an asset never silently rewrites it. Dialogue Director does not promise a production backward-compatibility workflow for pre-V1 assets.

Translator-facing surfaces

V1 gathers exactly these Dialogue Director authored surfaces:

• Dialogue Line text
• Choice Text
• Interjection text
• nonempty LineDelivery WrittenText
• nonempty LineDelivery CaptionText

An empty LineDelivery override is not a separate translation entry, even when runtime presentation falls back to another surface.

Developer-only text is excluded from translator surfaces: Developer Node Name, Choice Label, Developer Description, Action labels and descriptions, Event labels and descriptions, Branch Case DisplayName, Condition Expression DisplayName, Participant RoleName, generated condition/branch/editor summaries, and routing/debug/internal strings. RoleName identifies an authoring/runtime participant role; it is not a localized speaker name. Persisted developer-only FText values are expected to be culture invariant. Repair Developer-Only Text is an explicit transactional asset repair, preserves authored source strings, does not modify PO/archive data, and is separate from text identity recovery. Repair does not run on load or during validation.

Identity and clones

The namespace is DialogueDirector. Definition Line, Choice, and Interjection keys are:

Text.<TextIdentityGuid>.<TextId>

LineDelivery Written and Caption keys are distinct:

Text.<TextIdentityGuid>.Delivery.<TextId>.Written

Text.<TextIdentityGuid>.Delivery.<TextId>.Caption

The canonical Definition interchange stores TextIdentityGuid, TextId, authored source text, and ordered format-argument declarations. It reconstructs namespace/key identity deterministically rather than serializing those derived strings. Canonical Definition export preserves the authored source string.

Independent Clone preserves TextIds but assigns a new TextIdentityGuid. It therefore creates new localization keys; Unreal translations associated with the source clone are not automatically shared with the independent clone.

Changing authored source while retaining a key may make an existing translation stale; the readiness panel reports staleness only when Unreal’s imported archive data proves a source mismatch. Deleted surfaces disappear from future gathers; archive and translation cleanup follows Unreal’s localization workflow and remains under project authority.

Unreal workflow

1. Configure or select the host project’s Localization Target in Unreal’s Localization Dashboard.
2. Configure target cultures and gather rules for the DialogueDefinition and companion LineDelivery packages.
3. Gather text in Unreal and inspect that the expected packages and identities appear.
4. Export PO from Unreal.
5. Translate the PO externally.
6. Import PO and compile localization resources in Unreal.
7. Return to the DialogueDefinition Localization tab and choose Validate Localization.

The tab can validate Dialogue-local identity, source-format, developer-text, companion, and target/archive state even when no Localization Target exists. A missing target is a warning/state, not an invalid Definition. With multiple host targets, select which target to inspect. A configured culture with unavailable archive data is distinct from an available archive with a missing translation. Missing translations are warnings rather than hard correctness errors.

Format arguments

Source patterns and ordered argument declarations are authored in Dialogue Director. Argument names, types, and source keys remain controlled by those declarations, not by translated PO text. Validation checks translated pattern syntax, missing required placeholders, and unknown placeholders. A renamed placeholder is reported as the missing source name plus the unknown translated name. Placeholder names are case-sensitive; repeating a valid placeholder is allowed. Dialogue Director does not infer argument types from translations.

CSV boundary

Dialogue Director CSV bundles are update-only interchange projections, not a translation authority or PO workflow. Use Unreal localization gathering and PO operations for translation. See CSV Spreadsheet Interchange for the CSV contract.