eddx-translate

Translate visible text in EdrawMax/EdrawMind (.eddx) diagrams between languages without altering shapes, layout, styles, or metadata.

Overview

Edraw .eddx files are ZIP archives containing XML (shapes, text, styles) and assets (thumbnails, metadata). All visible text in a single-page diagram lives in pages/page1.xml inside <tp> (text paragraph) elements. This skill translates only those <tp> text nodes, leaving every other XML attribute, coordinate, style, and ZIP entry untouched.

Core Principle: Source files are never modified. A new .eddx file is always produced.

File Format Requirements

File Organization Rules

• Input .eddx: Read-only source. Never modified.
• Mapping JSON: Provided by the user or generated by the AI agent (see Workflow, Step 3).
• Output .eddx: Saved adjacent to the input file with the suffix .translated.eddx.
  • Example: diagram.eddx → diagram.translated.eddx
  • An explicit output path can be provided as the third argument.

Workflow

Step 1: Validate Input

1. Confirm the file path exists and has the .eddx extension.
2. Open the file with zipfile and list its entries. Expected entries include:
   • pages/page1.xml — the page XML containing <tp> text nodes
   • document.xml, theme.xml, thumbnail.jpeg, rels/*

Step 2: Extract and Present Text

1. Extract the .eddx ZIP to a temporary directory (never extract into the source file's directory).
2. Read pages/page1.xml as UTF-8.
3. Use regex to find all <tp ...>TEXT</tp> nodes.
4. Collect unique trimmed text values.
5. Present the extracted text to the user for them to provide a translation mapping, or — if the request is clear (e.g., "translate to Chinese") — ask whether the user wants the AI to auto-generate the mapping.

Step 3: Build a Translation Mapping

1. Keys must match the exact trimmed text inside <tp> nodes character for character — any mismatch (extra space, wrong punctuation) causes the replacement to fail silently.
2. Values are the replacement text (Chinese or English).
3. Preserve the original line-break structure. If the source uses a single <tp> for a multi-line label, keep it as a single entry in the mapping.

Mapping JSON format:

{
  "Start": "开始",
  "End": "结束",
  "Process": "处理中",
  "Decision": "判断"
}

Step 4: Apply Translations

1. Use the bundled script scripts/eddx_translate.py to apply the mapping:

   python scripts/eddx_translate.py <input.eddx> <mapping.json> [output.eddx]

2. The script uses the regex pattern (<tp[^>]*>)([^<]*)(</tp>) to locate each <tp> node.
3. Only the text content (group 2) is replaced when an exact key match exists in the mapping.
4. All attributes on <tp>, surrounding XML, ZIP metadata — everything else — is left intact.
5. The script reports the number of <tp> nodes replaced. If zero nodes matched, it prints a warning (keys may be incorrect).

Step 5: Verify Output

1. The script runs zipfile.testzip() on the new archive to confirm ZIP integrity.
2. It parses pages/page1.xml with xml.etree.ElementTree to confirm the XML is well-formed.
3. Manually or programmatically confirm the source file's hash/size has not changed.
4. Report results to the user (see Output Format).

Translation Quality Guidelines

For best results, follow these rules when building the mapping:

Key Matching (Critical)

• Exact string matching only. The script does not normalize quotes, trim whitespace, or do fuzzy matching. A trailing space or mismatched quote character (" vs " vs ") will cause the translation to fail.
• Copy keys directly from the extracted text list (Step 2) rather than re-typing them.
• If the script reports "0 text nodes replaced", the most likely cause is key mismatch.

Terminology Consistency

• Keep the same term translated the same way across all shapes. For example, if "Submit" is mapped to "提交" in one shape, use the same mapping everywhere.
• For product names, acronyms, and proper nouns, confirm with the user whether to translate or preserve.

Text Structure

• Do not merge or split <tp> nodes. Each <tp> in the source should map to exactly one entry in the JSON. If a label spans multiple lines inside one <tp>, preserve the line break in the translation.
• Do not add or remove HTML/XML tags. The script only handles plain text content.

Important Rules

• Never modify the source file. Always write a new .eddx file.
• Only translate text inside <tp> elements. Do not touch <Text>, <TextBlock>, <pp>, <shape>, or other attributes unless the user explicitly asks.
• Preserve the ZIP structure. Use the original infolist() to maintain entry order, compression type, and external attributes.
• Use UTF-8 encoding for both reading and writing XML.
• Warn the user that Edraw text boxes may look cramped because container widths were calculated for the original language. Suggest manual width adjustment in Edraw if needed.

Using the Bundled Script

The skill includes scripts/eddx_translate.py, which performs the exact workflow described above:

python scripts/eddx_translate.py <input.eddx> <mapping.json> [output.eddx]

Arguments:

Exit codes:

• 0 — Success (even if 0 nodes matched; a warning is printed)
• 1 — Missing arguments, invalid file, or script error

Typical User Prompts That Trigger This Skill

Output Format

After completion, present the following to the user:

1. New file path: diagram.translated.eddx (or custom path)
2. Translation count: Number of <tp> nodes translated
3. Source integrity: Confirmation that the source file was left untouched
4. Warning: Brief note about possible text-box overflow (English→Chinese expansion or Chinese→English contraction may affect layout)