zhtw 1.5.0__tar.gz

zhtw-1.5.0/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.9', '3.11', '3.12']
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Lint with ruff
+        run: ruff check .
+
+      - name: Run tests
+        run: pytest

zhtw-1.5.0/.github/workflows/publish.yml

@@ -0,0 +1,29 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install build tools
+        run: pip install build twine
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: twine upload dist/*

zhtw-1.5.0/.gitignore

@@ -0,0 +1,72 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Testing
+.tox/
+.nox/
+.coverage
+.coverage.*
+htmlcov/
+.pytest_cache/
+.hypothesis/
+
+# Mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Ruff
+.ruff_cache/
+
+# Distribution / packaging
+.Python
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Cache
+.zhtw-cache
+*.cache
+
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride

zhtw-1.5.0/CLAUDE.md

@@ -0,0 +1,208 @@
+# ZHTW - Claude AI 開發指南
+
+**專案名稱**: ZHTW - 簡轉繁台灣用語轉換器
+**作者**: rajatim
+**語言**: Python 3.9+
+**最後更新**: 2025-12-26
+
+---
+
+## 專案概述
+
+將程式碼和文件中的簡體中文轉換為台灣繁體中文用語的 CLI 工具。
+
+### 核心設計原則
+
+1. **完全離線** - 不傳送任何資料到外部伺服器
+2. **術語表優先** - 只轉換明確定義的詞彙，避免過度轉換
+3. **高效能** - Aho-Corasick 演算法處理大量術語
+4. **可擴充** - JSON 詞庫格式，易於維護
+
+### 為什麼不用 OpenCC？
+
+OpenCC 會過度轉換台灣正確的詞彙（如 權限→許可權）。我們使用精確術語表避免這問題。
+
+---
+
+## 專案結構
+
+```
+zhtw/
+├── src/zhtw/
+│   ├── __init__.py      # 版本號、匯出
+│   ├── cli.py           # CLI 入口 (click)
+│   ├── converter.py     # 核心轉換邏輯
+│   ├── dictionary.py    # 詞庫載入/管理
+│   ├── matcher.py       # Aho-Corasick 匹配器
+│   └── data/
+│       └── terms/
+│           ├── cn/          # 簡體 → 台灣繁體
+│           │   ├── base.json
+│           │   ├── it.json
+│           │   └── business.json
+│           └── hk/          # 港式 → 台灣繁體
+│               ├── base.json
+│               └── tech.json
+├── tests/
+├── pyproject.toml
+├── README.md
+└── CLAUDE.md            # 本文件
+```
+
+---
+
+## 核心模組說明
+
+### cli.py
+- 使用 `click` 框架
+- 子命令: `check`, `fix`
+- 參數: `--source`, `--dict`, `--exclude`, `--json`, `--verbose`, `--dry-run`
+
+### converter.py
+- `convert_file(path, matcher, fix)` - 處理單一檔案
+- `convert_directory(path, matcher, fix)` - 處理目錄
+- `process_directory()` - 主要入口，載入詞庫並處理
+
+### matcher.py
+- 使用 `pyahocorasick` 建立自動機
+- `Matcher` 類別:
+  - `find_matches(text)` - 找出所有匹配
+  - `find_matches_with_lines(text)` - 帶行列資訊
+  - `replace_all(text)` - 替換所有匹配
+
+### dictionary.py
+- `load_builtin(sources)` - 載入內建 cn/hk 詞庫
+- `load_dictionary(sources, custom_path)` - 主要載入函數
+- 支援簡單格式和擴展格式
+
+---
+
+## CLI 使用方式
+
+```bash
+# 檢查模式（只報告）
+zhtw check ./src
+
+# 修正模式（自動修改）
+zhtw fix ./src
+
+# 指定來源
+zhtw check ./src --source cn      # 只處理簡體
+zhtw check ./src --source hk      # 只處理港式
+zhtw check ./src --source cn,hk   # 兩者都處理（預設）
+
+# 自訂詞庫
+zhtw fix ./src --dict ./custom.json
+
+# JSON 輸出（CI/CD）
+zhtw check ./src --json
+
+# 模擬執行
+zhtw fix ./src --dry-run
+
+# 詳細輸出
+zhtw check ./src --verbose
+```
+
+---
+
+## 開發指令
+
+```bash
+# 安裝開發依賴
+pip install -e ".[dev]"
+
+# 執行測試
+pytest
+
+# 執行 lint
+ruff check .
+
+# 本地測試 CLI
+python -m zhtw check ./test-files
+```
+
+---
+
+## 詞庫格式
+
+### 簡單格式（v1.0）
+```json
+{
+  "version": "1.0",
+  "description": "說明文字",
+  "terms": {
+    "简体": "繁體"
+  }
+}
+```
+
+### 擴展格式（v1.5+，未來支援）
+```json
+{
+  "version": "1.5",
+  "terms": {
+    "文档": {
+      "target": "文件",
+      "category": "it",
+      "confidence": 1.0,
+      "context": "一般情境"
+    }
+  }
+}
+```
+
+---
+
+## 效能考量
+
+- **Aho-Corasick**: O(n) 時間複雜度掃描，不受術語數量影響
+- **預過濾**: 跳過不含中文字元的檔案（約 70%+）
+- **預設排除**: node_modules, .git, dist, build 等
+- **支援副檔名**: .py, .ts, .tsx, .js, .jsx, .java, .vue, .go, .rs, .json, .yml, .yaml, .md, .txt, .html, .css
+
+---
+
+## 新增詞彙
+
+1. 找到對應的詞庫檔案（cn/ 或 hk/）
+2. 新增 key-value 對
+3. 確保轉換在台灣用語中正確
+4. 提交 PR
+
+範例：
+```json
+{
+  "terms": {
+    "existing_term": "existing_translation",
+    "new_term": "新翻譯"
+  }
+}
+```
+
+---
+
+## 未來規劃
+
+### v2.0 LLM 整合
+- 詞彙探索: 用 LLM 發現新詞彙
+- 上下文感知: 依上下文判斷轉換
+- 主動學習: 收集使用者修正
+
+### v3.0 本地模型
+- 微調小型中文模型
+- 完全離線高準確度
+
+---
+
+## AI 開發注意事項
+
+1. **不要使用 OpenCC** - 會過度轉換台灣正確用語
+2. **不要呼叫外部 API** - 保持離線運作
+3. **詞庫修改要謹慎** - 確認轉換在台灣用語中正確
+4. **測試要全面** - 包含邊界案例和誤判測試
+5. **不要新增不確定的詞彙** - 寧可少轉不要錯轉
+
+---
+
+*rajatim 出品*

zhtw-1.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 rajatim
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

zhtw-1.5.0/PKG-INFO

@@ -0,0 +1,255 @@
+Metadata-Version: 2.4
+Name: zhtw
+Version: 1.5.0
+Summary: Simplified/HK Traditional to Taiwan Traditional Chinese Converter
+Project-URL: Homepage, https://github.com/rajatim/zhtw
+Project-URL: Repository, https://github.com/rajatim/zhtw
+Project-URL: Issues, https://github.com/rajatim/zhtw/issues
+Author-email: rajatim <rajatim@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: chinese,converter,i18n,simplified,taiwan,traditional
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.9
+Requires-Dist: click>=8.0
+Requires-Dist: pyahocorasick>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ZHTW
+
+> 簡轉繁台灣用語轉換器 | Simplified to Traditional Chinese (Taiwan) Converter
+
+[![CI](https://github.com/rajatim/zhtw/actions/workflows/ci.yml/badge.svg)](https://github.com/rajatim/zhtw/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**rajatim 出品**
+
+將程式碼和文件中的簡體中文轉換為台灣繁體中文用語。
+
+## 特色
+
+- **高效能** - Aho-Corasick 演算法，萬級術語秒級掃描
+- **完全離線** - 不傳送任何資料到外部伺服器
+- **可擴充詞庫** - JSON 格式，易於維護和貢獻
+- **精準轉換** - 術語表優先，避免過度轉換
+- **CI/CD 友善** - JSON 輸出，易於整合
+- **忽略註解** - 支援 `zhtw:disable` 跳過特定程式碼
+
+## 安裝
+
+```bash
+pip install zhtw
+```
+
+或從原始碼安裝：
+
+```bash
+git clone https://github.com/rajatim/zhtw.git
+cd zhtw
+pip install -e .
+```
+
+## 快速開始
+
+```bash
+# 檢查模式（只報告，不修改）
+zhtw check ./src
+
+# 修正模式（自動修改檔案）
+zhtw fix ./src
+
+# JSON 輸出（CI/CD 整合）
+zhtw check ./src --json
+
+# 使用自訂詞庫
+zhtw fix ./src --dict ./my-terms.json
+
+# 排除目錄
+zhtw check ./src --exclude node_modules,dist
+
+# 只處理簡體
+zhtw check ./src --source cn
+
+# 只處理港式
+zhtw check ./src --source hk
+
+# 模擬執行（不實際修改）
+zhtw fix ./src --dry-run
+
+# 顯示詞庫統計
+zhtw stats
+
+# 驗證詞庫品質
+zhtw validate
+```
+
+## 輸出範例
+
+```
+📁 掃描 ./src
+
+📄 src/components/Header.tsx
+   L12:5: "用户" → "使用者"
+      ...顯示用户資訊...
+
+📄 src/utils/api.ts
+   L8:10: "网络" → "網路"
+      ...檢查网络連線...
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+⚠️  發現 2 處問題（2 個檔案）
+   掃描: 150 個檔案 (跳過 45 個無中文檔案)
+```
+
+## 詞庫格式
+
+```json
+{
+  "version": "1.0",
+  "description": "自訂詞庫說明",
+  "terms": {
+    "文档": "文件",
+    "代码": "程式碼",
+    "软件": "軟體"
+  }
+}
+```
+
+## 內建詞庫
+
+| 來源 | 類別 | 詞彙數 | 說明 |
+|------|------|--------|------|
+| CN | base | 151 | 簡體基礎詞彙 |
+| CN | it | 132 | IT/程式術語 |
+| CN | business | 42 | 商業術語 |
+| HK | base | 42 | 港式基礎詞彙 |
+| HK | tech | 19 | 港式科技術語 |
+
+**總計：386 個詞彙**
+
+## 忽略註解
+
+在程式碼中使用註解來跳過特定內容的檢查：
+
+```python
+# 忽略當前行
+user_info = "用户信息"  # zhtw:disable-line
+
+# 忽略下一行
+# zhtw:disable-next
+simplified = "软件"
+
+# 忽略區塊
+# zhtw:disable
+test_data = [
+    "软件",
+    "硬件",
+    "网络",
+]
+# zhtw:enable
+```
+
+支援各種註解風格：`#`、`//`、`/* */`、`<!-- -->`
+
+## CI/CD 整合
+
+### GitHub Actions
+
+```yaml
+- name: Check Traditional Chinese
+  run: |
+    pip install zhtw
+    zhtw check ./src --json > result.json
+    if [ $? -ne 0 ]; then
+      echo "發現簡體中文用語，請修正"
+      exit 1
+    fi
+```
+
+### Jenkins
+
+```groovy
+stage('繁體中文檢查') {
+    steps {
+        sh 'pip install zhtw'
+        sh 'zhtw check . --json > terminology-report.json'
+    }
+}
+```
+
+### JSON 輸出格式
+
+```json
+{
+  "total_issues": 3,
+  "files_with_issues": 2,
+  "files_checked": 150,
+  "files_modified": 0,
+  "files_skipped": 45,
+  "status": "fail",
+  "issues": [
+    {
+      "file": "src/components/Header.tsx",
+      "line": 12,
+      "column": 5,
+      "source": "用户",
+      "target": "使用者"
+    }
+  ]
+}
+```
+
+## 為什麼不用 OpenCC？
+
+OpenCC 會過度轉換一些在台灣已經正確的詞彙：
+
+| 原文 | OpenCC 結果 | 正確（台灣） |
+|------|-------------|--------------|
+| 權限 | 許可權 | 權限 |
+| 設備 | 裝置 | 設備 |
+| 視頻 | 視訊 | 影片 |
+
+ZHTW 使用精確的術語表，只轉換明確定義的詞彙，避免這類問題。
+
+## 開發
+
+```bash
+# 安裝開發依賴
+pip install -e ".[dev]"
+
+# 執行測試
+pytest
+
+# 執行 lint
+ruff check .
+```
+
+## 路線圖
+
+- [x] v1.0 - 基礎 CLI + 詞庫
+- [x] v1.5 - 統計報告 + 詞庫驗證 + 忽略註解
+- [ ] v2.0 - LLM 輔助詞彙探索
+- [ ] v3.0 - 本地模型上下文感知
+
+## License
+
+MIT License
+
+---
+
+**rajatim 出品**