Translation Tree Reference

Use this page for maintainer-facing translation-tree operations: export, audit, exact-source cross-version synchronization, sync, XLIFF exchange, and translated-output structure checks. Use the parser guide before changing extraction, marker, or Jinja safety internals.

Translation Tree Facade

Translator-facing tree export and sync for expanded DSW templates.

class dsw_document_template_tool.translation_tree.TranslationMergeReport[source]

Bases: object

Summary of one old-tree to new-tree translation merge.

__init__(total_units, preserved_units, migrated_units, updated_units, untranslated_units, skipped_unsafe_old_units, exact_key_matches, source_hash_matches, sentence_matches)
Parameters:

  • total_units (int)

  • preserved_units (int)

  • migrated_units (int)

  • updated_units (int)

  • untranslated_units (int)

  • skipped_unsafe_old_units (int)

  • exact_key_matches (int)

  • source_hash_matches (int)

  • sentence_matches (int)

Return type:

None

exception dsw_document_template_tool.translation_tree.TranslationTreeError[source]

Bases: RuntimeError

Raised when the translator-facing tree is invalid.

class dsw_document_template_tool.translation_tree.XliffImportReport[source]

Bases: object

Summary of one XLIFF import into a translation tree.

__init__(imported_units)
Parameters:

imported_units (int)

Return type:

None

dsw_document_template_tool.translation_tree.audit_translated_template_structure(*, source_dir, output_dir)[source]

Return structural differences between expanded and translated templates.

Translation is allowed to change natural-language text, translatable Jinja string literals, and template metadata. It must not change the executable Jinja shape, machine placeholders, HTML structure, links/assets, or static source assets. This audit is intentionally stricter than dsw-tdk verify: the template can be syntactically valid and still be structurally wrong.

Parameters:

  • source_dir (Path)

  • output_dir (Path)

Return type:

list[TranslationTreeAuditIssue]

dsw_document_template_tool.translation_tree.audit_translation_tree(*, tree_dir, source_dir, source_lang='en', target_lang='zh_Hant')[source]

Return structural issues that make translation blocks unsafe to edit.

Parameters:

  • tree_dir (Path)

  • source_dir (Path)

  • source_lang (str)

  • target_lang (str)

Return type:

list[TranslationTreeAuditIssue]

dsw_document_template_tool.translation_tree.export_translation_tree(*, source_dir, output_dir, source_lang='en', target_lang='zh_Hant')[source]

Export one expanded template workspace into translator-facing unit files.

Parameters:

  • source_dir (Path)

  • output_dir (Path)

  • source_lang (str)

  • target_lang (str)

Return type:

Path

dsw_document_template_tool.translation_tree.export_xliff(*, tree_dir, output_path, source_lang, target_lang)[source]

Export a translation tree to one XLIFF 1.2 file.

Parameters:

  • tree_dir (Path)

  • output_path (Path)

  • source_lang (str)

  • target_lang (str)

Return type:

Path

dsw_document_template_tool.translation_tree.import_xliff(*, tree_dir, xliff_path, source_lang, target_lang)[source]

Import edited XLIFF targets back into a translation tree.

Parameters:

  • tree_dir (Path)

  • xliff_path (Path)

  • source_lang (str)

  • target_lang (str)

Return type:

XliffImportReport

dsw_document_template_tool.translation_tree.merge_translation_tree(*, old_tree_dir, new_tree_dir, output_dir, source_lang, target_lang, allow_sentence_matches=False, existing_translation_policy='preserve')[source]

Copy a regenerated tree and reuse safe translations from an older tree.

Matching is intentionally conservative. Exact (source_file, unit_key) can reuse a translation only when the unit source hash is unchanged, then unique source hash can recover moved but byte-identical source units. Visible sentence matches are intentionally disabled by default because they cannot prove that the underlying Jinja/HTML structure is still equivalent. Existing translations are preserved by default; cross-version synchronization may explicitly replace them when the source unit is an exact structural match.

Parameters:

  • old_tree_dir (Path)

  • new_tree_dir (Path)

  • output_dir (Path)

  • source_lang (str)

  • target_lang (str)

  • allow_sentence_matches (bool)

  • existing_translation_policy (Literal['preserve', 'replace'])

Return type:

TranslationMergeReport

dsw_document_template_tool.translation_tree.sync_translation_tree(*, tree_dir, source_dir, output_dir, source_lang='en', target_lang='zh_Hant', template_organization_id=None, template_id=None, template_name=None, template_description=None, template_version=None, public_readme_path=None)[source]

Apply translator-edited unit files back to one expanded workspace copy.

Parameters:

  • tree_dir (Path)

  • source_dir (Path)

  • output_dir (Path)

  • source_lang (str)

  • target_lang (str)

  • template_organization_id (str | None)

  • template_id (str | None)

  • template_name (str | None)

  • template_description (str | None)

  • template_version (str | None)

  • public_readme_path (Path | None)

Return type:

Path

CLI Entry Point

CLI entrypoint for translator-facing DSW template trees.

dsw_document_template_tool.cli.translation_tree.build_argument_parser()[source]

Build the CLI argument parser.

Return type:

ArgumentParser

dsw_document_template_tool.cli.translation_tree.main()[source]

Run the selected translation-tree command.

Return type:

None

Implementation Modules

These modules define the editable Markdown format, tree manifest, exact-source synchronization behavior, output polishing, XLIFF exchange, and structure audits.

Shared data models for translation tree workflows.

These models are intentionally free of HTML/Jinja scanner dependencies so they can be reused by export, sync, audit, and future translation migration planning.

class dsw_document_template_tool._translation_tree.models.TranslationUnit[source]

Bases: object

One translator-facing unit captured from an expanded wrapper block.

class dsw_document_template_tool._translation_tree.models.OutlineUnit[source]

Bases: object

One rendered outline row for a translator-facing unit.

class dsw_document_template_tool._translation_tree.models.TranslationEntry[source]

Bases: object

Translator-edited text plus the document it came from.

class dsw_document_template_tool._translation_tree.models.TranslationTreeAuditIssue[source]

Bases: object

One machine-checkable issue in a translator-facing tree.

exception dsw_document_template_tool._translation_tree.models.TranslationTreeError[source]

Bases: RuntimeError

Raised when the translator-facing tree is invalid.

Parser and renderer for translator-editable translation.md files.

dsw_document_template_tool._translation_tree.document.render_translation_document(*, unit, source_lang, target_lang, sentence_text, translation_text)[source]

Render one translator-facing Markdown document.

Parameters:

  • unit (TranslationUnit)

  • source_lang (str)

  • target_lang (str)

  • sentence_text (str)

  • translation_text (str)

Return type:

str

dsw_document_template_tool._translation_tree.document.parse_translation_document(*, document_path, source_lang, target_lang)[source]

Read the translation block from one translator-facing Markdown file.

Parameters:

  • document_path (Path)

  • source_lang (str)

  • target_lang (str)

Return type:

str

dsw_document_template_tool._translation_tree.document.parse_translation_markdown(*, markdown_text, location, source_lang, target_lang)[source]

Read the translation block from in-memory translation Markdown.

Parameters:

  • markdown_text (str)

  • location (str)

  • source_lang (str)

  • target_lang (str)

Return type:

str

dsw_document_template_tool._translation_tree.document.parse_sentence_text(*, document_path, source_lang)[source]

Read the plain source sentence from one translator-facing Markdown file.

Parameters:

  • document_path (Path)

  • source_lang (str)

Return type:

str

dsw_document_template_tool._translation_tree.document.parse_sentence_markdown(*, markdown_text, location, source_lang)[source]

Read the source sentence from in-memory translation Markdown.

Parameters:

  • markdown_text (str)

  • location (str)

  • source_lang (str)

Return type:

str

dsw_document_template_tool._translation_tree.document.replace_translation_text(*, document_path, target_lang, translation_text)[source]

Replace only the editable translation block in a translation document.

Parameters:

  • document_path (Path)

  • target_lang (str)

  • translation_text (str)

Return type:

None

Extract translator-facing units from expanded template wrapper blocks.

class dsw_document_template_tool._translation_tree.extraction.JinjaBranch[source]

Bases: object

One body inside an if/elif/else control group.

class dsw_document_template_tool._translation_tree.extraction.JinjaBranchGroup[source]

Bases: object

One parsed Jinja if group with branch body offsets.

class dsw_document_template_tool._translation_tree.extraction.JinjaBranchRegions[source]

Bases: object

Split branch unit spans plus the control spans they came from.

dsw_document_template_tool._translation_tree.extraction.extract_units(*, relative_path, source_text)[source]

Extract safe, independently translatable units from one expanded source file.

Parameters:

  • relative_path (str)

  • source_text (str)

Return type:

list[TranslationUnit]

Named source-quality guards learned from supported upstream templates.

These rules do not change executable template source. They improve translator-facing sentence previews and make parser regressions fail loudly. Keep each upstream-specific addition named and documented so maintainers can trace why it exists.

class dsw_document_template_tool._translation_tree.source_quality_rules.SourceFragmentRule[source]

Bases: object

Sentence shapes that indicate an incorrectly split translation unit.

class dsw_document_template_tool._translation_tree.source_quality_rules.SentenceRepairRule[source]

Bases: object

Display-only repair for words joined by upstream Jinja boundaries.

dsw_document_template_tool._translation_tree.source_quality_rules.matching_source_fragment_rule(sentence)[source]

Return the first named rule matched by a translator-facing sentence.

Parameters:

sentence (str)

Return type:

SourceFragmentRule | None

dsw_document_template_tool._translation_tree.source_quality_rules.repair_sentence_text(sentence)[source]

Apply display-only sentence repairs without mutating template source.

Parameters:

sentence (str)

Return type:

str

Apply translator-edited units back into expanded template source.

class dsw_document_template_tool._translation_tree.apply.UnitSpan[source]

Bases: object

Validated byte offsets and identity for one translated unit.

dsw_document_template_tool._translation_tree.apply.apply_unit_translations(*, source_file, wrapper_body, wrapper_units, translations)[source]

Apply validated unit translations while preserving untouched source byte-for-byte.

Parameters:

  • source_file (str)

  • wrapper_body (str)

  • wrapper_units (list[dict[str, str | int]])

  • translations (dict[tuple[str, str], TranslationEntry])

Return type:

str

Merge translator edits from an older tree into a regenerated tree.

class dsw_document_template_tool._translation_tree.merge.TranslationCandidate[source]

Bases: object

One reusable translation from an older translation tree.

class dsw_document_template_tool._translation_tree.merge.ReuseIndexes[source]

Bases: object

Lookup tables for translations that are safe to migrate.

class dsw_document_template_tool._translation_tree.merge.CandidateMatch[source]

Bases: object

One old-tree candidate selected for one new-tree unit.

class dsw_document_template_tool._translation_tree.merge.TranslationMergeReport[source]

Bases: object

Summary of one old-tree to new-tree translation merge.

dsw_document_template_tool._translation_tree.merge.merge_translation_tree(*, old_tree_dir, new_tree_dir, output_dir, source_lang, target_lang, allow_sentence_matches=False, existing_translation_policy='preserve')[source]

Copy a regenerated tree and reuse safe translations from an older tree.

Matching is intentionally conservative. Exact (source_file, unit_key) can reuse a translation only when the unit source hash is unchanged, then unique source hash can recover moved but byte-identical source units. Visible sentence matches are intentionally disabled by default because they cannot prove that the underlying Jinja/HTML structure is still equivalent. Existing translations are preserved by default; cross-version synchronization may explicitly replace them when the source unit is an exact structural match.

Parameters:

  • old_tree_dir (Path)

  • new_tree_dir (Path)

  • output_dir (Path)

  • source_lang (str)

  • target_lang (str)

  • allow_sentence_matches (bool)

  • existing_translation_policy (Literal['preserve', 'replace'])

Return type:

TranslationMergeReport

Manifest helpers for translator-facing template trees.

dsw_document_template_tool._translation_tree.manifest.load_tree_manifest(tree_dir)[source]

Load one translation tree manifest or fail with a workflow-level error.

Parameters:

tree_dir (Path)

Return type:

dict

Outline rendering for translator-facing translation trees.

dsw_document_template_tool._translation_tree.outline.refresh_outline_markdown(*, tree_dir, source_lang, target_lang)[source]

Rewrite the tree outline from the current translation documents.

Parameters:

  • tree_dir (Path)

  • source_lang (str)

  • target_lang (str)

Return type:

Path

dsw_document_template_tool._translation_tree.outline.load_outline_units(*, tree_dir, source_lang, target_lang)[source]

Load outline rows from the tree manifest and current translation blocks.

Parameters:

  • tree_dir (Path)

  • source_lang (str)

  • target_lang (str)

Return type:

list[OutlineUnit]

dsw_document_template_tool._translation_tree.outline.render_outline_markdown(*, outline_units, output_outline)[source]

Render a clickable progress outline for translation units.

Parameters:

  • outline_units (list[OutlineUnit])

  • output_outline (Path)

Return type:

str

Language-specific polish for synced translated template output.

class dsw_document_template_tool._translation_tree.output_polish.SilentSpacingCollapse[source]

Bases: object

Silent Jinja tags to keep while removing following visible whitespace.

dsw_document_template_tool._translation_tree.output_polish.polish_translated_output_dir(*, output_dir, target_lang)[source]

Apply safe, text-level polish after translations are synced.

Translation units intentionally avoid owning surrounding Jinja punctuation. For zh-Hant output, a few punctuation marks from the English template remain outside translation blocks, so normalize them at the final output boundary.

Parameters:

  • output_dir (Path)

  • target_lang (str)

Return type:

None

dsw_document_template_tool._translation_tree.output_polish.polish_zh_hant_template_text(text)[source]

Normalize punctuation patterns that are outside translation units.

Parameters:

text (str)

Return type:

str

Structural audit for translated expanded templates.

dsw_document_template_tool._translation_tree.structure_audit.audit_translated_template_structure(*, source_dir, output_dir)[source]

Return structural differences between expanded and translated templates.

Translation is allowed to change natural-language text, translatable Jinja string literals, and template metadata. It must not change the executable Jinja shape, machine placeholders, HTML structure, links/assets, or static source assets. This audit is intentionally stricter than dsw-tdk verify: the template can be syntactically valid and still be structurally wrong.

Parameters:

  • source_dir (Path)

  • output_dir (Path)

Return type:

list[TranslationTreeAuditIssue]

Audit translator-facing tree files before syncing them.

dsw_document_template_tool._translation_tree.tree_audit.audit_translation_tree(*, tree_dir, source_dir, source_lang='en', target_lang='zh_Hant')[source]

Return structural issues that make translation blocks unsafe to edit.

Parameters:

  • tree_dir (Path)

  • source_dir (Path)

  • source_lang (str)

  • target_lang (str)

Return type:

list[TranslationTreeAuditIssue]

XLIFF exchange helpers for translation trees.

class dsw_document_template_tool._translation_tree.xliff.XliffImportReport[source]

Bases: object

Summary of one XLIFF import into a translation tree.

dsw_document_template_tool._translation_tree.xliff.export_xliff(*, tree_dir, output_path, source_lang, target_lang)[source]

Export a translation tree to one XLIFF 1.2 file.

Parameters:

  • tree_dir (Path)

  • output_path (Path)

  • source_lang (str)

  • target_lang (str)

Return type:

Path

dsw_document_template_tool._translation_tree.xliff.import_xliff(*, tree_dir, xliff_path, source_lang, target_lang)[source]

Import edited XLIFF targets back into a translation tree.

Parameters:

  • tree_dir (Path)

  • xliff_path (Path)

  • source_lang (str)

  • target_lang (str)

Return type:

XliffImportReport