OpenccNet

OpenccNetLib is a fast and efficient .NET library for converting Chinese text, offering support for Simplified ↔ Traditional, Taiwan, Hong Kong, and Japanese Kanji variants. Built with inspiration from OpenCC, this library is designed to integrate seamlessly into modern .NET projects with a focus on performance and minimal memory usage.

Features
Installation
Usage
Office Document & EPUB Conversion
Example: Convert Office Document In-Memory
Backward-Compatible String Overload
Async API
Convert Files
What does conversion do?
Error Handling
Unit Tested
Why This Matters
Performance
API Reference
Dictionary Data
Add-On CLI Tools
Usage Notes - OpenccNet pdf
Project That Use OpenccNetLib
License

Features

Fast, multi-stage Chinese text conversion using prebuilt dictionary unions
(optimized with static caching and zero-allocation hot paths)
Supports:
- Simplified ↔ Traditional Chinese
- Taiwan Traditional (T) ↔ Simplified / Traditional
- Hong Kong Traditional (HK) ↔ Simplified / Traditional
- Japanese Kanji Shinjitai ↔ Traditional Kyujitai
Accurate handling of Supplementary Plane CJK (U+20000+) characters
(correct surrogate-pair detection and matching)
Optional punctuation conversion

Thread-safe conversion core with immutable shared dictionaries; suitable for high-throughput parallel processing when converters are not reconfigured concurrently.

Office document & EPUB conversion (pure in-memory):
- .docx (Word), .xlsx (Excel), .pptx (PowerPoint), .epub
- byte[] → byte[] conversion with full XML patching
- Async/await supported (ConvertOfficeBytesAsync)
- Zero temp files required; safe for Web, Server, and WASM/Blazor hosts
.NET Standard 2.0 compatible
(cross-platform: Windows, Linux, macOS; supported on .NET Core 2.0+, .NET 5+, .NET 6/7/8/9/10 LTS)

Installation

Add the library to your project via NuGet or reference the source code directly.
Add required dependencies of dictionary files to library root.
- dicts\dictionary_maxlength.zstd Default dictionary file.
- dicts\*.* Others dictionary files for different configurations.

Install via NuGet:

dotnet add package OpenccNetLib

Or, clone and include the source files in your project.

Usage

Basic Example

using OpenccNetLib;

// Recommended: use the enum-based constructor
var opencc = new Opencc(OpenccConfig.S2T); // Simplified → Traditional

string traditional = opencc.Convert("汉字转换测试");
Console.WriteLine(traditional);
// Output: 漢字轉換測試

Or, using the legacy string-based configuration:

using OpenccNetLib;
var opencc = new Opencc("s2t"); // Simplified to Traditional 
string traditional = opencc.Convert("汉字转换测试"); 
Console.WriteLine(traditional);
// Output: 漢字轉換測試

Supported Configurations

Config	Description
s2t	Simplified → Traditional
t2s	Traditional → Simplified
s2tw	Simplified → Traditional (Taiwan)
tw2s	Traditional (Taiwan) → Simplified
s2twp	Simplified → Traditional (Taiwan, idioms)
tw2sp	Traditional (Taiwan, idioms) → Simplified
s2hkp	Simplified → Traditional (Hong Kong phrases)
hk2sp	Traditional (Hong Kong phrases) → Simplified
t2hkp	Traditional → Traditional (Hong Kong, phrases)
hk2tp	Traditional (Hong Kong, phrases) → Traditional
s2hk	Simplified → Traditional (Hong Kong)
hk2s	Traditional (Hong Kong) → Simplified
t2tw	Traditional → Traditional (Taiwan)
tw2t	Traditional (Taiwan) → Traditional
t2twp	Traditional → Traditional (Taiwan, idioms)
tw2tp	Traditional (Taiwan, idioms) → Traditional
t2hk	Traditional → Traditional (Hong Kong)
hk2t	Traditional (Hong Kong) → Traditional
t2jp	Traditional Kyujitai → Japanese Kanji Shinjitai
jp2t	Japanese Kanji Shinjitai → Traditional Kyujitai

Example: Convert with Punctuation

var opencc = new Opencc("s2t"); 
string result = opencc.Convert("“汉字”转换。", punctuation: true);
Console.WriteLine(result);
// Output: 「漢字」轉換。

Example: Hong Kong Phrase Conversion

var cc = new Opencc(OpenccConfig.S2Hkp);
Console.WriteLine(cc.Convert("别随便录影侵犯个人隐私权"));
// 別隨便錄影侵犯個人私隱權

Example: Switching Config Dynamically

using OpenccNetLib;

var opencc = new Opencc("s2t");  // Or: var opencc = new Opencc(OpenccConfig.S2T);

// Initial conversion
string result = opencc.Convert("动态切换转换方式");
Console.WriteLine(result);  // Output: 動態切換轉換方式

// Switch config using string
opencc.Config = "t2s";  // Also valid: opencc.SetConfig("t2s")
result = opencc.Convert("動態切換轉換方式");
Console.WriteLine(result);  // Output: 动态切换转换方式

// Switch config using enum (recommended for safety and autocomplete)
opencc.SetConfig(OpenccConfig.S2T);
result = opencc.Convert("动态切换转换方式");
Console.WriteLine(result);  // Output: 動態切換轉換方式

// Invalid config falls back to "s2t"
opencc.Config = "invalid_config";
Console.WriteLine(opencc.GetLastError());  // Output: Invalid config provided: invalid_config. Using default 's2t'.

Thread-safety note: Opencc instances should not be reconfigured while they are being used by other threads. For parallel conversion, create one instance per configuration and treat it as immutable, or use direct conversion methods. GetLastError() is instance-level diagnostic state and should not be shared across threads.

💡 Tips

Use OpenccConfig enum for compile-time safety and IntelliSense support.
Use GetLastError() to check if fallback occurred due to an invalid config.
You can also validate config strings with Opencc.IsValidConfig("t2tw").

Direct API Methods

You can also use direct methods for specific conversions:

using OpenccNetLib;
var opencc = new Opencc();
opencc.S2T("汉字");      
// Simplified to Traditional opencc.T2S("漢字");      
// Traditional to Simplified opencc.S2Tw("汉字");     
// Simplified to Taiwan Traditional opencc.T2Jp("漢字");     
// Traditional to Japanese Kanji
// ...and more

Preserve IDS expressions

IDS preservation is disabled by default. Enable it when working with Unicode Ideographic Description Sequences (IDS). Complete IDS chunks are preserved, while surrounding normal text is still converted.

using OpenccNetLib;

var cc = new Opencc(OpenccConfig.T2S);

Console.WriteLine(cc.Convert("⿰氵漢"));
// ⿰氵汉

cc.SetPreserveIds(true);

Console.WriteLine(cc.Convert("⿰氵漢"));
// ⿰氵漢

Console.WriteLine(cc.Convert("測試⿰氵漢文本"));
// 测试⿰氵漢文本

The same option can be set as a property:

var cc = new Opencc("t2s")
{
    IsPreserveIds = true
};

CJK Compatibility Ideograph Normalization

CompatIdeographs is an optional Unicode compatibility pre-processing helper. It maps CJK Compatibility Ideographs to their Unicode decomposition targets before OpenCC segmentation and dictionary conversion. This is useful when input text contains compatibility forms such as 金 but you want conversion to behave as if the canonical ideograph 金 had been provided.

Compatibility ideograph normalization is not OpenCC linguistic conversion. It does not modify OpenCC dictionaries, phrase matching, regional variant selection, script detection, or punctuation conversion. For converted text, the recommended order is:

Normalize compatibility ideographs with NormalizeCompat(...) or CompatIdeographs.
Run normal OpenCC conversion with Convert(...).
Optionally run DeTofu on the converted result for display fallback.

Convenient Opencc instance API:

using OpenccNetLib;

var cc = new Opencc();

Console.WriteLine(cc.NormalizeCompat("天龍八部書裡的喬峰是契丹人"));
// Output: 天龍八部書裡的喬峰是契丹人

Console.WriteLine(cc.NormalizeCompat("abc天龍八部書裡的喬峰是契丹人123"));
// Output: abc天龍八部書裡的喬峰是契丹人123

Normalize before conversion:

using OpenccNetLib;

var cc = new Opencc(OpenccConfig.T2S);

string normalized = cc.NormalizeCompat("天龍八部書裡的喬峰是契丹人");
string converted = cc.Convert(normalized);

Console.WriteLine(converted);
// Output: 天龙八部书里的乔峰是契丹人

Direct reusable normalizer usage:

using OpenccNetLib;

var compat = CompatIdeographs.Builtin();

Console.WriteLine(compat.Normalize("天龍八部書裡的喬峰是契丹人"));
// Output: 天龍八部書裡的喬峰是契丹人

CompatIdeographs also supports custom mapping text for advanced callers:

using OpenccNetLib;

var compat = CompatIdeographs.FromText("金\t金\n");
Console.WriteLine(compat.Normalize("金"));
// Output: 金

Compatibility ideograph APIs:

CompatIdeographs.Builtin()
CompatIdeographs.FromText(...)
CompatIdeographs.Normalize(...)
CompatIdeographs.NormalizeScalar(...)
CompatIdeographs.NormalizeChar(...)
CompatIdeographs.NormalizeInPlace(...)
CompatIdeographs.NormalizeCompatIdeographs(...)
Opencc.NormalizeCompat(...)

Characters outside the CJK Compatibility Ideograph ranges, and compatibility ideographs without a decomposition mapping, are preserved unchanged.

DeTofu Display Compatibility

DeTofu is an optional display-compatibility pass for rare non-BMP CJK extension characters. Some systems, browsers, document viewers, e-book readers, and mobile platforms do not have complete font coverage for these characters, so they may render as tofu boxes or missing glyphs.

DeTofu is not OpenCC linguistic conversion. It does not modify OpenCC dictionaries, phrase matching, regional variant selection, script detection, or punctuation conversion. For converted text, the recommended order is:

Optionally normalize CJK Compatibility Ideographs before conversion.
Run normal OpenCC conversion with Convert(...).
Run DeTofu on the converted result.

Normal OpenCC conversion:

using OpenccNetLib;

var cc = new Opencc(OpenccConfig.S2T);
string converted = cc.Convert("汉字转换测试");
Console.WriteLine(converted);
// Output: 漢字轉換測試

OpenCC conversion followed by DeTofu:

using OpenccNetLib;

var cc = new Opencc(OpenccConfig.T2S);
string converted = cc.Convert("驂𬴂");
string displaySafe = cc.DeTofu(converted, DeTofuLevel.ExtB);

Console.WriteLine(displaySafe);

Direct utility usage:

using OpenccNetLib;

string displaySafe = DeTofu.Convert("驂𬴂", DeTofuLevel.ExtB);
Console.WriteLine(displaySafe);

DeTofu APIs:

DeTofu.ParseLevel(...)
DeTofu.Convert(...)
DeTofuMap.Builtin(...)
DeTofuMap.WithCustomFile(...)
DeTofuMap.WithCustomPairs(...)
Opencc.DeTofu(...)
Opencc.DeTofuWithCustomFile(...)
Opencc.DeTofuWithCustomPairs(...)

Reusable map usage:

using System.Collections.Generic;
using OpenccNetLib;

var map = DeTofuMap
    .Builtin(DeTofuLevel.ExtB)
    .WithCustomPairs(new[]
    {
        new KeyValuePair<string, string>("𣭲", "氄")
    });

string displaySafe = map.Convert("𣭲");
Console.WriteLine(displaySafe);

Custom in-memory pairs usage:

using OpenccNetLib;

var cc = new Opencc();

var pairs = new Dictionary<string, string>
{
    ["𣭲"] = "氂",
    ["𬴂"] = "騑"
};

var output = cc.DeTofuWithCustomPairs(
    "𣭲毛 骖𬴂",
    DeTofuLevel.ExtB,
    pairs);

Console.WriteLine(output);
// 氂毛 骖騑

In-memory pairs are supplied as IEnumerable<KeyValuePair<string, string>>, where each key is a tofu-risk character and each value is its display-compatible fallback character. Only the first Unicode scalar value from each key and value is used, and null or empty keys and values are ignored. Pairs do not carry an extension column, so they are applied directly to the selected map after the built-in mappings. Custom pairs override built-in mappings for the same tofu-risk character. If duplicate keys are supplied, the later mapping wins according to enumeration order.

Custom fallback file usage:

using OpenccNetLib;

var cc = new Opencc(OpenccConfig.T2S);
string converted = cc.Convert("驂𬴂");
string displaySafe = cc.DeTofuWithCustomFile(
    converted,
    DeTofuLevel.ExtB,
    "dicts/custom-tofu.txt");

Console.WriteLine(displaySafe);

Fallback files are UTF-8 text files with one mapping per line:

# Format: tofu_char<TAB>fallback_char<TAB>extension

Example:

# Custom DeTofu fallbacks
𣭲	氂	B
𬴂	騑	ExtC

Blank lines and lines beginning with # are ignored. The extension column accepts compact B-I values and legacy ExtB-ExtI values.

Built-in mappings are loaded from dicts/TSCharactersTofu.txt. Custom files and custom pairs are applied after the built-in mappings. File mappings override built-in mappings for the same tofu-risk character, and custom pairs do the same. Later mappings override earlier mappings when the same tofu-risk character is provided.

Characters without built-in or custom fallback mappings are preserved unchanged, even if they belong to an enabled CJK extension block. DeTofu is non-destructive: it never replaces unknown characters with ?, □, �, or empty text.

DeTofuLevel is threshold-based:

Level	Replacement threshold
`DeTofuLevel.ExtB`	ExtB and above
`DeTofuLevel.ExtC`	ExtC and above
`DeTofuLevel.ExtD`	ExtD and above
`DeTofuLevel.ExtE`	ExtE and above
`DeTofuLevel.ExtF`	ExtF and above
`DeTofuLevel.ExtG`	ExtG and above
`DeTofuLevel.ExtH`	ExtH and above
`DeTofuLevel.ExtI`	ExtI only

Error Handling

If an error occurs (e.g., invalid config), use:

string error = opencc.GetLastError();
Console.WriteLine(error); // Output the last error message

Language Detection

Detect if a string is Simplified, Traditional, or neither:

using OpenccNetLib;
int result = Opencc.ZhoCheck("汉字"); // Returns 2 for Simplified, 1 for Traditional, 0 for neither
Console.WriteLine(result); // Output: 2 (for Simplified)

User Custom Dictionaries

By default, OpenccNetLib uses the built-in Zstandard-compressed lexicon. For advanced custom dictionary workflows, build or customize a DictionaryMaxlength instance, then activate it before creating Opencc instances.

DictionaryMaxlength DictionaryLib.FromDicts(
    string relativeBaseDir = "dicts",
    IDictionary<DictSlot, string> overrides = null,
    IDictionary<DictSlot, string> appends = null)

OpenccNetLib follows the OpenCC lexicon structure. Custom dictionaries must attach to existing OpenCC dictionary slots such as DictSlot.STPhrases or DictSlot.TSPhrases; dynamic generic slots such as user_dict are intentionally rejected. Preserving the OpenCC dictionary topology keeps dictionary metadata, lookup acceleration structures, and runtime plans deterministic and compatible.

Regional variant phrase slots are also customizable. DictSlot.TWVariantsPhrases is applied before DictSlot.TWVariants, and DictSlot.HKVariantsPhrases is applied before DictSlot.HKVariants, so phrase exceptions can protect a full term from later character-level regional variant mappings. These slots can be used with both append and override custom dictionary APIs.

Direct Hong Kong phrase slots are customizable too. DictSlot.HKPhrases is used by s2hkp after Simplified-to-Traditional conversion, and DictSlot.HKPhrasesRev is used by hk2sp before Traditional-to-Simplified conversion.

Portable custom-dictionary specifications

A portable custom-dictionary token has this grammar:

<slot>:<append|override>:<path>

Use CustomDictSpec.Parse(...) when a specification comes from configuration, a command line, or another portable string source. Slot and mode matching is case-insensitive. Slot parsing is strict: numeric enum strings, unknown names, and the obsolete JPVariants and JPVariantsRev slots are rejected. The parser splits the token into no more than three fields, preserving Windows drive-letter paths and relative paths containing additional colons. It validates the specification syntax but does not check whether the file exists; dictionary loading reports missing or unreadable files.

using OpenccNetLib;

var parsed = CustomDictSpec.Parse(
    @"hkphrasesrev:append:data\my_hk_dict.txt");

var parsedDict = DictionaryLib.WithCustomDicts(
    DictionaryLib.New(),
    new[] { parsed });

Use CustomDictSpec.FromFile(...) when the slot and mode are already strongly typed in C#:

var typed = CustomDictSpec.FromFile(
    DictSlot.HKPhrasesRev,
    @"data\my_hk_dict.txt",
    CustomDictMode.Append);

var typedDict = DictionaryLib.WithCustomDicts(
    DictionaryLib.New(),
    new[] { typed });

Parse(...) and FromFile(...) construct specifications; they do not load files or change the active dictionary. Apply the resulting specifications with DictionaryLib.WithCustomDicts(...). For custom files applied while loading a complete OpenCC text dictionary directory, use DictionaryLib.FromDicts(...) with its strongly typed appends or overrides dictionaries.

Canonical names and supported slots are discoverable without maintaining a separate list:

foreach (var slot in DictSlotExtensions.ActiveSlots)
{
    Console.WriteLine(slot.ToCanonicalName());
}

var slotParsed = DictSlotExtensions.Parse("hkphrasesrev");
bool recognized = DictSlotExtensions.TryParse("HKPhrasesRev", out var slotTried);

The token representation is intentionally unified across the C#, Java, Rust, and Python OpenCC ecosystem. This release provides the public C# CustomDictSpec.Parse(...) API and uses it for the C# CLI. A matching public library parser is not claimed here for Java, Rust, or Python; those public API ports are separate work and should be treated as planned or not yet ported unless the documentation for that language explicitly says otherwise. A CLI in another language may already accept the shared token without exposing a public library parser.

File-level customization

Use DictionaryLib.FromDicts() when custom files should be applied while loading the OpenCC text dictionaries.

Use appends to load custom entries after the built-in dictionary in the selected slot. Appended entries use "late-comer wins" behavior, so duplicate keys override earlier built-in mappings.

using System.Collections.Generic;
using OpenccNetLib;

var dict = DictionaryLib.FromDicts(
    appends: new Dictionary<DictSlot, string>
    {
        [DictSlot.STPhrases] = "custom_st_phrases.txt",
        [DictSlot.TWVariantsPhrases] = "custom_tw_variant_phrases.txt"
    });

Opencc.UseCustomDictionary(dict);

var opencc = new Opencc("s2t");
Console.WriteLine(opencc.Convert("帕兰蒂尔是一家公司"));

Hong Kong phrase slots can be customized with the same API:

var dict = DictionaryLib.FromDicts(
    appends: new Dictionary<DictSlot, string>
    {
        [DictSlot.HKPhrases] = "custom_hk_phrases.txt"
    });

Opencc.UseCustomDictionary(dict);

var cc = new Opencc(OpenccConfig.S2Hkp);
Console.WriteLine(cc.Convert("小女孩问：什么是个人隐私权？"));
// 妹丁問：什麽是個人私隱權？

For in-memory pairs, apply a post-load custom spec:

var dict = DictionaryLib.New();

DictionaryLib.WithCustomDicts(
    dict,
    new[]
    {
        new CustomDictSpec
        {
            Slot = DictSlot.HKPhrases,
            Mode = CustomDictMode.Append,
            Pairs = new Dictionary<string, string>
            {
                ["小女孩"] = "妹丁",
                ["動畫片"] = "卡通片"
            }
        }
    });

Opencc.UseCustomDictionary(dict);

var cc = new Opencc(OpenccConfig.S2Hkp);
Console.WriteLine(cc.Convert("小女孩喜欢看动画片"));
// 妹丁喜歡看卡通片

Override an entire slot

Use overrides only when replacing the full content of an OpenCC dictionary slot with a complete custom dictionary.

using OpenccNetLib;

var dict = DictionaryLib.FromDicts(
    overrides: new Dictionary<DictSlot, string>
    {
        [DictSlot.STPhrases] = "./company/STPhrases.txt"
    });

Opencc.UseCustomDictionary(dict);

Post-load customization

Use DictionaryLib.WithCustomDicts() when you already have a loaded DictionaryMaxlength provider and want to apply additional slot-level changes.

using System.Collections.Generic;
using OpenccNetLib;

var dict = DictionaryLib.New();

DictionaryLib.WithCustomDicts(
    dict,
    new CustomDictSpec[]
    {
        new CustomDictSpec
        {
            Slot = DictSlot.STPhrases,
            Mode = CustomDictMode.Append,
            Paths = new[] { "company_terms.txt", "product_terms.txt" },
            Pairs = new Dictionary<string, string>
            {
                ["帕兰蒂尔"] = "帕蘭蒂爾"
            }
        }
    });

Opencc.UseCustomDictionary(dict);
var opencc = new Opencc("s2t");

Post-load customization works with any already loaded provider, including DictionaryLib.New(), FromDicts(), FromJson(), FromCbor(), or another customized DictionaryMaxlength instance.

Each CustomDictSpec targets one slot. Paths is optional and can contain multiple custom dictionary files. Pairs is optional and contains in-memory entries. At least one of Paths or Pairs must be supplied. When both are supplied, files are applied first in array order, then pairs are applied; later duplicate keys overwrite earlier entries, so pairs win over file entries.

CustomDictMode.Append merges into the existing slot. CustomDictMode.Override replaces the whole target slot with the merged result from that spec. Dictionary metadata and lookup acceleration structures are rebuilt automatically after customization.

Exact in-memory fallback pairs

Use CustomDictSpec.Pairs for small, exact in-memory fallback pairs when an application needs project-local conversion patches without restructuring the built-in OpenCC dictionary files.

This is especially useful for tofu-risk or CJK Extension Unicode cases where some target platforms may not render newer characters correctly. Applications can provide temporary alternate mappings while keeping the built-in dictionary topology unchanged.

using System.Collections.Generic;
using OpenccNetLib;

var dict = DictionaryLib.New();

DictionaryLib.WithCustomDicts(
    dict,
    new CustomDictSpec[]
    {
        new CustomDictSpec
        {
            Slot = DictSlot.STPhrases,
            Mode = CustomDictMode.Append,
            Pairs = new Dictionary<string, string>
            {
                // Project-local fallback pairs for tofu-risk / Extension Unicode cases.
                // Keep these patches small, explicit, and easy to remove later.
                ["骖𬴂"] = "驂騑",
                ["𫜩合"] = "齧合",
                ["𫜩蘗吞针"] = "齧蘗吞針",

                // Normal custom phrase pairs may be mixed in as well.
                ["帕兰蒂尔"] = "帕蘭蒂爾"
            }
        }
    });

Opencc.UseCustomDictionary(dict);

var opencc = new Opencc("s2t");

Console.WriteLine(opencc.Convert("骖𬴂"));
Console.WriteLine(opencc.Convert("𫜩合"));
Console.WriteLine(opencc.Convert("帕兰蒂尔"));

This keeps the core dictionary structure unchanged while still allowing applications to patch specific high-risk entries at load time.

API	Description
`DictSlot`	Strongly typed OpenCC dictionary slot selector
`DictSlotExtensions.ActiveSlots`	Enumerate active supported slots
`DictSlotExtensions.Parse(...)` / `TryParse(...)`	Strictly parse a canonical slot name
`DictSlotExtensions.ToCanonicalName()`	Format an active slot canonically
`CustomDictSpec.Parse(...)`	Parse a portable custom-dictionary token
`CustomDictSpec.FromFile(...)`	Construct a strongly typed single-file spec
`CustomDictSpec.Slot`	Target slot
`CustomDictSpec.Paths`	Custom dictionary files
`CustomDictSpec.Pairs`	In-memory dictionary entries
`CustomDictSpec.Mode`	`Append` or `Override`
`CustomDictMode.Append`	Merge into the existing slot
`CustomDictMode.Override`	Replace the whole slot

Custom dictionary file format

Custom dictionary files are UTF-8 text files. Each entry is written as phrase<TAB>translation; blank lines are ignored, comments are supported, and duplicate keys use late-comer wins behavior.

# Company terminology
帕兰蒂尔	帕蘭蒂爾
人工智能	人工智慧

Short append example:

var dictionary = DictionaryLib.FromDicts(
    appends: new Dictionary<DictSlot, string>
    {
        [DictSlot.STPhrases] = "custom-st-phrases.txt"
    });

Opencc.UseCustomDictionary(dictionary);
var opencc = new Opencc("s2t");

Supported dictionary slots

DictSlot	Serialization Field	Default File
`DictSlot.STCharacters`	`st_characters`	`STCharacters.txt`
`DictSlot.STPhrases`	`st_phrases`	`STPhrases.txt`
`DictSlot.STPunctuations`	`st_punctuations`	`STPunctuations.txt`
`DictSlot.TSCharacters`	`ts_characters`	`TSCharacters.txt`
`DictSlot.TSPhrases`	`ts_phrases`	`TSPhrases.txt`
`DictSlot.TSPunctuations`	`ts_punctuations`	`TSPunctuations.txt`
`DictSlot.TWPhrases`	`tw_phrases`	`TWPhrases.txt`
`DictSlot.TWPhrasesRev`	`tw_phrases_rev`	`TWPhrasesRev.txt`
`DictSlot.TWVariants`	`tw_variants`	`TWVariants.txt`
`DictSlot.TWVariantsPhrases`	`tw_variants_phrases`	`TWVariantsPhrases.txt`
`DictSlot.TWVariantsRev`	`tw_variants_rev`	`TWVariantsRev.txt`
`DictSlot.TWVariantsRevPhrases`	`tw_variants_rev_phrases`	`TWVariantsRevPhrases.txt`
`DictSlot.HKVariants`	`hk_variants`	`HKVariants.txt`
`DictSlot.HKPhrases`	`hk_phrases`	`HKPhrases.txt`
`DictSlot.HKVariantsPhrases`	`hk_variants_phrases`	`HKVariantsPhrases.txt`
`DictSlot.HKVariantsRev`	`hk_variants_rev`	`HKVariantsRev.txt`
`DictSlot.HKPhrasesRev`	`hk_phrases_rev`	`HKPhrasesRev.txt`
`DictSlot.HKVariantsRevPhrases`	`hk_variants_rev_phrases`	`HKVariantsRevPhrases.txt`
`DictSlot.JPSCharacters`	`jps_characters`	`JPShinjitaiCharacters.txt`
`DictSlot.JPSCharactersRev`	`jps_characters_rev`	`JPShinjitaiCharactersRev.txt`
`DictSlot.JPSPhrases`	`jps_phrases`	`JPShinjitaiPhrases.txt`

Japanese Shinjitai dictionary layout follows upstream OpenCC commit 93ee7f7: JPShinjitaiCharacters.txt is the authoritative character mapping source, and JPShinjitaiCharactersRev.txt is the generated reverse dictionary used by t2jp. JPVariants.txt and JPVariantsRev.txt are no longer part of the active dictionary schema. Users who provide custom dictionary bundles, JSON, CBOR, or Zstd packs must regenerate those bundles or include the new non-empty JPShinjitaiCharactersRev.txt / jps_characters_rev slot. The retired DictSlot.JPVariants and DictSlot.JPVariantsRev enum members remain defined as obsolete compatibility sentinels with their original numeric values. Custom dictionary APIs reject these inactive slots rather than silently redirecting their values to a different dictionary.

Recommended usage

Use appends for company terms, product names, domain vocabulary, and temporary conversion fixes. Use overrides only when maintaining a full proprietary replacement dictionary. Prefer following the upstream OpenCC lexicon structure whenever possible.

Call Opencc.UseCustomDictionary(dict) once during application startup, before constructing Opencc instances. The chosen dictionary should be treated as the application's single source of truth. Do not hot-swap the global dictionary provider while existing Opencc instances are still active; if the provider must change, set the new provider and then discard and recreate existing Opencc instances.

This global provider design is intentional for performance: dictionary data, metadata, StarterUnion / UnionCache acceleration structures, and runtime plans can be shared instead of duplicated per Opencc instance. Normal applications usually need only one custom provider. Unit tests that mutate the global provider should not run in parallel with tests expecting the default provider.

Why no `user_dict` slot?

OpenccNetLib intentionally preserves the OpenCC dictionary topology. Generic dynamic slots complicate conversion contracts, DictRefs, starter indexes, StarterUnion, and the conversion plan/union caches. Existing OpenCC slots already provide deterministic and extensible customization points.

🆕 Office Document & EPUB Conversion (In-Memory, No Temp Files Required)

Starting from OpenccNetLib v1.3.2, the library now provides a pure in-memory Office / EPUB conversion API.
This allows converting .docx, .xlsx, .pptx, and .epub directly from byte[] to byte[], without touching the filesystem.

This is ideal for:

Web servers (ASP.NET Core)
Blazor / WebAssembly
JavaScript interop
Desktop apps that want to avoid temp paths
Security-restricted environments

✔ Supported formats

Format	Description
`docx`	Word document (Office Open XML)
`xlsx`	Excel spreadsheet (Office Open XML)
`pptx`	PowerPoint presentation (Office Open XML)
`odt`	OpenDocument Text (LibreOffice / OpenOffice)
`ods`	OpenDocument Spreadsheet
`odp`	OpenDocument Presentation
`epub`	EPUB e-book (with correct uncompressed mimetype)

📦 Example: Convert Office Document In-Memory

using OpenccNetLib;

var opencc = new Opencc("s2t"); // Simplified → Traditional

byte[] inputBytes = File.ReadAllBytes("sample.docx");

// New strongly-typed OfficeFormat enum (recommended)
byte[] outputBytes = OfficeDocConverter.ConvertOfficeBytes(
    inputBytes,
    format: OfficeFormat.Docx,
    converter: opencc,
    punctuation: false,
    keepFont: true
);

File.WriteAllBytes("output.docx", outputBytes);

🔁 Backward-Compatible String Overload

Existing string-based API still works:

byte[] outputBytes = OfficeDocConverter.ConvertOfficeBytes(
    inputBytes,
    format: "docx",   // legacy string format
    converter: opencc
);

No breaking changes — all existing code continues working.

⚡ Async API (Recommended for Server/Web)

var outputBytes = await OfficeDocConverter.ConvertOfficeBytesAsync(
    inputBytes,
    format: OfficeFormat.Docx,
    converter: opencc,
    punctuation: false,
    keepFont: true
);

Fully async
No blocking
Safe for ASP.NET Core, MAUI, Blazor WebAssembly

String format async overload also remains available.

📁 Convert Files (Convenience wrappers)

Office and EPUB conversion validates every generated ZIP package before returning success. Invalid or corrupted input packages fail with a clear InvalidOperationException that preserves the underlying ZIP/package exception instead of returning potentially corrupted bytes. File-output overloads write to a temporary file in the destination directory and atomically publish it only after conversion and validation complete, avoiding partial or corrupted output files.

OfficeDocConverter.ConvertOfficeFile(
    "input.docx",
    "output.docx",
    format: OfficeFormat.Docx,
    converter: opencc
);

Or async:

await OfficeDocConverter.ConvertOfficeFileAsync(
    "input.docx",
    "output.docx",
    format: OfficeFormat.Docx,
    converter: opencc
);

String-based overload:

OfficeDocConverter.ConvertOfficeFile(
    "input.docx",
    "output.docx",
    "docx",
    opencc
);

🔍 What does conversion do?

Inside the Office/EPUB container (ZIP), the library will:

Extract only the relevant XML/XHTML parts
Apply OpenCC text conversion (s2t, t2s, t2tw, hk2s, etc.)
Preserve XML structure and formatting
Optionally preserve fonts (keepFont = true)
Rebuild the Office container as valid ZIP
For EPUB: ensure mimetype is first uncompressed entry (EPUB spec)

🛡 Error Handling

If conversion fails (invalid format, corrupted ZIP, missing document.xml, etc.):

throw new InvalidOperationException("Conversion failed: ...");

A companion “Try” API may be added in future versions.

🧪 Unit Tested (MSTest)

OpenccNetLib includes integration tests for:

.docx (Word)
ZIP structure validation
XML extraction correctness
Chinese text conversion inside word/document.xml
Round-trip verification

Example (OfficeDocConverterTests):

[TestMethod]
public void ConvertOfficeBytes_Docx_S2T_Succeeds()
{
    var opencc = new Opencc("s2t");
    var inputBytes = File.ReadAllBytes("滕王阁序.docx");

    var outputBytes = OfficeDocConverter.ConvertOfficeBytes(
        inputBytes, "docx", opencc);

    Assert.IsNotNull(outputBytes);

    using var ms = new MemoryStream(outputBytes);
    using var zip = new ZipArchive(ms, ZipArchiveMode.Read);

    Assert.IsNotNull(zip.GetEntry("word/document.xml"));
}

🚀 Why This Matters

Zero temp files → perfect for cloud environments
Memory-only pipeline → safer, faster, cleaner
Cross-platform (Windows / macOS / Linux / WASM)
Blazor and JavaScript-ready (byte[] in/out)
No external dependencies (only built-in System.IO.Compression)

Performance

Uses static dictionary caching, precomputed StarterUnion masks, and thread-local buffers for high throughput.
On .NET 9 and later, dictionary candidates are probed directly from ReadOnlySpan<char> without allocating temporary string keys. The .NET Standard 2.0 asset retains the compatible string-key fallback.
Suitable for real-time, batch, and parallel processing.

🚀 Performance Benchmark for OpenccNetLib 1.6.2

`S2T` Conversion (.NET 9+ Span-Key Optimizations, Real-World Load)

Benchmarked under normal desktop usage (IDE and background apps running) to reflect realistic performance.

Environment

Item	Value
BenchmarkDotNet	v0.15.8
OS	Windows 11 (Build 26200.8875, 25H2)
CPU	Intel Core i5-13400 (10C/16T @ 2.50 GHz)
.NET SDK	10.0.302
Runtime	.NET 10.0.10 (X64 RyuJIT x86-64-v3)
Iterations	10 (1 warm-up)

Results

Method	Size	Mean	Error	StdDev	Min	Max	Rank	Gen0	Gen1	Gen2	Allocated
BM_Convert_Sized	100	1.776 µs	0.0156 µs	0.0093 µs	1.769 µs	1.793 µs	1	0.0305	–	–	328 B
BM_Convert_Sized	1,000	35.594 µs	0.2929 µs	0.1743 µs	35.364 µs	35.876 µs	2	0.1831	–	–	2,128 B
BM_Convert_Sized	10,000	199.543 µs	13.7299 µs	9.0815 µs	192.796 µs	214.343 µs	3	14.6484	2.4414	–	146,651 B
BM_Convert_Sized	100,000	1,383.007 µs	36.8934 µs	21.9547 µs	1,352.110 µs	1,422.130 µs	4	156.2500	119.1406	109.3750	1,035,338 B
BM_Convert_Sized	1,000,000	11,444.810 µs	144.7586 µs	86.1435 µs	11,278.808 µs	11,562.277 µs	5	968.7500	859.3750	531.2500	10,274,191 B

Summary

100 chars → ~1.8 µs, 328 B allocated
1,000 chars → ~35.6 µs, 2.1 KB allocated
10,000 chars → ~0.20 ms, 143.2 KB allocated
100,000 chars → ~1.38 ms, 0.99 MB allocated
1,000,000 chars (1M) → ~11.45 ms, 9.8 MB allocated

On this system, the 1M-character result corresponds to approximately 87 million characters per second.

Comparison with v1.6.1

Size	v1.6.1 Mean	v1.6.2 Mean	Speedup	Allocation Reduction
100	2.430 µs	1.776 µs	1.37×	~93.8%
1,000	62.305 µs	35.594 µs	1.75×	~97.6%
10,000	250.230 µs	199.543 µs	1.25×	~81.1%
100,000	3.807 ms	1.383 ms	2.75×	~86.7%
1,000,000	20.040 ms	11.445 ms	1.75×	~87.1%

The large improvement is primarily due to target-specific optimization introduced in v1.6.2. Version 1.6.1 did not ship a .NET 9+ optimized asset, so modern applications used the .NET Standard 2.0 implementation and materialized a temporary string for each candidate dictionary key. Version 1.6.2 adds a net9.0 asset that uses Dictionary.TryGetAlternateLookup<ReadOnlySpan<char>>(), allowing the union conversion hot path to probe existing Dictionary<string, string> data directly from input spans. This removes most temporary candidate-key allocations, reduces GC pressure, and improves throughput without changing dictionaries or conversion results.

The package still includes its netstandard2.0 asset for broad compatibility. Applications running on runtimes that do not select the .NET 9+ asset continue to use the string-allocation fallback, so the gains above should not be assumed for those targets.

Notes

Benchmarks include real-world system noise (IDE and background services), not isolated lab conditions.
The benchmark measures warmed S2T conversion. Conversion plans select only the required dictionary groups; StarterUnion rejects impossible candidate lengths, and UnionCache reuses the prepared accelerator.
Managed allocation now comes mainly from conversion output and buffer growth rather than temporary lookup keys.
Time and memory remain approximately linear with input size; expected GC activity is visible at larger sizes.
BenchmarkDotNet removed one outlier from the 100-, 1,000-, 100,000-, and 1,000,000-character measurements. For the 1,000,000-character case, two outliers were detected and one was removed.
Results are specific to the listed hardware, runtime, input distribution, and system load. Treat them as comparative measurements rather than universal latency guarantees.

Conclusion

OpenccNetLib 1.6.2 delivers a clear performance step forward on .NET 9 and later: the measured workload is 1.25×–2.75× faster than v1.6.1, while managed allocation falls by approximately 81%–98%. At one million characters, conversion improves from ~20.0 ms to ~11.45 ms and allocation drops from ~75.7 MB to ~9.8 MB, with the same deterministic conversion behavior and a preserved .NET Standard 2.0 compatibility path.

⏱ Relative Performance Chart

🟢 Highlights (OpenccNetLib v1.6.2)

🚀 High throughput: processes 1M characters in ~11.45 ms, or roughly 87 million characters/second on the tested Intel i5-13400 system.
📉 Much lower allocation: uses about 9.8 MB for the 1M-character conversion, down from about 75.7 MB in v1.6.1.
⚙️ Modern-runtime fast path: .NET 9+ uses allocation-free span-key dictionary probes; .NET Standard 2.0 retains the compatible string-key fallback.
📌 Predictable scaling: both elapsed time and memory remain approximately linear as input size grows.
📚 Same conversion semantics: the optimization changes candidate lookup mechanics, not dictionary selection, longest-match behavior, or output.

API Reference

`Opencc` Class

🔧 Constructors

Opencc(string config = null)
Creates a new converter using a configuration name (e.g., "s2t", "t2s").
This overload is compatible with existing code but requires string-based config.
Opencc(OpenccConfig configEnum)
Creates a new converter using the strongly-typed OpenccConfig enum
(e.g., OpenccConfig.S2T, OpenccConfig.T2S).
Recommended for all new code because it avoids magic strings.

🔁 Conversion Methods

string Convert(string inputText, bool punctuation = false)
Convert text according to the current config and punctuation mode.
string S2T(string inputText, bool punctuation = false)
string T2S(string inputText, bool punctuation = false)
string S2Tw(string inputText, bool punctuation = false)
string Tw2S(string inputText, bool punctuation = false)
string S2Twp(string inputText, bool punctuation = false)
string Tw2Sp(string inputText, bool punctuation = false)
string S2Hkp(string inputText, bool punctuation = false)
string Hk2Sp(string inputText, bool punctuation = false)
string T2Hkp(string inputText)
string Hk2Tp(string inputText)
string S2Hk(string inputText, bool punctuation = false)
string Hk2S(string inputText, bool punctuation = false)
string T2Tw(string inputText)
string T2Twp(string inputText)
string Tw2T(string inputText)
string Tw2Tp(string inputText)
string T2Hk(string inputText)
string Hk2T(string inputText)
string T2Jp(string inputText)
string Jp2T(string inputText)

⚙️ Configuration

Opencc supports both string-based and enum-based configuration APIs.
Internally, all configurations are stored as a strongly typed OpenccConfig identifier;
string APIs are provided for backward compatibility and convenience.

Recommended: Use the OpenccConfig enum–based APIs whenever possible.
String-based APIs are fully supported but are considered legacy-style convenience helpers.

Instance Configuration APIs

string Config { get; set; }
Gets or sets the current conversion configuration using a canonical string
(for example, "s2t", "tw2sp").
Invalid values automatically fall back to "s2t" and update the internal error status.
void SetConfig(string config)
Sets the conversion configuration using a string name.
Comparison is case-insensitive and ignores surrounding whitespace.
Falls back to "s2t" if the value is invalid.
void SetConfig(OpenccConfig configEnum)
Sets the conversion configuration using a strongly typed OpenccConfig enum value.
This is the preferred and recommended approach for type safety, IDE support, and interop scenarios (P/Invoke, JNI, bindings).
string GetConfig()
Returns the current configuration as a canonical lowercase string
(for example, "s2tw").
OpenccConfig GetConfigId()
Returns the current configuration as an OpenccConfig enum value.
This reflects the authoritative internal configuration state.
string GetLastError()
Returns the most recent configuration-related error message, if any.
A null value indicates that no configuration error is currently recorded.

📋 Validation and Helper APIs

The following static helpers are provided for validation, parsing, and discovery of supported configurations:

static bool TryParseConfig(string config, out OpenccConfig result)
Attempts to parse a configuration string into the corresponding OpenccConfig enum value.
Comparison is case-insensitive and ignores leading or trailing whitespace.
Returns false if the input is null, empty, or not a recognized configuration.
static bool IsValidConfig(string config)
Determines whether the specified string represents a supported OpenCC configuration.
static IReadOnlyCollection<string> GetSupportedConfigs()
Returns a read-only collection of all supported configuration names
(canonical lowercase strings).
The returned collection is stable and does not allocate on each call.
static int ZhoCheck(string inputText)
Detects whether the input text is likely:
- 2 → Simplified Chinese
- 1 → Traditional Chinese
- 0 → Neither / unknown
string NormalizeCompat(string text) Normalizes mapped CJK Compatibility Ideographs with the built-in Unicode compatibility table. Use this as an optional pre-processing step before Convert(...) when input may contain forms such as 金. Unmapped text is preserved unchanged.

📚 Dictionary Provider APIs

OpenccNetLib exposes dictionary provider APIs for advanced scenarios such as custom dictionaries, generated dictionary artifacts, test fixtures, and tooling. Most applications can use the built-in dictionary without calling these APIs.

`Opencc` dictionary activation helpers

static void UseCustomDictionary(DictionaryMaxlength customDictionary) Sets the active conversion dictionary provider to a custom DictionaryMaxlength instance and clears cached conversion plans. Call this once during application startup, before creating converters that should use the custom dictionary. Treat the chosen dictionary as the shared application provider; if it must change, recreate existing Opencc instances after setting the new provider.
static void UseDefaultDictionary() Restores the active provider to the built-in dictionary and clears cached conversion plans.
static void UseDictionaryFromPath(string dictionaryRelativePath) Loads OpenCC text dictionary files with DictionaryLib.FromDicts(dictionaryRelativePath) and activates the result.
static void UseDictionaryFromJsonString(string jsonString) Deserializes a DictionaryMaxlength JSON payload and activates it as the custom dictionary provider.

`DictionaryLib` provider and cache APIs

static DictionaryMaxlength Provider { get; } Returns the shared built-in dictionary instance.
static ConversionPlanCache PlanCache { get; } Returns the active global conversion plan cache.
static DictionaryMaxlength GetActiveProvider() Returns the dictionary instance currently supplied by the active provider delegate.
static DictionaryMaxlength New() Returns the built-in dictionary and resets the active provider to the built-in dictionary.
static void SetDictionaryProvider(DictionaryMaxlength dictionary) Sets the active dictionary provider to a fixed DictionaryMaxlength instance and publishes a fresh plan cache.
static void ResetDictionaryProviderToDefault() Restores the active dictionary provider to the built-in dictionary and publishes a fresh plan cache.

`DictionaryLib` loading APIs

static DictionaryMaxlength FromDicts(string relativeBaseDir = "dicts", IDictionary<DictSlot, string> overrides = null, IDictionary<DictSlot, string> appends = null) Loads OpenCC text dictionary files, optionally replacing slots with overrides or extending slots with appends.

static DictionaryMaxlength WithCustomDicts(DictionaryMaxlength dict, IEnumerable<CustomDictSpec> specs) Applies post-load customization to an already loaded dictionary provider. Each spec targets one DictSlot, reads optional Paths and/or Pairs, and applies them with CustomDictMode.Append or CustomDictMode.Override.
static DictionaryMaxlength FromJson(string relativePath = "dicts/dictionary_maxlength.json") Loads and normalizes a JSON dictionary payload.
static DictionaryMaxlength DeserializedFromJson(string path) Compatibility wrapper around FromJson(path).
static DictionaryMaxlength FromCbor(string relativePath = "dicts/dictionary_maxlength.cbor") Loads and normalizes a CBOR dictionary payload.
static DictionaryMaxlength LoadJsonCompressed(string path) Loads and normalizes a Zstandard-compressed JSON dictionary payload.

`DictionaryLib` serialization APIs

The serialization helpers accept an optional DictionaryMaxlength dictionary = null parameter. When omitted, they load from the default OpenCC text dictionary sources with FromDicts().

static void SerializeToJson(string path, DictionaryMaxlength dictionary = null) Writes a dictionary to indented JSON.
static void SerializeToJsonUnescaped(string path, DictionaryMaxlength dictionary = null) Writes indented UTF-8 JSON without escaping non-ASCII characters.
static void SaveCbor(string path, DictionaryMaxlength dictionary = null) Writes a dictionary as CBOR.
static byte[] ToCborBytes(DictionaryMaxlength dictionary = null) Returns a CBOR-encoded dictionary payload.
static void SaveJsonCompressed(string path, DictionaryMaxlength dictionary = null) Writes a dictionary as Zstandard-compressed JSON.

var dict = DictionaryLib.FromDicts(
    appends: new Dictionary<DictSlot, string>
    {
        [DictSlot.STPhrases] = "./UserDict.txt"
    });

DictionaryLib.SerializeToJson("./custom-dictionary.json", dict);
DictionaryLib.SaveCbor("./custom-dictionary.cbor", dict);
DictionaryLib.SaveJsonCompressed("./custom-dictionary.zstd", dict);

Notes

All configuration inputs ultimately resolve to a single internal OpenccConfig identifier.
Invalid configuration values never throw; they safely fall back to "s2t".
Enum-based APIs are future-proof and align with the C API, Rust core, and other language bindings.

Dictionary Data

Dictionaries are loaded and cached on first use.
Data files are expected in the dicts/ directory (see DictionaryLib for details).

Add-On CLI Tools (Separated from OpenccNetLib)

`OpenccNet dictgen`

Description:
  Generate OpenccNetLib dictionary files.
  
  Examples:
    OpenccNet dictgen
      Generate default Zstd dictionary (dictionary_maxlength.zstd)
  
    OpenccNet dictgen -f cbor
      Generate CBOR dictionary for interop
  
    OpenccNet dictgen -f json --unescape
      Generate readable JSON dictionary without \uXXXX escapes
  

Usage:
  OpenccNet dictgen [options]

Options:
  -f, --format <format>            Dictionary format: zstd|cbor|json [default: zstd]
  -o, --output <output>            Output filename. Default: dictionary_maxlength.<ext>
  -b, --base-dir <base-dir>        Base directory containing OpenCC-style .txt dictionary sources (for dictgen) [default: dicts]
  -u, --unescape                   For JSON format only: write readable Unicode characters instead of \uXXXX escapes
  -D, --custom-dict <custom-dict>  Load custom dictionary: <slot>:<mode>:<path>.
                                   Example: HkPhrasesRev:append:my_hk_dict.txt
                                   Available slots: STCharacters, STPhrases, STPunctuations, TSCharacters, TSPhrases, TSPunctuations, TWPhrases, TWPhrasesRev, 
                                   TWVariants, TWVariantsRev, TWVariantsRevPhrases, HKVariants, HKVariantsRev, HKVariantsRevPhrases, JPSCharacters, JPSPhrases, 
                                   TWVariantsPhrases, HKVariantsPhrases, JPSCharactersRev, HKPhrases, HKPhrasesRev
  -?, -h, --help                   Show help and usage information

`OpenccNet convert`

Description:
  Convert text using OpenccNetLib configurations.

Usage:
  OpenccNet convert [options]

Options:
  -i, --input <input>               Read original text from file <input>
  -o, --output <output>             Write original text to file <output>
  -c, --config <config> (REQUIRED)  Conversion configuration.
                                    Valid options: s2t, t2s, s2tw, tw2s, s2twp, tw2sp, s2hkp, hk2sp, t2hkp, hk2tp, s2hk, hk2s, t2tw, tw2t, t2twp, tw2tp, t2hk, 
                                    hk2t, t2jp, jp2t
  -p, --punct                       Punctuation conversion.
  --detofu <detofu>                 Apply tofu-safe fallback after conversion: all, ext-b, ext-c, ext-d, ext-e, ext-f, ext-g, ext-h, ext-i
  --detofu-file <detofu-file>       Load additional DeTofu fallback mappings from a UTF-8 text file. Custom mappings override built-in mappings (requires 
                                    --detofu)
  -I, --keep-ids                    Preserve Unicode IDS expressions during conversion.
  -n, --norm-compat                 Normalize CJK Compatibility Ideographs before conversion.
  -D, --custom-dict <custom-dict>   Load custom dictionary: <slot>:<mode>:<path>.
                                    Example: HkPhrasesRev:append:my_hk_dict.txt
                                    Available slots: STCharacters, STPhrases, STPunctuations, TSCharacters, TSPhrases, TSPunctuations, TWPhrases, TWPhrasesRev, 
                                    TWVariants, TWVariantsRev, TWVariantsRevPhrases, HKVariants, HKVariantsRev, HKVariantsRevPhrases, JPSCharacters, 
                                    JPSPhrases, TWVariantsPhrases, HKVariantsPhrases, JPSCharactersRev, HKPhrases, HKPhrasesRev
  --in-enc <in-enc>                 Encoding for input: UTF-8|UNICODE|GBK|GB2312|BIG5|Shift-JIS [default: UTF-8]
  --out-enc <out-enc>               Encoding for output: UTF-8|UNICODE|GBK|GB2312|BIG5|Shift-JIS [default: UTF-8]
  -?, -h, --help                    Show help and usage information

Example: append a custom Hong Kong phrase dictionary for hk2sp using the verified portable token.

data\my_hk_dict.txt:

# Custom Dictionary

細路哥	小男孩

"這個細路哥很靈活" | .\OpenccNet.exe convert -c hk2sp -D 'hkphrasesrev:append:data\my_hk_dict.txt'
这个小男孩很灵活
✅ Conversion (hk2sp): <stdin> → <stdout>

Repeat -D or --custom-dict to apply multiple specifications in command-line order:

.\OpenccNet.exe convert -c hk2sp -i input.txt -o output.txt `
  -D 'hkphrasesrev:append:data\my_hk_dict.txt' `
  --custom-dict 'tsphrases:append:data\company_ts_phrases.txt'

`OpenccNet office`

Description:
  Convert Office documents or EPUB using OpenccNetLib.

Usage:
  OpenccNet office [options]

Options:
  -i, --input <input>               Input Office document <input>
  -o, --output <output>             Output Office document <output>
  -c, --config <config> (REQUIRED)  Conversion configuration.
                                    Valid options: s2t, t2s, s2tw, tw2s, s2twp, tw2sp, s2hkp, hk2sp, t2hkp, hk2tp, s2hk, hk2s, t2tw, tw2t, t2twp, tw2tp, t2hk, 
                                    hk2t, t2jp, jp2t
  -p, --punct                       Enable punctuation conversion.
  -f, --format <format>             Force Office document format: docx | xlsx | pptx | odt | ods | odp | epub
  -k, --keep-font                   Preserve font names in Office documents [default: true]. Use --keep-font:false to disable.
  -q, --quiet                       Suppress status and progress output; only errors will be shown.
  -D, --custom-dict <custom-dict>   Load custom dictionary: <slot>:<mode>:<path>.
                                    Example: HkPhrasesRev:append:my_hk_dict.txt
                                    Available slots: STCharacters, STPhrases, STPunctuations, TSCharacters, TSPhrases, TSPunctuations, TWPhrases, TWPhrasesRev, 
                                    TWVariants, TWVariantsRev, TWVariantsRevPhrases, HKVariants, HKVariantsRev, HKVariantsRevPhrases, JPSCharacters, 
                                    JPSPhrases, TWVariantsPhrases, HKVariantsPhrases, JPSCharactersRev, HKPhrases, HKPhrasesRev
  -?, -h, --help                    Show help and usage information

`OpenccNet pdf`

Description:
  Convert a PDF to UTF-8 text using PdfPig + OpenccNetLib, with optional CJK paragraph reflow.

Usage:
  OpenccNet pdf [options]

Options:
  -i, --input <input>              Input PDF file <input.pdf>
  -o, --output <output>            Output text file <output.txt>
  -c, --config <config>            Conversion configuration.
                                   Valid options: s2t, t2s, s2tw, tw2s, s2twp, tw2sp, s2hkp, hk2sp, t2hkp, hk2tp, s2hk, hk2s, t2tw, tw2t, t2twp, tw2tp, t2hk, 
                                   hk2t, t2jp, jp2t
  -p, --punct                      Enable punctuation conversion.
  -H, --header                     Add [Page x/y] headers to the extracted text.
  -r, --reflow                     Reflow CJK paragraphs into continuous lines.
  -C, --compact                    Use compact reflow (fewer blank lines between paragraphs). Only meaningful with --reflow.
  -q, --quiet                      Suppress status and progress output; only errors will be shown.
  -e, --extract                    Extract text from PDF only (no OpenCC conversion).
  -n, --norm-compat                Normalize CJK Compatibility Ideographs before conversion.
  -D, --custom-dict <custom-dict>  Load custom dictionary: <slot>:<mode>:<path>.
                                   Example: HkPhrasesRev:append:my_hk_dict.txt
                                   Available slots: STCharacters, STPhrases, STPunctuations, TSCharacters, TSPhrases, TSPunctuations, TWPhrases, TWPhrasesRev, 
                                   TWVariants, TWVariantsRev, TWVariantsRevPhrases, HKVariants, HKVariantsRev, HKVariantsRevPhrases, JPSCharacters, JPSPhrases, 
                                   TWVariantsPhrases, HKVariantsPhrases, JPSCharactersRev, HKPhrases, HKPhrasesRev
  -?, -h, --help                   Show help and usage information

Usage Notes — `OpenccNet pdf`

PDF extraction engine

OpenccNet pdf uses a text-based PDF extraction engine (PdfPig) and is intended for digitally generated PDFs (e-books, research papers, reports).

✅ Works best with selectable text
❌ Does not perform OCR on scanned/image-only PDFs
❌ Visual layout (columns, tables, figures) is not preserved

CJK paragraph reflow

The --reflow option applies a CJK-aware paragraph reconstruction pipeline, designed for Chinese novels, essays, and academic text.

Reflow attempts to:

Join artificially wrapped lines
Repair cross-line splits (e.g. 面 + 容 → 面容)
Preserve headings, short titles, dialog markers, and metadata-like lines

⚠️ Important limitations

Reflow is heuristic-based
It is not suitable for:
- Poetry
- Comics / scripts
- Highly informal or experimental layouts
Web novels often use inconsistent formatting and may require tuning

`--compact` mode

When used together with --reflow, --compact:

Reduces excessive blank lines
Produces denser, book-like paragraphs
Is recommended for long-form reading or further text processing

--compact has no effect unless --reflow is enabled.

Page headers

Using --header inserts markers such as:

=== [Page 12/240] ===

This is useful for:

Debugging extraction issues
Locating original PDF pages
Avoiding empty or ambiguous page boundaries

Quiet mode

--quiet suppresses:

Progress bars
Status messages
Informational logs

Only errors will be printed.
Recommended for batch processing or script integration.

Output encoding

Output text is always written as UTF-8
Line endings follow the host platform

If you need other encodings, convert the output text using standard tools after extraction.

Recommended Workflows

Simple PDF → Traditional Chinese text

OpenccNet pdf -i input.pdf -o output.txt -c s2t -r

Compact novel conversion with page markers

OpenccNet pdf -i novel.pdf -o novel.txt -c s2tw -r --compact -H

Batch / automation use

OpenccNet pdf -i file.pdf -o out.txt -c t2s -r -q

Project That Use OpenccNetLib

OpenccNetLibGui : A GUI application for OpenccNetLib, providing a user-friendly interface for Traditional/Simplified Chinese text conversion.

License

This project is licensed under the MIT License. See the LICENSE file for details.

See THIRD_PARTY_NOTICES.md for bundled OpenCC lexicons (Apache License 2.0).

OpenccNet is not affiliated with the original OpenCC project, but aims to provide a compatible and high-performance solution for .NET developers.

Name		Name	Last commit message	Last commit date
Latest commit History 494 Commits
.github/workflows		.github/workflows
OpenccNet		OpenccNet
OpenccNetLib.Benchmarks		OpenccNetLib.Benchmarks
OpenccNetLib		OpenccNetLib
OpenccNetTests		OpenccNetTests
.gitattributes		.gitattributes
.gitignore		.gitignore
LICENSE		LICENSE
OpenccNet.sln		OpenccNet.sln
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation

OpenccNet

Table of Contents

Features

Installation

Usage

Basic Example

Supported Configurations

Example: Convert with Punctuation

Example: Hong Kong Phrase Conversion

Example: Switching Config Dynamically

💡 Tips

Direct API Methods

Preserve IDS expressions

CJK Compatibility Ideograph Normalization

DeTofu Display Compatibility

Error Handling

Language Detection

User Custom Dictionaries

Portable custom-dictionary specifications

File-level customization

Override an entire slot

Post-load customization

Exact in-memory fallback pairs

Custom dictionary file format

Supported dictionary slots

Recommended usage

Why no user_dict slot?

🆕 Office Document & EPUB Conversion (In-Memory, No Temp Files Required)

✔ Supported formats

📦 Example: Convert Office Document In-Memory

🔁 Backward-Compatible String Overload

⚡ Async API (Recommended for Server/Web)

📁 Convert Files (Convenience wrappers)

🔍 What does conversion do?

🛡 Error Handling

🧪 Unit Tested (MSTest)

🚀 Why This Matters

Performance

🚀 Performance Benchmark for OpenccNetLib 1.6.2

S2T Conversion (.NET 9+ Span-Key Optimizations, Real-World Load)

Environment

Results

Summary

Comparison with v1.6.1

Notes

Conclusion

⏱ Relative Performance Chart

🟢 Highlights (OpenccNetLib v1.6.2)

API Reference

Opencc Class

🔧 Constructors

🔁 Conversion Methods

⚙️ Configuration

Instance Configuration APIs

📋 Validation and Helper APIs

📚 Dictionary Provider APIs

Opencc dictionary activation helpers

DictionaryLib provider and cache APIs

DictionaryLib loading APIs

DictionaryLib serialization APIs

Notes

Dictionary Data

Add-On CLI Tools (Separated from OpenccNetLib)

OpenccNet dictgen

OpenccNet convert

OpenccNet office

OpenccNet pdf

Usage Notes — OpenccNet pdf

PDF extraction engine

CJK paragraph reflow

--compact mode

Page headers

Quiet mode

Output encoding

Recommended Workflows

Project That Use OpenccNetLib

Why no `user_dict` slot?

`S2T` Conversion (.NET 9+ Span-Key Optimizations, Real-World Load)

`Opencc` Class

`Opencc` dictionary activation helpers

`DictionaryLib` provider and cache APIs

`DictionaryLib` loading APIs

`DictionaryLib` serialization APIs

`OpenccNet dictgen`

`OpenccNet convert`

`OpenccNet office`

`OpenccNet pdf`

Usage Notes — `OpenccNet pdf`

`--compact` mode