docx-template-translator

DOCX Template Translator

Core Idea

Treat the input file as the content source and the Word template as the formatting source. Do not expect pandoc or PDF import to infer template semantics. Build a project-specific Python postprocessor after inspecting the template and the converted body document.

Do not treat the bundled starter pipeline or a preset JSON file as a finished converter for institutional templates. For thesis/dissertation templates, you must create or patch a project-specific pipeline for the concrete template and source project before claiming success.

Workflow

1. Identify inputs:
   • Source: .tex project, .pdf, .md, or an existing rough .docx.
   • Template: required .docx.
   • Output location and document metadata.
2. Inspect the template with the real CLI form:
   • python scripts/inspect_docx_template.py template.docx --out template_report.json
3. Create a rough body .docx:
   • LaTeX/Markdown: use pandoc when available.
   • PDF: try Word COM import or pdf2docx; prefer PDF only when the original source is unavailable.
   • Existing DOCX: use it as the rough body source.
4. Write or patch a project-specific Python pipeline:
   • Start from scripts/adaptive_docx_pipeline.py.
   • Copy it into the run/output directory or project workspace before patching; do not edit the bundled script in place for a one-off conversion.
   • Decide, from the template inspection, which template paragraphs/tables/sections are reusable and which are sample placeholders to delete.
   • Mark protected native-template regions before coding. For thesis templates, cover pages, English cover pages, originality/declaration pages, authorization pages, signatures, and their section breaks are protected by default until the first generated abstract/body marker.
   • Replace or fill template front matter such as cover pages, declarations, abstracts, keywords, TOC placeholders, headers, footers, page numbering, and section breaks when the source provides those fields.
   • In protected regions, replace text inside existing paragraphs/runs/tables without deleting and rebuilding the paragraph. Preserve paragraph styles, run fonts/sizes/bold, alignment, spacing, and page breaks unless the user explicitly asks to alter the template.
   • Insert the rough body at the real body start or rebuild the document around the template parts. Do not blindly append the rough body to the end of the template.
   • Copy template front matter if needed.
   • Append rough body content while remapping DOCX relationships.
   • Remap copied style IDs by visible style name before applying formatting; otherwise Heading 1/2/3 can silently become an unrelated template style when source and template style IDs collide.
   • Remap styles to the template's real body, heading, caption, reference, and TOC styles.
   • Scope global formatting passes to generated content only, for example with formatting_start_marker. Never run body-style remapping across native cover/declaration pages.
   • Clean or rebuild section header/footer references when deleting sample template sections; stale back-matter headers such as 致谢 must not appear on body pages.
   • Add or repair figure/table captions, table borders, hyperlinks, bookmarks, citations, and page breaks.
5. Finalize with Microsoft Word when available:
   • Use scripts/finalize_word_docx.py to update fields/TOC and export a PDF preview.
6. Automated and visual verification:
   • Use scripts/validate_docx_conversion.py final.docx --template template.docx --protected-until "中 文 摘 要" --pdf final.pdf --out validation.json for placeholder/order/header/image/table checks plus protected-front-matter format checks. Choose the real first generated marker for non-Zhengzhou templates.
   • Then run scripts/validate_docx_render.py final.docx --pdf final.pdf --out validation_render.json for render-level checks: TOC field presence, numId↔abstractNum consistency, multilevel heading format, reference-counter independence, body-header static-text leakage, and PDF field-error strings. The structural validator can return PASS while the document is visibly broken; the render validator is what catches "empty TOC", "chapters not auto-numbered", "references start at [47]", "body header still says 致谢", and "STYLEREF prints 错误!使用'开始'选项卡…".
   • Use scripts/render_pdf_preview.py to inspect cover pages, abstracts, TOC, representative tables, figures, formulas, and references.