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.

## Mandatory Quality Gate

Before reporting success, run an automated and visual QA pass. If any check fails, patch the project-specific pipeline and rerun; do not present the output as complete.

- Confirm the rough body is not appended after a back-matter placeholder such as `致谢`, `Acknowledgements`, `参考文献`, or sample appendices.
- Confirm template placeholder text is gone or intentionally preserved. Common failures include names like `李四`, `王五`, `张三`, red formatting instructions, lorem ipsum, sample chapter headings, and template-only reference lists.
- Confirm source metadata and source front matter replaced the template placeholders: title, author, advisor, major/department, date, Chinese abstract, English abstract, keywords, declarations when applicable.
- Confirm protected front matter still matches the template's formatting. Content may change, but cover/declaration/signature pages must preserve paragraph styles, run-level fonts/sizes/bold, spacing, alignment, and page-break structure unless explicitly modified.
- Confirm TOC entries point to the generated source chapters, not only to the template's sample chapters.
- Confirm heading paragraphs are still heading styles after OOXML insertion; style ID collisions must not break TOC generation.
- Confirm body pages use the intended body style and do not inherit the last template section's header/footer.
- Confirm representative images, formulas, tables, captions, references, and citations survive the reconstruction.
- Record failures in the r