OpenCC Selection Converter

Safely convert the current visible selection in Obsidian using real OpenCC custom configurations while preserving Markdown structure and source outside the selection.

The plugin supports desktop and mobile code paths, vault files and URL-based schemes, offline caching, strict equal-length checks, atomic undo, the command palette, per-scheme commands and a context-menu entry. Release verification currently covers the Obsidian desktop application and its mobile simulation; Android and iOS devices have not yet been tested.

Installation

community or build the plugin, copy the release files to the vault’s plugin directory:

npm ci
npm run build

Copy dist/main.js, dist/manifest.json, dist/versions.json and dist/styles.css to:
<Vault>/.obsidian/plugins/opencc-selection-converter/

Reload Obsidian and enable OpenCC Selection Converter under Community plugins. The fixed native engine assets in engine/generated/ are bundled at build time; a clean plugin build needs only Node.js and npm dependencies. Conversion requires no network access at runtime.

To rebuild the native assets after changing the engine, run npm run build:engine with the OpenCC and emsdk source versions pinned in engine/upstream.lock.json. This regenerates engine/generated/opencc.mjs and engine/generated/opencc.wasm; include both updated assets with native source changes.

Usage

1. Open Settings → OpenCC Selection Converter → Add scheme.
2. Pick a preset and click Add. This includes **Traditional → Mainland Traditional (`t2gov`)** and **Simplified → Mainland Traditional (`s2gov`)**. For a custom scheme, choose a vault file or enter a config URL, then Save.
3. To run several complete OpenCC schemes in order, choose **Conversion chain**, add at least two loaded schemes and arrange the steps. Chains are saved as independent offline snapshots; use Refresh when you want to reload their original sources.
4. Select text in Source mode or Live Preview and use Convert selection, a scheme command, or the context menu. Undo once to restore the complete conversion.

Each active scheme has its own stable command, which can be assigned a separate shortcut in Obsidian’s Hotkeys settings. No selection means no conversion of the whole note.

Use Edit → Save for changes; renaming alone works offline. Each scheme’s More options menu contains Refresh, Check lengths and Delete. Custom schemes keep dependency overrides and a source preview under Advanced. Warnings and unapproved HTTP resources still require review before loading; cancelling leaves the active scheme unchanged.

Schemes and cache

• Supports real OpenCC JSON/JSONC configurations, inline, text, ocd and ocd2 dictionaries, and the conversion stages defined by the configuration.
• A conversion chain runs every complete configuration in order, including each step’s normalization and segmentation. Chains allow repeated schemes, contain 2–16 steps, and cannot nest other chains.
• URL-relative dependencies are resolved relative to the configuration URL by default; vault-relative dependencies are resolved relative to the configuration file. Advanced settings can specify a dependency base or per-file overrides.
• HTTP uses exact-URL authorisation rather than authorising an entire domain. Selected note text is processed locally by the WASM engine; it is not uploaded, logged or written to the cache.
• A successful scheme saves a complete immutable snapshot for offline reuse. If a refresh fails, the previous usable snapshot is retained and its status is shown.

The Mainland Traditional presets use dictionaries from TerryTian-tech/OpenCC-Traditional-Chinese-characters-according-to-Chinese-government-standards, pinned to a fixed commit under Apache-2.0. s2gov runs the existing official OpenCC s2t preset and then t2gov.

Safe mapping and equal length

Strict mode checks every actual native OpenCC match in every chain step and the final Unicode code-point count. An intermediate length change is rejected even if a later step restores the original length; any failure cancels the complete write.

Force mode allows length changes, but does not bypass selection boundaries, Markdown structure, link targets, region rules or candidate-source re-parsing. When a cross-format phrase cannot be assigned uniquely, the output inherits the formatting at the start of the phrase.

Manual Length check shows:

• Complete: equal length
• Length risk found
• Check incomplete

This is a scheme audit. It does not replace the actual per-conversion checks.

Region rules

Inline code, code blocks, quotes, inline maths, block maths and maths groups each support three policies: always convert, convert only when the complete selection is inside the region, or never convert.

When a parent region is excluded, its child regions are excluded too. Maths supports a verified fixed subset, including common Greek and symbol commands, text and font commands, fractions, roots, subscripts, superscripts and escapes. Unknown macros, environments or ambiguous structures are rejected explicitly; the plugin does not guess the source mapping.

Known limitations

• Only Markdown Source mode and Live Preview selections are supported; Reading mode selections are not supported.
• Multiple selections are rejected. Without a selection, the plugin never falls back to converting the whole note.
• Complex wikilink paths without aliases, headings and block references may be rejected conservatively.
• When conversion inside code is allowed, surrounding fences are protected, but programming-language semantics are not guaranteed.
• When Obsidian opens and saves a CRLF file, it may normalise line endings to LF. The plugin ensures that its conversion logic does not rewrite editor line endings, but does not promise byte-level fidelity on disk.
• Desktop mobile simulation is not equivalent to Android/iOS device acceptance; user-provided schemes must also be verified independently.

Development and verification

Tests use a dedicated vault and clear this plugin’s test cache. Do not point them at a real vault. See docs/testing.md and docs/verification.md.

npm run check
npm run test:build
npm run test:cli -- smoke
npm run test:cli -- mapping
npm run test:cli -- editor
npm run test:cli -- settings
npm run test:cli -- production
npm test

Acknowledgements

The conversion core is based on OpenCC. Complete third-party sources, pinned versions and licences are listed in THIRD_PARTY_NOTICES.md and engine/licenses/.

Contributing

This repository currently has no public remote, issue tracker or formal contribution process. Do not assume that pull requests are accepted. Confirm with the repository owner before submitting changes; at minimum, run npm run check and the smallest relevant dedicated-vault test.

Licence

MIT © 2026 OpenCC Selection Converter contributors. Third-party components, including the bundled native engine, retain the licences listed in THIRD_PARTY_NOTICES.md.