# V2 Translation File Format

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`