Fighting Game · Guides & deep dives

V2 Translation File Format

The canonical JSON schema is

5sections2 minread
Markdown source
On this page

This document defines the phase-72 translation file format for TODOS.phase-72.72.11.1.3. The canonical source format is .v2loc.json; XLIFF and PO exports are derived vendor views and must preserve the same metadata.

Format Identity#

The canonical JSON schema is V2/ue/Content/Localization/V2/Schemas/V2TranslationFileFormat.schema.json. Every file uses schema v2.localization.translationFile.v1 and the extension .v2loc.json.

Required top-level fields:

  • schema
  • locale
  • sourceLocale
  • generatedFrom
  • formatVersion
  • entries

Entry Metadata#

Every translation entry must include:

  • id: canonical loc.* string ID.
  • tmsAlias: short alias without the loc. root.
  • sourceText: source-locale text.
  • translation: locale text. In source-locale files this matches sourceText.
  • contextDescription: translator-facing context description.
  • maxCharacterLength: UI budget for layout-constrained strings.
  • screenshotReference: stable screenshot or capture reference.
  • textRole: semantic role such as title, button, subtitle, body, or screen_reader_label.
  • variables: named formatting variables.
  • occurrencePaths: source files where the ID was found.
  • state: source, needs_translation, translated, reviewed, approved, or blocked.

Context descriptions are required because identical source text can have different intent across UI, dialogue, store, accessibility, and privacy flows. Max character length is required so translation QA can detect layout overflow. Screenshot references are required when available so vendors can inspect the UI surface without opening the editor.

XLIFF And PO Mapping#

Vendor adapters can export .v2loc.json entries to XLIFF or PO:

  • id maps to trans-unit@id in XLIFF and msgctxt in PO.
  • sourceText maps to XLIFF source and PO msgid.
  • translation maps to XLIFF target and PO msgstr.
  • contextDescription, maxCharacterLength, screenshotReference, textRole, and variables are preserved as notes or extracted comments.

The JSON file remains the repository source of truth. XLIFF and PO files are export artifacts and must round-trip without changing IDs or metadata.

Sample#

The source-locale sample is V2/ue/Content/Localization/V2/Translations/en-US.v2loc.json. It is generated from V2/ue/Content/Localization/V2/Extracted/StringExtractionCatalog_V2.json and includes registered string ID samples such as loc.quest.main_01.title, loc.ui.menu.options, and loc.npc.blacksmith.greeting.

Verification#

Run this gate after changing the format, schema, sample file, or CI wiring:

bash
python3 V2/ue/Tools/check-v2-translation-file-format.py

Required release gates:

  • localization-translation-file-format-contract
  • localization-translation-file-format-schema
  • localization-translation-file-format-context
  • localization-translation-file-format-max-length
  • localization-translation-file-format-screenshot
  • localization-translation-file-format-ci-wired