OpenccFmmsegLib 1.4.0

OpenccFmmsegLib

A .NET Standard 2.0 library providing a managed C# wrapper for the Rust-based opencc-fmmseg C API (OpenCC-compatible), enabling high-performance Chinese text conversion (Simplified / Traditional) in .NET applications.

This library focuses only on OpenCC-style conversion. For Jieba segmentation and keyword extraction, use OpenccJiebaLib instead.

Features

• OpenCC-compatible Chinese text conversion (Simplified / Traditional variants)
• Optional punctuation conversion
• Fast FMM-based segmentation engine under the hood (native Rust)
• Lightweight API with explicit native error-reporting semantics
• Safe native resource management via IDisposable

Supported Conversion Configurations

s2t, t2s, s2tw, tw2s, s2twp, tw2sp, s2hk, s2hkp, hk2s, hk2sp, t2tw, t2twp, t2hk, t2hkp, tw2t, tw2tp, hk2t, hk2tp, t2jp, jp2t

The phrase-aware Hong Kong configurations s2hkp, hk2sp, t2hkp, and hk2tp require native opencc-fmmseg-capi v0.11.5 or later. This package bundles v0.11.5.

Getting Started

Prerequisites

• .NET Standard 2.0 or higher (.NET Framework, .NET Core / 5+ / 6+, Mono, Xamarin, etc.)
• .NET 6.0 or later recommended
• Native opencc_fmmseg_capi library available at runtime

Installation

Option 1 — From NuGet (recommended)

dotnet add package OpenccFmmsegLib

The NuGet package includes prebuilt native runtimes and deploys them under:

runtimes/<RID>/native/

Shipped RIDs:

• win-x64
• linux-arm64
• linux-x64
• osx-x64
• osx-arm64

No manual copying is required when using NuGet.

Option 2 — Project Reference / Custom Native Builds

If you use a project reference or a custom native build, place the native library using the same layout as NuGet:

runtimes/<RID>/native/

Expected filenames:

• Windows: opencc_fmmseg_capi.dll
• Linux: libopencc_fmmseg_capi.so
• macOS: libopencc_fmmseg_capi.dylib

The built-in native loader will discover the library automatically.

🧪 Unit test projects must also have access to the native library. Use the same layout under the test project output directory.

Usage

using OpenccFmmsegLib;

using var opencc = new OpenccFmmseg();

string input = "汉字转换测试";
string result = opencc.Convert(input, "s2t");

Console.WriteLine(result); // 漢字轉換測試

int code = opencc.ZhoCheck(input);
Console.WriteLine(code); // 2 (Simplified Chinese)

Error Handling

• InvalidOperationException is thrown if initialization fails or a native error occurs.
• ObjectDisposedException is thrown by instance APIs after disposal, including for null or empty input.
• OpenccFmmseg.LastError() returns the last native error for the calling thread. Read it immediately after the failing native call, on the same thread, before an await or any other native OpenCC call on that thread.

Public API Overview

OpenccFmmseg

• string Convert(string input, string config, bool punctuation = false) Converts Chinese text using the specified canonical OpenCC configuration name and throws for invalid names.

• string Convert(string input, OpenccConfig configId, bool punctuation = false) Converts Chinese text using the OpenCC configuration Enum.

• string ConvertCfg(string input, OpenccConfig configId, bool punctuation = false) Converts Chinese text using the numeric-config native path with a typed config enum.

• string ConvertCfgMemLen(string input, int configId, bool punctuation = false) Uses the specialized explicit-length native buffer pipeline. Prefer Convert() or ConvertCfg() for ordinary conversion; this API's size-query and output passes add conversion overhead.

• byte[] ConvertCfgMemLenToUtf8Z(string input, int configId, bool punctuation = false) Returns UTF-8 output including a trailing NUL terminator for interop scenarios.

bool TryConvertCfgToUtf8(string input, int configId, bool punctuation, Span<byte> destination, out int requiredBytes) Writes UTF-8 output into a caller-provided buffer using the native size-query API.

*

bool TryConvertCfgToUtf8Into(string input, int configId, bool punctuation, Span<byte> destination, out int requiredBytes) Writes UTF-8 output into a caller-provided buffer using the explicit-length native API.

For both TryConvertCfgToUtf8* methods, false with requiredBytes > destination.Length means the buffer is too small; resize and retry. This is the expected result for an empty-buffer size query and is not a native error. For other false results, retrieve LastError() immediately on the same thread.

• int ZhoCheck(string input) Detects whether the input text is Simplified Chinese, Traditional Chinese, or non-Chinese.

• static string LastError() Returns the last error message reported by the native library for the calling thread.

• Implements IDisposable for deterministic native resource cleanup.

Troubleshooting

DllNotFoundException / Unable to load shared library 'opencc_fmmseg_capi'

• Ensure the native file exists under:

  runtimes/<RID>/native/
  

• Clean and rebuild the project after installing via NuGet

• Verify the correct file name for your platform

BadImageFormatException

• Architecture mismatch (x64 vs x86)
• Ensure your application and native library target the same architecture

Linux: library exists but cannot be loaded

• Place the .so next to the executable or set:

  export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$(pwd)
  

macOS: Gatekeeper / quarantine issues

xattr -dr com.apple.quarantine libopencc_fmmseg_capi.dylib

Thread Safety

• Do not share a single OpenccFmmseg instance across threads
• Create one instance per thread or scope
• Dispose instances promptly (using is recommended)

License

MIT License. See LICENSE.

Acknowledgements

• OpenCC
• opencc-fmmseg