GO — Healthy across the board

• Last commit 1d ago
• 9 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 63% of recent commits

_{Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests}

OpenCC is a C++ library for bidirectional character and phrase-level conversion between Traditional Chinese, Simplified Chinese, and Japanese Kanji (Shinjitai), with support for regional variants (Mainland, Taiwan, Hong Kong). It solves the problem of text normalization across Chinese-speaking regions by maintaining separate phrase-level and character-level conversion tables with strict one-to-many relationship handling. Monorepo structure: core C++ library in src/, bindings for Python/Node.js/JavaScript in separate entry points, dictionary data in data/config/ (JSON schema-validated), CLI utilities, and comprehensive CI pipelines. Config-driven architecture: conversion behavior defined in JSON files (s2t.json, t2hk.json, etc.) validated against opencc_config.schema.json, enabling rule modification without recompilation.

Developers building Chinese text processing systems (NLP pipelines, search engines, localization tools) who need programmatic Chinese variant conversion; linguists and CJK content platforms requiring accurate regional idiom handling; maintainers of multilingual UIs targeting Chinese-speaking markets.

Production-ready and actively maintained: v1.3.0 released with extensive CI coverage (CMake, Bazel, MSVC, Node.js, Python workflows on GitHub Actions). Distributed across major package managers (Debian, Arch, Homebrew, npm, PyPI, Bazel Registry). Monolithic codebase with 569K lines of C++ indicates maturity, though commit recency not visible from provided data.

Single maintainer (BYVoid) is a potential continuity risk. Minimal external dependencies (only absl-py>=0.7.1 listed) reduces supply-chain risk. Multiple build systems (CMake, Bazel, binding.gyp for Node.js) increases maintenance surface area. Config validation tests (ConfigDictValidationTest.cpp, ConfigSchemaValidationTest.cpp) suggest known failure modes, but test coverage across core conversion logic not evident from file list.

Active multi-platform CI/CD: workflows for CMake, Bazel, MSVC, MinGW, Node.js, Python, with automated package releases (Debian, npm, PyPI). Dictionary validation appears to be an ongoing quality gate (check-dictionary-sorted.yml workflow). Windows (WinGet) and Bazel Registry distributions recently added. Node-gyp binding.gyp present, suggesting active JavaScript ecosystem engagement.

git clone https://github.com/BYVoid/OpenCC.git
cd OpenCC
mkdir build && cd build
cmake ..
make
make install

Or for Python bindings: pip install opencc (prebuilt on PyPI).

Daily commands: Development: make (Makefile in root) or cmake --build build/ after cmake ... For Python: python -m opencc --help. For Node.js: npm test (npm CI workflow present). For CLI: opencc -i input.txt -o output.txt -c s2t.json (once installed).

• src/opencc.h — Primary public API header; all contributors must understand the core conversion interface and class hierarchy
• src/Config.hpp — Configuration loading and validation; essential for understanding how conversion pipelines are defined and composed
• data/dictionary — Dictionary data directory containing character/phrase mappings; core data assets that drive all conversions
• data/config — Conversion configuration files (s2t, t2s, hk2s, etc.); defines all supported conversion scenarios
• CMakeLists.txt — Primary build configuration for C++ library; contributors need to understand build targets and dependencies
• src/Converter.hpp — Main conversion engine; implements the text transformation pipeline using dictionaries and segmentation
• src/DictEntry.hpp — Dictionary entry data structure; foundational for understanding phrase matching and conversion logic

Add a new Chinese variant conversion (e.g., Cantonese variant)

1. Create character mapping dictionary file in data/dictionary/ (e.g., HKVariants.txt with format 'Traditional_Char Variant_Char') (data/dictionary/HKVariants.txt)
2. Create phrase mapping file (e.g., HKVariantsRevPhrases.txt) for multi-character conversions if needed (data/dictionary/HKVariantsRevPhrases.txt)
3. Create JSON configuration file in data/config/ (e.g., hk2t.json) referencing the dictionaries and conversion chain (data/config/hk2t.json)
4. Update CMakeLists.txt data/CMakeLists.txt to include new dictionary files in build targets (data/CMakeLists.txt)
5. Run data/scripts/sort_all.py to validate dictionary sorting and consistency (data/scripts/sort_all.py)
6. Add corresponding unit test in src/tests/ to verify conversion accuracy (data/dictionary/DictionaryTest.cpp)

Fix a conversion accuracy issue in phrase mappings

1. Identify which dictionary file contains the incorrect mapping (e.g., STPhrases.txt for S→T phrase issues) (data/dictionary/STPhrases.txt)
2. Edit the phrase mapping file to correct or add the entry in format 'source_phrase target_phrase [weight]' (data/dictionary/STPhrases.txt)
3. Run data/scripts/sort.py on the modified file to maintain sort order and prevent conflicts (data/scripts/sort.py)
4. Add a test case in data/dictionary/DictionaryTest.cpp or data/config/ConfigDictValidationTest.cpp (data/dictionary/DictionaryTest.cpp)
5. Re-build with CMake or Bazel and verify the fix passes CI workflows (CMakeLists.txt)

Add Python binding support for a new conversion method

1. Add C++ method to Converter class (e.g., ConvertToHKVariant()) in src/Converter.hpp (src/Converter.hpp)
2. Implement the method in src/Converter.cpp with the conversion logic using the conversion chain (src/Converter.cpp)
3. Expose the method in Python bindings (src/py_opencc or similar) using pybind11 or CFFI (src/py_opencc)
4. Update .github/workflows/python.yml to test the new binding if needed (.github/workflows/python.yml)
5. Add Python unit test in test directory verifying the new method (data/dictionary/DictionaryTest.cpp)

Support a new conversion configuration variant (e.g., Traditional→Hong Kong variant)

1. Create new JSON config file in data/config/ (e.g., t2hk.json) defining the conversion chain with segment and conversion steps (data/config/t2hk.json)
2. Validate the config structure against opencc_config.schema.json (data/config/opencc_config.schema.json)
3. Reference required dictionary files in the config (e.g., TSCharacters.txt, HKVariants.txt) (data/dictionary/TSCharacters.txt)
4. Update src/Config.hpp to ensure the new config is loaded and parsed correctly if needed (src/Config.hpp)
5. Add integration test in data/config/ConfigDictValidationTest.cpp (data/config/ConfigDictValidationTest.cpp)

• CMake + Bazel — Multi-platform C++ build with consistent hermetic builds (Bazel); CMake for widespread compatibility and IDE support
• JSON configuration (RFC 7158) — Human-readable, standardized format for defining conversion chains; enables validation via JSON schema
• Darts-clone trie library (deps/darts-clone-0.32) — Fast double-array trie for phrase dictionary lookup; reduces memory footprint and O(n) lookup for phrase matching
• Python/Node.js bindings (pybind11/native modules) — Reaches broader ecosystem; enables integration into data pipelines and web services
• GitHub Actions multi-platform CI — Tests across Linux, Windows, macOS; validates CMake, Bazel, MSVC, MinGW, Node.js, and Python builds in parallel

• Dictionary-based conversion vs. machine learning models
  • Why: Deterministic, rule-based conversion guarantees 100% consistency and transparency; no training data required
  • Consequence: undefined

Config files (data/config/*.json) must be sorted lexicographically for performance (checked-dictionary-sorted.yml will fail otherwise). Dictionary data directory must be findable at runtime (install location or OPENCC_DATA_PATH env var). Python bindings require SWIG or compiled extension (absl-py dependency). Phrase-level and character-level lookups have different code paths — mutations to one may not affect the other. Windows builds require MSVC or MinGW (separate workflows suggest environment-specific quirks).

• One-to-Many Character Mapping — OpenCC's core challenge: a single Simplified character can map to multiple Traditional forms depending on phrase context (e.g., '干' → '乾'/'幹'); the codebase separates phrase-level and char-level tables to handle this, a distinction absent from naive mapping approaches
• Phrase-Level vs Character-Level Conversion — OpenCC applies phrase lookups before falling back to character mappings; understanding this two-tier hierarchy is essential to debug why certain conversions succeed or fail and to extend the dictionary correctly
• Lexicographic Dictionary Sorting — The check-dictionary-sorted.yml workflow enforces sorted phrase tables for binary search performance; violation causes CI failure and indicates misunderstanding of OpenCC's lookup implementation
• Configuration-Driven Conversion Rules — Conversion behavior is entirely defined in JSON configs (data/config/*.json) validated against opencc_config.schema.json, not hardcoded; this enables zero-recompilation rule changes and regional variant swapping
• Multi-Target Build System (CMake + Bazel + node-gyp) — OpenCC targets C++, Python, Node.js, and system package managers; understanding build tool orchestration (when to modify CMakeLists.txt vs binding.gyp vs BUILD.bazel) is critical for cross-platform changes
• Regional Idiom Normalization (Mainland/Taiwan/HK/Japan) — Beyond character conversion, OpenCC maps region-specific phrases (e.g., '鼠標' in Mainland → '滑鼠' in Taiwan); this requires separate dictionaries and config chains (s2tw.json, s2hk.json, etc.) and is the reason the library exists
• Native Language Bindings via FFI/SWIG — The C++ core is wrapped for Python, Node.js, and JavaScript (likely WASM); contributing to bindings requires understanding both the C++ interface and the target language's foreign function interface semantics

• hotoo/pinyin — Complementary Chinese text processing library; handles pinyin conversion while OpenCC handles variant normalization — often used together in CJK pipelines
• yanyiwu/cppjieba — Chinese word segmentation library frequently paired with OpenCC for full text preprocessing (segment, then convert variants)
• fxsjy/jieba — Python wrapper around cppjieba; same ecosystem as OpenCC's Python bindings for end-to-end Chinese NLP
• NaturalNode/natural — JavaScript/Node.js NLP toolkit; potential consumer of OpenCC bindings for Chinese text normalization in Node.js projects
• golang-design/go-opencc — Go binding to OpenCC C++ library; demonstrates cross-language adoption pattern and alternative build approach via FFI

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive CI workflow for Ruby bindings

The repo has CI workflows for Node.js, Python, and MSVC, but no Ruby workflow despite OpenCC being a polyglot library. Given the .github/workflows/ structure with multiple language-specific CI files, a Ruby workflow would ensure binding quality and catch regressions early. This aligns with the project's multi-platform philosophy.

• [ ] Create .github/workflows/ruby.yml following the pattern of .github/workflows/nodejs.yml and .github/workflows/python.yml
• [ ] Test against multiple Ruby versions (2.7, 3.0, 3.1, 3.2) if Ruby bindings exist in the codebase
• [ ] Include gem build and test steps, similar to npm and pip workflows
• [ ] Add badge to README.md alongside existing language CI badges

Add validation tests for all config dictionary mappings

The repo has 14+ conversion config files (data/config/*.json) and multiple dictionary files, but only ConfigDictValidationTest.cpp and ConfigSchemaValidationTest.cpp exist. There's no automated test verifying that conversions like s2t.json, t2s.json, hk2s.json produce expected outputs. Adding integration tests would catch dictionary corruption and config inconsistencies.

• [ ] Create data/config/ConfigIntegrationTest.cpp to test actual conversion outputs for each config file
• [ ] Add test cases for bidirectional conversions (e.g., s2t then t2s should approach original)
• [ ] Test edge cases with the non-BMP character test mentioned in DictionaryNonBmpTest.cpp
• [ ] Integrate into CMake and Bazel build systems (reference data/config/BUILD.bazel)

Add API usage documentation for language bindings

While CONTRIBUTING.md and DESIGN_PRINCIPLES.md exist, there's no binding_docs/ or section in README explaining how to use OpenCC from Node.js, Python, and other languages. Given the sophisticated binding workflows in place, contributors and users need clear examples for each language binding.

• [ ] Create docs/bindings/ directory with language-specific guides
• [ ] Add docs/bindings/nodejs.md with example code for Node.js binding usage (reference .github/workflows/nodejs.yml for tested scenarios)
• [ ] Add docs/bindings/python.md with example code for Python binding usage (reference .github/workflows/python.yml and MANIFEST.in)
• [ ] Link binding documentation from main README.md in a new 'Language Bindings' section

• Add coverage report badge and tooling: .github/workflows lacks coverage.yml; set up gcov/lcov in CMake and publish to Codecov to establish baseline test coverage for src/opencc.cpp and src/dict.cpp
• Document regional variant selection examples: README mentions Taiwan/HK/Mainland variants but data/config/*.json filenames (hk2s.json, t2tw.json) are terse; create data/config/VARIANTS.md explaining when to use each config file with before/after examples
• Create TypeScript definitions for Node.js bindings: binding.gyp exists but no *.d.ts found in file list; generate opencc.d.ts for npm package to improve IDE support and reduce runtime errors in JS codebases

The OpenCC codebase shows a reasonable security posture overall. The primary concern is the loose dependency specification for absl-py which could allow installation of unvetted versions. The project lacks visible security documentation (SECURITY.md) and relies on multiple build systems which increases complexity and potential for misconfiguration. No obvious injection vulnerabilities, hardcoded secrets, or critical infrastructure issues were detected in the provided file structure. Recommendations focus on tightening dependency constraints, improving security documentation, and auditing build pipeline configurations.

• Medium · Outdated Python Dependency Specification — Dependencies/Package file (absl-py>=0.7.1). The dependency file specifies 'absl-py>=0.7.1' which is extremely permissive. This version was released in 2019 and the constraint allows installation of any version from 0.7.1 onwards without upper bounds, potentially introducing security vulnerabilities from newer versions with breaking changes or security issues. Fix: Specify a more restrictive version constraint, such as 'absl-py>=0.15.0,<1.0.0' (using a recent stable version). Regularly audit and update dependencies to versions with known security patches. Use dependency management tools like pip-audit or Safety to scan for known vulnerabilities.
• Low · Missing Security Policy Documentation — Repository root. No SECURITY.md or security policy file is visible in the repository. This makes it difficult for security researchers to report vulnerabilities responsibly. Fix: Create a SECURITY.md file that outlines how to report security vulnerabilities privately, response timelines, and supported versions for security updates.
• Low · Multiple Build System Configurations — CMakeLists.txt, BUILD.bazel, binding.gyp, build.cmd. The project uses multiple build systems (CMake, Bazel, MSVC, npm, etc.) which increases the attack surface if any configuration is misconfigured. Complex build pipelines can introduce supply chain risks. Fix: Regularly audit build configurations for security issues. Ensure all build systems use consistent security practices. Pin dependencies in all build configurations. Use signed releases and verify checksums.
• Low · Extensive GitHub Actions Workflows — .github/workflows/. The project uses multiple GitHub Actions workflows (.github/workflows/) which may have access to secrets and credentials. If workflow files are not properly secured, they could be vulnerable to injection attacks or credential exposure. Fix: Review all workflow files for: (1) Proper input sanitization to prevent injection attacks, (2) Minimal permissions and secrets access, (3) Use of specific action versions rather than 'latest' or 'main' branches, (4) Audit access controls for who can trigger workflows.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/BYVoid/OpenCC shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live BYVoid/OpenCC repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/BYVoid/OpenCC.

What it runs against: a local clone of BYVoid/OpenCC — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in BYVoid/OpenCC | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of BYVoid/OpenCC. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/BYVoid/OpenCC.git
#   cd OpenCC
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of BYVoid/OpenCC and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "BYVoid/OpenCC(\\.git)?\\b" \\
  && ok "origin remote is BYVoid/OpenCC" \\
  || miss "origin remote is not BYVoid/OpenCC (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "src/opencc.h" \\
  && ok "src/opencc.h" \\
  || miss "missing critical file: src/opencc.h"
test -f "src/Config.hpp" \\
  && ok "src/Config.hpp" \\
  || miss "missing critical file: src/Config.hpp"
test -f "data/dictionary" \\
  && ok "data/dictionary" \\
  || miss "missing critical file: data/dictionary"
test -f "data/config" \\
  && ok "data/config" \\
  || miss "missing critical file: data/config"
test -f "CMakeLists.txt" \\
  && ok "CMakeLists.txt" \\
  || miss "missing critical file: CMakeLists.txt"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/BYVoid/OpenCC"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.