Back to Details

idml

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

IDML creation, editing, and analysis

IDML创建、编辑与分析

Overview

概述

An IDML file is a ZIP package containing XML component files (stories, spreads, resources) and a root 
designmap.xml
. Use component-level edits for minimal, safe changes; use full-package workflows for repacking and validation.
Where scripts live
  • All helper scripts are in 
    scripts/
    . If a model says “no python scripts,” have it list the directory to confirm: 
    • ls scripts
    • ls skills/idml/scripts
      (if running from repo root)
Reference files:
  • IDML package structure: 
    references/idml-structure.md
  • IDML XML overview: 
    references/idml-xml.md
  • IDML document library: 
    references/idml-document.md
  • IDML translation workflow: 
    references/idml-translation.md
  • Track changes guidance: 
    references/idml-track-changes.md
  • Schemas and validation: 
    references/idml-schemas.md
  • Tooling: 
    references/tools.md
IDML文件是一个包含XML组件文件（文稿、跨页、资源）和根文件
designmap.xml
的ZIP包。如需进行最小化、安全的修改，可使用组件级编辑；如需重新打包和验证，可使用全包工作流。
脚本存放位置
  • 所有辅助脚本都存放在
    scripts/
    目录下。如果模型提示“无Python脚本”，请让它列出目录进行确认： 
    • ls scripts
    • ls skills/idml/scripts
      （如果从仓库根目录运行）
参考文件：
  • IDML包结构：
    references/idml-structure.md
  • IDML XML概述：
    references/idml-xml.md
  • IDML文档库：
    references/idml-document.md
  • IDML翻译工作流：
    references/idml-translation.md
  • 修订追踪指南：
    references/idml-track-changes.md
  • 模式与验证：
    references/idml-schemas.md
  • 工具集：
    references/tools.md

Example prompts

示例提示词

  • "Extract all story text from this IDML and prepare it for translation."
  • "Apply translated text back into Stories/*.xml without changing layout."
  • "Map stories to spreads and pages for review."
  • "Validate this IDML package and run a roundtrip smoke test."
  • "Generate an observed schema and report unknown elements."
  • "提取此IDML中的所有文稿文本并为翻译做准备。"
  • "将翻译后的文本重新应用到Stories/*.xml中，不改变布局。"
  • "为审核需求，将文稿映射到跨页和页面。"
  • "验证此IDML包并运行往返冒烟测试。"
  • "生成观测模式并报告未知元素。"

Workflow decision tree

工作流决策树

Reading/analyzing content

读取/分析内容

  • Unpack and inspect 
    designmap.xml
    , story files, and spreads.
  • Use the XML reference to understand component boundaries.
  • 解压并检查
    designmap.xml
    、文稿文件和跨页文件。
  • 参考XML文档以了解组件边界。

Creating a new document

创建新文档

  • Preferred: create in InDesign and export to IDML.
  • If generating from scratch, follow the IDML specification and component schemas.
  • 推荐方式：在InDesign中创建文档并导出为IDML。
  • 如需从头生成，请遵循IDML规范和组件模式。

Editing an existing document

编辑现有文档

  • Text-only edits: edit 
    Stories/*.xml
    .
  • Layout edits: edit 
    Spreads/*.xml
    or 
    MasterSpreads/*.xml
    .
  • Styles/resources: edit 
    Resources/*.xml
    and keep references consistent.
  • 仅文本编辑：编辑
    Stories/*.xml
    文件。
  • 布局编辑：编辑
    Spreads/*.xml
    或
    MasterSpreads/*.xml
    文件。
  • 样式/资源：编辑
    Resources/*.xml
    文件并保持引用一致性。

Reading and analyzing content

读取与分析内容

Unpacking

解压

bash
python scripts/unpack_idml.py file.idml unpacked
bash
python scripts/unpack_idml.py file.idml unpacked

Key files

关键文件

See 
references/idml-structure.md
for the required files and folders.
所需文件和文件夹请参见
references/idml-structure.md
。

Editing workflows

编辑工作流

Library-based edits (recommended)

基于库的编辑（推荐）

Use 
scripts/idml_document.py
for component discovery and XML edits. See 
references/idml-document.md
for usage.
使用
scripts/idml_document.py
进行组件发现和XML编辑。使用方法请参见
references/idml-document.md
。

Raw XML edits (advanced)

原始XML编辑（高级）

  1. MANDATORY - READ ENTIRE FILE: Read 
    references/idml-xml.md
    before editing XML directly.
  2. Unpack the file: 
    python scripts/unpack_idml.py file.idml unpacked
  3. Edit the specific component XML (stories/spreads/resources).
  4. Repack: 
    python scripts/pack_idml.py unpacked out.idml
  5. Validate: 
    python scripts/validate_idml.py unpacked --original out.idml
  1. 必须操作 - 阅读完整文件：在直接编辑XML之前，请阅读
    references/idml-xml.md
    。
  2. 解压文件：
    python scripts/unpack_idml.py file.idml unpacked
  3. 编辑特定组件XML（文稿/跨页/资源）。
  4. 重新打包：
    python scripts/pack_idml.py unpacked out.idml
  5. 验证：
    python scripts/validate_idml.py unpacked --original out.idml

Translation workflow

翻译工作流

Use 
references/idml-translation.md
to extract, translate, and reapply story text.
使用
references/idml-translation.md
提取、翻译并重新应用文稿文本。

Track changes

修订追踪

Disable Track Changes before exporting IDML from InDesign. See 
references/idml-track-changes.md
.
从InDesign导出IDML之前，请禁用修订追踪。详情请参见
references/idml-track-changes.md
。

Validation and smoke tests

验证与冒烟测试

  • Package validation: 
    python scripts/validate_idml.py <unpacked_dir> --original <file.idml>
  • Full roundtrip smoke test: 
    python scripts/smoke_test.py <file.idml> <work_dir>
  • Translation extract: 
    python scripts/extract_story_text.py <unpacked_dir> translations.jsonl
  • Prepare translation JSONL: 
    python scripts/prepare_translation_jsonl.py translations.jsonl translations_for_translation.jsonl
  • Translation apply: 
    python scripts/apply_story_text.py <unpacked_dir> translations.jsonl
  • Story count report: 
    python scripts/compare_story_counts.py english.jsonl khmer.jsonl --out story_counts.json
  • Alignment file: 
    python scripts/align_story_text.py english.jsonl khmer.jsonl --out alignment.jsonl
  • Story/spread map: 
    python scripts/map_story_spreads.py <unpacked_dir> --out story_spreads.json
  • Resource report: 
    python scripts/check_resources.py <unpacked_dir> --out resources_report.json
  • Content-only validation: 
    python scripts/validate_content_only_changes.py <original_unpacked> <modified_unpacked>
  • Observed schema report: 
    python scripts/observe_idml_schema.py <idml_or_unpacked> --out idml_observed_schema.json
  • Observed schema validation: 
    python scripts/validate_observed_schema.py <schema.json> <idml_or_unpacked> --out idml_schema_report.json
  • Observed schema coverage: 
    python scripts/observed_schema_report.py <schema.json> --out idml_schema_coverage.json
  • Observed schema delta: 
    python scripts/schema_delta_report.py <base_schema.json> <new_schema.json> --out idml_schema_delta.json
  • Coverage checklist: 
    python scripts/coverage_checklist.py <schema_delta.json> --out idml_schema_checklist.md
  • Combined coverage plan: 
    python scripts/coverage_plan.py Label=delta.json ... --out idml_schema_plan.md
  • 包验证：
    python scripts/validate_idml.py <unpacked_dir> --original <file.idml>
  • 完整往返冒烟测试：
    python scripts/smoke_test.py <file.idml> <work_dir>
  • 翻译提取：
    python scripts/extract_story_text.py <unpacked_dir> translations.jsonl
  • 准备翻译JSONL：
    python scripts/prepare_translation_jsonl.py translations.jsonl translations_for_translation.jsonl
  • 翻译应用：
    python scripts/apply_story_text.py <unpacked_dir> translations.jsonl
  • 文稿数量报告：
    python scripts/compare_story_counts.py english.jsonl khmer.jsonl --out story_counts.json
  • 对齐文件：
    python scripts/align_story_text.py english.jsonl khmer.jsonl --out alignment.jsonl
  • 文稿/跨页映射：
    python scripts/map_story_spreads.py <unpacked_dir> --out story_spreads.json
  • 资源报告：
    python scripts/check_resources.py <unpacked_dir> --out resources_report.json
  • 仅内容验证：
    python scripts/validate_content_only_changes.py <original_unpacked> <modified_unpacked>
  • 观测模式报告：
    python scripts/observe_idml_schema.py <idml_or_unpacked> --out idml_observed_schema.json
  • 观测模式验证：
    python scripts/validate_observed_schema.py <schema.json> <idml_or_unpacked> --out idml_schema_report.json
  • 观测模式覆盖率：
    python scripts/observed_schema_report.py <schema.json> --out idml_schema_coverage.json
  • 观测模式差异：
    python scripts/schema_delta_report.py <base_schema.json> <new_schema.json> --out idml_schema_delta.json
  • 覆盖检查清单：
    python scripts/coverage_checklist.py <schema_delta.json> --out idml_schema_checklist.md
  • 组合覆盖计划：
    python scripts/coverage_plan.py Label=delta.json ... --out idml_schema_plan.md

Code style guidelines

代码风格指南

  • Write concise code.
  • Avoid verbose variable names and redundant operations.
  • Avoid unnecessary print statements.
  • 编写简洁的代码。
  • 避免冗长的变量名和冗余操作。
  • 避免不必要的打印语句。

Dependencies

依赖项

Required
  • defusedxml: 
    pip install defusedxml
    (safe XML parsing)
Optional
  • InDesign: export IDML from source documents
  • jing: Relax NG validator for strict schema checks
必需
  • defusedxml：
    pip install defusedxml
    （安全XML解析）
可选
  • InDesign：从源文档导出IDML
  • jing：用于严格模式检查的Relax NG验证器