How graphviz2drawio Handles Character Encoding for Input Files

graphviz2drawio detects the system locale for default text encoding, supports explicit encoding declarations via CLI flags, and implements automatic UTF-8 fallback to prevent conversion failures.

The hbmartin/graphviz2drawio converter bridges Graphviz DOT files and Draw.io diagrams, requiring robust character encoding handling to process international character sets correctly. Understanding how this tool manages encoding ensures reliable conversion across different operating systems and language locales. The implementation prioritizes flexibility through user overrides while providing sensible defaults based on system configuration.

Default Encoding Detection via System Locale

In graphviz2drawio/models/Arguments.py, the command-line interface defines an --encoding (-e) parameter that defaults to the system's preferred encoding. The code obtains this value through Python's locale.getpreferredencoding(do_setlocale=False).lower(), ensuring cross-platform compatibility without modifying the global locale state.

This approach automatically adapts to Windows systems using cp1252, Linux environments defaulting to utf-8, or Chinese Windows installations using gbk. The default selection happens at argument parse time, making the encoding immediately available to the conversion routine.

File Reading with Automatic UTF-8 Recovery

The conversion routine in graphviz2drawio/__main__.py opens input files using Path.open(encoding=encoding), passing the encoding parameter directly from parsed CLI arguments. When a UnicodeDecodeError occurs and the requested encoding differs from UTF-8, the tool assumes the underlying DOT file is actually UTF-8 encoded—a common scenario on Windows systems with international content.

The fallback logic retries the file read using UTF-8 encoding, preventing conversion failures when the locale-derived default mismatches the actual file encoding. This automatic recovery eliminates manual intervention for files containing Chinese, Japanese, or other non-ASCII characters saved in UTF-8 despite the system's default code page.

Output Encoding Consistency

After successful parsing and conversion, the generated Draw.io XML maintains encoding consistency by using the same character set that successfully read the input. The write operation in graphviz2drawio/__main__.py applies the final encoding value to the output file, ensuring that international characters survive the round-trip from DOT to XML format.

When users specify --stdout, the encoding parameter still governs string handling during conversion, though terminal output may apply additional system-level encoding depending on the shell environment.

Practical Command-Line Examples

Force UTF-8 encoding regardless of system locale:

graphviz2drawio -e utf-8 international_graph.dot

Handle legacy Windows files using CP1252:

graphviz2drawio -e cp1252 legacy_graph.dot

Process Chinese-language files with GBK encoding:

graphviz2drawio -e gbk chinese_graph.dot

Rely on automatic detection with UTF-8 fallback:

graphviz2drawio mygraph.dot

Summary

• System locale detection: Defaults to locale.getpreferredencoding(do_setlocale=False).lower() via graphviz2drawio/models/Arguments.py
• Explicit overrides: Supports --encoding (-e) flag for user-specified character sets like gbk, cp1252, or utf-8
• UTF-8 fallback: Automatically retries with UTF-8 when UnicodeDecodeError occurs and the original encoding wasn't UTF-8, as implemented in graphviz2drawio/__main__.py
• Consistent output: Writes Draw.io XML using the successfully decoded input encoding to preserve character fidelity

Frequently Asked Questions

What encoding does graphviz2drawio use by default?

By default, graphviz2drawio uses your system's preferred encoding obtained via Python's locale.getpreferredencoding(do_setlocate=False).lower(). This typically returns utf-8 on Linux and macOS systems, while Windows environments may return cp1252 or regional code pages depending on the locale configuration.

How do I convert a DOT file containing Chinese or Japanese characters?

Specify the correct encoding using the --encoding or -e flag. For files saved in UTF-8 but running on a Windows system with a different default, use graphviz2drawio -e utf-8 chinese.dot. For GBK-encoded files common in Chinese Windows environments, use graphviz2drawio -e gbk chinese.dot.

What happens if graphviz2drawio cannot decode the input file?

If the initial encoding attempt raises a UnicodeDecodeError and the requested encoding is not UTF-8, graphviz2drawio automatically retries opening the file with UTF-8 encoding. This fallback mechanism handles the common case where DOT files are UTF-8 encoded but the system locale indicates a different code page.

Does the output XML file use the same encoding as the input DOT file?

Yes, the generated Draw.io XML file uses the same encoding value that successfully decoded the input. The Path.open() call in graphviz2drawio/__main__.py applies this encoding to the output stream, ensuring that international characters and special symbols remain intact throughout the conversion process.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}