Browse documentation

BaseStructure map

A field-by-field reference for the document, unit, target, metadata, and helper objects developers use in application code.

The model at a glance

Every parser converges on this shape. The dictionary key or streamed unit_id is the stable application lookup key; the Data value holds everything associated with that translation unit.

BaseStructure map

BaseStructure├── source_locale: str├── target_locale: str | None├── data: dict[str, Data]│   └── unit_id → Data│       ├── source: str│       ├── target: str | None│       ├── targets: dict[str, TargetData]│       ├── plural: Plural | None│       ├── tags: Tags | None│       ├── meta: Meta│       ├── status: TranslationStatus│       ├── comments: list[Comment]│       ├── previous_context / next_context│       └── extensions: dict[str, str]├── target_locales / source_language / target_languages├── format_version / export_origin / export_timestamp├── extensions: dict[str, str]└── export / regen / to_dict() / split_targets()

BaseStructure field reference

Field	Type	Meaning
`source_locale`	`str`	Full source locale carried by the document, such as `en-US`.
`target_locale`	`str	None`
`data`	`dict[str, Data]`	Ordered materialized units keyed by stable application ID.
`target_locales`	`tuple[str, ...]`	Ordered target locales known at document level.
`format_version`	`str`	Model/interchange version metadata; defaults to `0.1` for manually constructed documents.
`export_origin`	`str`	Document-level generator or source-system provenance when the input exposes it.
`export_timestamp`	`str`	Document-level source/export timestamp as supplied by the format.
`source_language`	`str	None`
`target_language`	`str	None`
`target_languages`	`tuple[str, ...]`	Ordered base languages corresponding to known targets.
`extensions`	`dict[str, str]`	Format-specific document fields that have no universal model slot.

Data and TargetData field reference

Owner	Field	Type	Processing rule
`Data`	`source`	`str`	Required plain source text; inline structure lives beside it in `tags`.
`Data`	`target`	`str	None`
`Data`	`targets`	`dict[str, TargetData]`	Locale-keyed target payloads for multilingual documents.
`Data`	`plural`	`Plural	None`
`Data`	`tags`	`Tags	None`
`Data`	`meta`	`Meta`	Usage, time, and length metadata.
`Data`	`status`	`TranslationStatus`	Selected/legacy unit status; defaults to `unknown`.
`Data`	`comments`	`list[Comment]`	Ordered notes, provenance, project attribution, and contextual history.
`Data`	`previous_context`, `next_context`	`AdjacentContext	None`
`Data`	`extensions`	`dict[str, str]`	Unit-level source-format properties such as resource, domain, flags, or original ID.
`TargetData`	`text`	`str	None`
`TargetData`	`status`	`TranslationStatus`	Locale-specific status; `unknown` allows the base status to remain authoritative.
`TargetData`	`tags`	`TargetTags	None`
`TargetData`	`plural`	`Plural	None`
`TargetData`	`meta`	`Meta`	Target-specific metadata, merged over base metadata during splitting.
`TargetData`	`comments`	`list[Comment]`	Target-specific comments; when present they replace base comments in a split view.
`TargetData`	`extensions`	`dict[str, str]`	Target-specific format fields, merged over unit extensions during splitting.

Construct a checked document

The public objects are slotted dataclasses. Construct them directly when an application creates localization data; this keeps field names visible to type checkers and distinguishes a missing target from an intentionally empty string.

model.py

from lokit.types import BaseStructure, Data, TargetData
document = BaseStructure(    source_locale="en-US",    target_locale="fr-FR",    data={        "home.title": Data(            source="Welcome",            target="Bienvenue",            targets={                "fr-FR": TargetData(text="Bienvenue"),            },        ),    },)

Single-target and multilingual documents

A selected single-target document normally has document.target_locale and may expose its selected text as Data.target. A multilingual document has ordered target_locales and stores per-locale values in Data.targets. Do not assume Data.target is populated for multilingual input; select from unit.targets[locale] or call document.split_targets().

split.py

documents_by_locale = document.split_targets(    ("fr-FR", "de-DE"),    include_missing=False,)
for locale, localized in documents_by_locale.items():    localized.export.xliff(f"messages.{locale}.xliff")

Materialized and streaming parity

StreamingStructure carries every document field above but replaces data with items: Iterable[tuple[str, Data]]. Treat items as one-shot. Both structures expose .export, .regen, .to_dict(), and .split_targets(); materialized projections return lists and dictionaries, while streaming projections stay lazy or use a bounded temporary split context.

Follow the integrity references

Use Tags & inline content when editing or converting formatted segments, Metadata & plurals for every nested metadata type and its format mappings, and TMX, XLIFF & file splitting for per-locale output and streaming lifecycle rules.