vocabulary-scanner 0.2.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- vocabulary_scanner-0.2.0/LICENSE +9 -0
- vocabulary_scanner-0.2.0/PKG-INFO +240 -0
- vocabulary_scanner-0.2.0/README.md +209 -0
- vocabulary_scanner-0.2.0/data/SOURCES.md +62 -0
- vocabulary_scanner-0.2.0/data/cefrj-vocabulary-profile-1.6.csv +7802 -0
- vocabulary_scanner-0.2.0/data/octanove-vocabulary-profile-c1c2-1.0.csv +2137 -0
- vocabulary_scanner-0.2.0/pyproject.toml +58 -0
- vocabulary_scanner-0.2.0/sample/sample.pdf +47 -0
- vocabulary_scanner-0.2.0/sample/sample_data.xlsx +0 -0
- vocabulary_scanner-0.2.0/sample/sample_doc.docx +0 -0
- vocabulary_scanner-0.2.0/sample/sample_text.txt +12 -0
- vocabulary_scanner-0.2.0/src/vocabulary_scanner/__init__.py +312 -0
- vocabulary_scanner-0.2.0/src/vocabulary_scanner/__main__.py +6 -0
- vocabulary_scanner-0.2.0/src/vocabulary_scanner/buildDictionary.py +238 -0
- vocabulary_scanner-0.2.0/src/vocabulary_scanner/cefrDictionary.py +250 -0
- vocabulary_scanner-0.2.0/src/vocabulary_scanner/chatColor.py +129 -0
- vocabulary_scanner-0.2.0/src/vocabulary_scanner/connectGoogleTranslate.py +38 -0
- vocabulary_scanner-0.2.0/src/vocabulary_scanner/connectMyMemory.py +147 -0
- vocabulary_scanner-0.2.0/src/vocabulary_scanner/connectWordNet.py +100 -0
- vocabulary_scanner-0.2.0/src/vocabulary_scanner/data/THIRD_PARTY_NOTICES.md +50 -0
- vocabulary_scanner-0.2.0/src/vocabulary_scanner/data/cefr_words.csv +10118 -0
- vocabulary_scanner-0.2.0/src/vocabulary_scanner/data/cefr_words_estimated.csv +68146 -0
- vocabulary_scanner-0.2.0/src/vocabulary_scanner/exportVocabularyBook.py +383 -0
- vocabulary_scanner-0.2.0/src/vocabulary_scanner/extractText.py +282 -0
- vocabulary_scanner-0.2.0/src/vocabulary_scanner/scanText.py +220 -0
- vocabulary_scanner-0.2.0/src/vocabulary_scanner/translation.py +240 -0
- vocabulary_scanner-0.2.0/src/vocabulary_scanner/visionOCR.py +132 -0
- vocabulary_scanner-0.2.0/src/vocabulary_scanner/visionOCR.swift +39 -0
- vocabulary_scanner-0.2.0/tests/conftest.py +49 -0
- vocabulary_scanner-0.2.0/tests/test_buildDictionary.py +86 -0
- vocabulary_scanner-0.2.0/tests/test_cefrDictionary.py +98 -0
- vocabulary_scanner-0.2.0/tests/test_chatColor.py +27 -0
- vocabulary_scanner-0.2.0/tests/test_cli.py +117 -0
- vocabulary_scanner-0.2.0/tests/test_connectMyMemory.py +121 -0
- vocabulary_scanner-0.2.0/tests/test_exportVocabularyBook.py +127 -0
- vocabulary_scanner-0.2.0/tests/test_extractText.py +55 -0
- vocabulary_scanner-0.2.0/tests/test_scanText.py +92 -0
- vocabulary_scanner-0.2.0/tests/test_translation.py +169 -0
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 ShingWong08
|
|
4
|
+
|
|
5
|
+
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:
|
|
6
|
+
|
|
7
|
+
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
|
|
8
|
+
|
|
9
|
+
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.
|
|
@@ -0,0 +1,240 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: vocabulary_scanner
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: Scan English documents, find the CEFR level (A1-C2) of every word, and export a vocabulary book.
|
|
5
|
+
Keywords: cefr,vocabulary,english-learning,education,cli
|
|
6
|
+
Author: AndyTLY
|
|
7
|
+
Author-email: Shing8981 <shingwong088@gmail.com>
|
|
8
|
+
Requires-Python: >=3.10
|
|
9
|
+
Description-Content-Type: text/markdown
|
|
10
|
+
Classifier: Development Status :: 3 - Alpha
|
|
11
|
+
Classifier: Environment :: Console
|
|
12
|
+
Classifier: Intended Audience :: Education
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Topic :: Education
|
|
15
|
+
License-File: LICENSE
|
|
16
|
+
Requires-Dist: openpyxl>=3.1
|
|
17
|
+
Requires-Dist: pdfplumber>=0.10
|
|
18
|
+
Requires-Dist: pypdf>=4.0
|
|
19
|
+
Requires-Dist: python-docx>=1.1
|
|
20
|
+
Requires-Dist: nltk>=3.8
|
|
21
|
+
Requires-Dist: pytest ; extra == "dev"
|
|
22
|
+
Requires-Dist: pypdfium2>=4.30 ; extra == "ocr"
|
|
23
|
+
Requires-Dist: pillow ; extra == "ocr"
|
|
24
|
+
Requires-Dist: deep-translator>=1.11 ; extra == "translate"
|
|
25
|
+
Requires-Dist: requests ; extra == "translate"
|
|
26
|
+
Provides-Extra: dev
|
|
27
|
+
Provides-Extra: ocr
|
|
28
|
+
Provides-Extra: translate
|
|
29
|
+
Import-Name: vocabulary_scanner
|
|
30
|
+
|
|
31
|
+
# 英文文件 CEFR 單詞等級掃描工具
|
|
32
|
+
|
|
33
|
+
**中文** | [English](README.en.md)
|
|
34
|
+
|
|
35
|
+
掃描 PDF、Word、Excel、圖片、純文字等檔案,分析每個英文單詞的 CEFR 等級(A1–C2),
|
|
36
|
+
並自動把 **B2 到 C2** 的高級單詞/片語整理成單詞簿,附英文定義與出處例句。
|
|
37
|
+
|
|
38
|
+
## 功能
|
|
39
|
+
|
|
40
|
+
- 支援 PDF(.pdf)、Word(.docx)、Excel(.xlsx)、圖片(.png/.jpg/.tiff)與純文字(.txt/.csv/.md/.html)
|
|
41
|
+
- 支援單一檔案或多個檔案/整個資料夾(遞迴掃描)
|
|
42
|
+
- 掃描圖片 PDF:自動偵測「沒有文字層」的 PDF,改用 Apple Vision OCR 認字(僅 macOS)
|
|
43
|
+
- 內建 CEFR 字典(A1–C2,約 1 萬筆人工標注詞條:CEFR-J 1.6 + Octanove),
|
|
44
|
+
另有約 6.8 萬個單詞的推算等級(Maximax67),補足字典沒收錄的字;來源見 `data/SOURCES.md`
|
|
45
|
+
- 詞形還原(run/runs/ran → run)與英文定義(WordNet,可離線)
|
|
46
|
+
- 可選翻譯:把單詞翻譯成指定語言(繁中、簡中、日、韓、西、法等),只翻單詞本身
|
|
47
|
+
- 匯出多種格式,方便匯入字典或背單詞 App
|
|
48
|
+
|
|
49
|
+
## 專案結構
|
|
50
|
+
|
|
51
|
+
```
|
|
52
|
+
vocabulary_scanner/
|
|
53
|
+
├── pyproject.toml 套件設定與相依套件
|
|
54
|
+
├── src/vocabulary_scanner/
|
|
55
|
+
│ ├── __init__.py 命令列主程式 main()
|
|
56
|
+
│ ├── __main__.py 讓 python -m vocabulary_scanner 可以執行
|
|
57
|
+
│ ├── chatColor.py 終端機彩色輸出
|
|
58
|
+
│ ├── cefrDictionary.py CEFR 字典與等級查詢
|
|
59
|
+
│ ├── connectWordNet.py WordNet 詞形還原與英文定義
|
|
60
|
+
│ ├── translation.py 翻譯:快取、語言名稱、自動切換翻譯服務
|
|
61
|
+
│ ├── connectGoogleTranslate.py Google 翻譯
|
|
62
|
+
│ ├── connectMyMemory.py MyMemory 翻譯(Google 被擋時的備援)
|
|
63
|
+
│ ├── extractText.py 讀取 PDF / Word / Excel / HTML / 文字檔
|
|
64
|
+
│ ├── visionOCR.py Apple Vision OCR(macOS)
|
|
65
|
+
│ ├── visionOCR.swift OCR 輔助程式原始碼
|
|
66
|
+
│ ├── scanText.py 斷句、比對單詞與片語
|
|
67
|
+
│ ├── exportVocabularyBook.py 匯出 Excel / CSV / Anki / 欧路 / JSON / 報告
|
|
68
|
+
│ ├── buildDictionary.py 由原始詞表重建字典
|
|
69
|
+
│ └── data/
|
|
70
|
+
│ ├── cefr_words.csv CEFR 主字典(CEFR-J + Octanove)
|
|
71
|
+
│ ├── cefr_words_estimated.csv 推算等級字典(Maximax67)
|
|
72
|
+
│ └── THIRD_PARTY_NOTICES.md 字典資料的來源與授權聲明
|
|
73
|
+
├── data/ 原始詞表(CEFR-J 1.6、Octanove)與資料來源說明
|
|
74
|
+
├── sample/ 範例檔案
|
|
75
|
+
└── tests/ pytest 測試
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
## 安裝
|
|
79
|
+
|
|
80
|
+
需要 Python 3.10 以上。在專案資料夾執行:
|
|
81
|
+
|
|
82
|
+
**Windows(PowerShell)**
|
|
83
|
+
|
|
84
|
+
```powershell
|
|
85
|
+
python -m venv env
|
|
86
|
+
.\env\Scripts\Activate.ps1
|
|
87
|
+
python -m pip install -e ".[translate]"
|
|
88
|
+
python -m nltk.downloader wordnet omw-1.4
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
**macOS / Linux**
|
|
92
|
+
|
|
93
|
+
```bash
|
|
94
|
+
python3 -m venv env
|
|
95
|
+
source env/bin/activate
|
|
96
|
+
python3 -m pip install -e ".[translate,ocr]"
|
|
97
|
+
python3 -m nltk.downloader wordnet omw-1.4
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
- `[translate]`:翻譯功能(`deep-translator`),不需要可省略。
|
|
101
|
+
- `[ocr]`:圖片 PDF 的 OCR,只在 macOS 有效。
|
|
102
|
+
- `[dev]`:開發用的 `pytest`。
|
|
103
|
+
- 專案根目錄的 `requirements.txt` 列出同樣的相依套件(核心+翻譯+macOS 的 OCR),
|
|
104
|
+
也可以用 `python -m pip install -r requirements.txt` 安裝;但要使用 `vocab-scanner` 指令,仍需執行上面的 `pip install -e .`。
|
|
105
|
+
- 最後一行下載 WordNet(只需一次),用於英文定義與詞形還原。沒下載的話,程式第一次執行時也會自動嘗試下載。
|
|
106
|
+
|
|
107
|
+
> 若無法安裝 nltk 或下載 WordNet,程式仍可執行,只是會跳過「詞形還原」與「英文定義」,
|
|
108
|
+
> 改用單詞原形比對(CEFR-J 字典本身已含大量屈折形式,仍有相當涵蓋率)。
|
|
109
|
+
|
|
110
|
+
之後每次開新的終端機,先啟用虛擬環境(Windows:`.\env\Scripts\Activate.ps1`;macOS:`source env/bin/activate`)。
|
|
111
|
+
|
|
112
|
+
### OCR(macOS,選用)
|
|
113
|
+
|
|
114
|
+
OCR 使用 Apple 內建的 Vision 框架,不需要另外安裝 Tesseract。啟用條件:
|
|
115
|
+
|
|
116
|
+
- macOS 需有 **Xcode 命令列工具**(`swiftc` 可用)。終端機執行 `xcode-select --install` 即可安裝。
|
|
117
|
+
- 首次用到 OCR 時,程式會自動把 `visionOCR.swift` 編譯到 `~/.cache/vocabulary_scanner/`。
|
|
118
|
+
|
|
119
|
+
OCR 只在「PDF 沒有文字層」時才會觸發(`--ocr auto`,預設);原生文字 PDF 完全不經過 OCR,速度不受影響。
|
|
120
|
+
**Windows 不支援 OCR**:圖片檔與掃描圖片 PDF 會被略過,其他格式不受影響。
|
|
121
|
+
|
|
122
|
+
### 翻譯(選用)
|
|
123
|
+
|
|
124
|
+
翻譯需要網路連線,預設(`--translator auto`)先用 Google 翻譯(`deep-translator`);
|
|
125
|
+
Google 不回應時(例如回報 `TooManyRequests`),自動改用 [MyMemory](https://mymemory.translated.net/)。
|
|
126
|
+
翻譯結果會快取在目前資料夾的 `translation_cache/`,之後同樣的單詞離線也能用。
|
|
127
|
+
翻譯失敗的單詞不會中斷掃描,下次執行時會自動重試。
|
|
128
|
+
|
|
129
|
+
- Google 偶爾會把短時間內大量請求的電腦判定為「異常流量」並暫時封鎖(通常幾小時到一天後恢復)。
|
|
130
|
+
- MyMemory 免費、不需帳號,但每天約有 5,000 字元的免費額度(約數百個單詞),用完會在隔天恢復。
|
|
131
|
+
- 想指定翻譯服務:`--translator google` 或 `--translator mymemory`。
|
|
132
|
+
|
|
133
|
+
## 使用
|
|
134
|
+
|
|
135
|
+
安裝後會有 `vocab-scanner` 指令(也可以用 `python -m vocabulary_scanner`,效果相同)。
|
|
136
|
+
|
|
137
|
+
### 最省事的方法:完全不用手打路徑
|
|
138
|
+
|
|
139
|
+
路徑有空白時(例如 `Group 6_TAM ... Final Version.docx`)必須加引號,手動輸入很容易少一個引號就報錯。
|
|
140
|
+
最簡單的做法是讓終端機自己幫你貼:
|
|
141
|
+
|
|
142
|
+
1. 先輸入 `vocab-scanner`,**結尾留一個空格**
|
|
143
|
+
2. 從檔案總管(Windows)或 Finder(macOS)把檔案或整個資料夾拖進終端機視窗 → 路徑會自動貼上
|
|
144
|
+
3. 按 Enter
|
|
145
|
+
|
|
146
|
+
> 所有參數都是選填的。結果預設寫到目前資料夾的 `output/`;加 `--out-dir` 可以換一個輸出資料夾,
|
|
147
|
+
> 避免覆蓋上一次的結果,例如 `--out-dir output/essay`。
|
|
148
|
+
|
|
149
|
+
### 完整指令範例
|
|
150
|
+
|
|
151
|
+
```bash
|
|
152
|
+
# 掃描整個資料夾
|
|
153
|
+
vocab-scanner sample/
|
|
154
|
+
|
|
155
|
+
# 掃描多個檔案
|
|
156
|
+
vocab-scanner report.pdf notes.docx data.xlsx
|
|
157
|
+
|
|
158
|
+
# 合併進既有單詞簿(累加次數、保留來源)
|
|
159
|
+
vocab-scanner new_docs/ --merge output/vocabulary_book.csv
|
|
160
|
+
|
|
161
|
+
# 只查詢某個單詞的等級
|
|
162
|
+
vocab-scanner --lookup ambiguous
|
|
163
|
+
|
|
164
|
+
# 掃描並把單詞翻譯成繁體中文(只翻單詞,不翻定義)
|
|
165
|
+
vocab-scanner sample/ --translate zh-TW
|
|
166
|
+
|
|
167
|
+
# 支援語言名稱或代碼,例如:zh-CN(簡中)、ja(日)、ko(韓)、es(西)、fr(法)
|
|
168
|
+
vocab-scanner sample/ --translate 日文
|
|
169
|
+
|
|
170
|
+
# 強制所有 PDF 都用 OCR(macOS,通常不需要)
|
|
171
|
+
vocab-scanner scans/ --ocr force
|
|
172
|
+
|
|
173
|
+
# 完全關閉 OCR
|
|
174
|
+
vocab-scanner scans/ --ocr off
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
## 參數
|
|
178
|
+
|
|
179
|
+
| 參數 | 說明 | 預設 |
|
|
180
|
+
|------|------|------|
|
|
181
|
+
| `inputs` | 檔案或資料夾(可多個) | 無 |
|
|
182
|
+
| `--out-dir` | 輸出資料夾 | `output` |
|
|
183
|
+
| `--min-level` | 單詞簿最低等級 | `B2` |
|
|
184
|
+
| `--max-level` | 單詞簿最高等級 | `C2` |
|
|
185
|
+
| `--merge` | 合併進既有 `vocabulary_book.csv` | 無 |
|
|
186
|
+
| `--sort` | 排序方式:`level`=先依等級(A1→A2→B1→B2→C1→C2),同等級再依字母;`count`=依出現次數 | `level` |
|
|
187
|
+
| `--top` | 報告中列出的未知單詞數量 | `30` |
|
|
188
|
+
| `--no-definitions` | 不加入 WordNet 英文定義(詞形還原仍會使用) | 無 |
|
|
189
|
+
| `--no-estimated` | 只用 CEFR-J / Octanove 的人工等級,不使用推算等級 | 無 |
|
|
190
|
+
| `--lookup` | 查詢單詞等級後離開 | 無 |
|
|
191
|
+
| `--ocr` | OCR 模式:`auto`=沒有文字層才 OCR、`force`=PDF 一律 OCR、`off`=關閉 | `auto` |
|
|
192
|
+
| `--ocr-dpi` | OCR 時 PDF 渲染解析度 | `200` |
|
|
193
|
+
| `--translate` | 把單詞翻譯成指定語言(`zh-TW`、`zh-CN`、`ja`、`ko`、`es`、`fr`…;只翻單詞) | 無 |
|
|
194
|
+
| `--translator` | 翻譯服務:`auto`=先 Google,不回應時改用 MyMemory;`google`;`mymemory` | `auto` |
|
|
195
|
+
| `--translation-cache` | 翻譯快取資料夾 | `translation_cache` |
|
|
196
|
+
| `--dictionary` | 改用其他 CEFR 字典 CSV | 內建字典 |
|
|
197
|
+
|
|
198
|
+
## 輸出(預設在 `output/`)
|
|
199
|
+
|
|
200
|
+
| 檔案 | 用途 |
|
|
201
|
+
|------|------|
|
|
202
|
+
| `vocabulary_book.xlsx` | Excel 單詞簿(含「翻譯」欄與「等級統計」分頁) |
|
|
203
|
+
| `vocabulary_book.csv` | CSV 單詞簿,可作為 `--merge` 的合併檔 |
|
|
204
|
+
| `vocabulary_anki.tsv` | Anki 匯入檔(單詞/定義/例句/等級/詞性/翻譯) |
|
|
205
|
+
| `vocabulary_eudic.txt` | 欧路词典、有道等生詞本匯入檔(每行一詞) |
|
|
206
|
+
| `vocabulary_book.json` | JSON 格式 |
|
|
207
|
+
| `analysis_report.txt` | 完整分析報告(各等級分布 + 單詞簿 + 常見未知單詞) |
|
|
208
|
+
|
|
209
|
+
## 匯入字典/背單詞 App
|
|
210
|
+
|
|
211
|
+
- **Anki**:檔案 → 匯入 → 選擇 `vocabulary_anki.tsv`,分隔符選「Tab」,
|
|
212
|
+
欄位對應「單詞、定義、例句、等級、詞性、翻譯」。
|
|
213
|
+
- **欧路词典(Eudic)**:學習 → 生詞本 → 匯入 → 選 `vocabulary_eudic.txt`(每行一個單詞)。
|
|
214
|
+
- **有道/其他**:多數 App 支援匯入每行一個單詞的 `.txt`,用 `vocabulary_eudic.txt` 即可。
|
|
215
|
+
|
|
216
|
+
## 等級判定規則
|
|
217
|
+
|
|
218
|
+
- 單詞先以小寫、去重音、原形比對;比不到時用 WordNet 做詞形還原後再比對。
|
|
219
|
+
- 一個單詞若同時出現在多個等級,以「較低」等級為主(CEFR 慣例),並在 `all_levels` 保留全部等級。
|
|
220
|
+
- 片語(如 `climate change`)會以 2–4 字連詞比對,與單詞分開列在單詞簿中。
|
|
221
|
+
- 主字典查不到的單詞,改用推算字典(Maximax67)。這些單詞在 Excel 的「推算等級」欄標為「推算」,
|
|
222
|
+
在 Anki 檔與報告中等級後面加 `*`(例如 `C2*`),等級僅供參考。加 `--no-estimated` 可關閉。
|
|
223
|
+
- 網址、DOI、電子郵件會在掃描前移除,不會被當成單詞。
|
|
224
|
+
|
|
225
|
+
## 開發
|
|
226
|
+
|
|
227
|
+
```bash
|
|
228
|
+
python -m pip install -e ".[dev]"
|
|
229
|
+
python -m pytest
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
重建 CEFR 字典:`python -m vocabulary_scanner.buildDictionary`(詳見 `data/SOURCES.md`)。
|
|
233
|
+
|
|
234
|
+
## 注意事項
|
|
235
|
+
|
|
236
|
+
- 舊版 Word `.doc` 與 Excel `.xls` 不直接支援,請先用 Word/Excel 另存成 `.docx`/`.xlsx`。
|
|
237
|
+
- 掃描圖片 PDF 會自動用 OCR(macOS);解析度越高(`--ocr-dpi`)越準但越慢,頁數多時請耐心等待。
|
|
238
|
+
- 翻譯需連上網路;首次翻譯一批新單詞會較慢,之後走快取(`translation_cache/`)就快了。
|
|
239
|
+
- CEFR 等級為「近似」參考,同一個字在不同語境、不同詞性下等級可能不同。
|
|
240
|
+
|
|
@@ -0,0 +1,209 @@
|
|
|
1
|
+
# 英文文件 CEFR 單詞等級掃描工具
|
|
2
|
+
|
|
3
|
+
**中文** | [English](README.en.md)
|
|
4
|
+
|
|
5
|
+
掃描 PDF、Word、Excel、圖片、純文字等檔案,分析每個英文單詞的 CEFR 等級(A1–C2),
|
|
6
|
+
並自動把 **B2 到 C2** 的高級單詞/片語整理成單詞簿,附英文定義與出處例句。
|
|
7
|
+
|
|
8
|
+
## 功能
|
|
9
|
+
|
|
10
|
+
- 支援 PDF(.pdf)、Word(.docx)、Excel(.xlsx)、圖片(.png/.jpg/.tiff)與純文字(.txt/.csv/.md/.html)
|
|
11
|
+
- 支援單一檔案或多個檔案/整個資料夾(遞迴掃描)
|
|
12
|
+
- 掃描圖片 PDF:自動偵測「沒有文字層」的 PDF,改用 Apple Vision OCR 認字(僅 macOS)
|
|
13
|
+
- 內建 CEFR 字典(A1–C2,約 1 萬筆人工標注詞條:CEFR-J 1.6 + Octanove),
|
|
14
|
+
另有約 6.8 萬個單詞的推算等級(Maximax67),補足字典沒收錄的字;來源見 `data/SOURCES.md`
|
|
15
|
+
- 詞形還原(run/runs/ran → run)與英文定義(WordNet,可離線)
|
|
16
|
+
- 可選翻譯:把單詞翻譯成指定語言(繁中、簡中、日、韓、西、法等),只翻單詞本身
|
|
17
|
+
- 匯出多種格式,方便匯入字典或背單詞 App
|
|
18
|
+
|
|
19
|
+
## 專案結構
|
|
20
|
+
|
|
21
|
+
```
|
|
22
|
+
vocabulary_scanner/
|
|
23
|
+
├── pyproject.toml 套件設定與相依套件
|
|
24
|
+
├── src/vocabulary_scanner/
|
|
25
|
+
│ ├── __init__.py 命令列主程式 main()
|
|
26
|
+
│ ├── __main__.py 讓 python -m vocabulary_scanner 可以執行
|
|
27
|
+
│ ├── chatColor.py 終端機彩色輸出
|
|
28
|
+
│ ├── cefrDictionary.py CEFR 字典與等級查詢
|
|
29
|
+
│ ├── connectWordNet.py WordNet 詞形還原與英文定義
|
|
30
|
+
│ ├── translation.py 翻譯:快取、語言名稱、自動切換翻譯服務
|
|
31
|
+
│ ├── connectGoogleTranslate.py Google 翻譯
|
|
32
|
+
│ ├── connectMyMemory.py MyMemory 翻譯(Google 被擋時的備援)
|
|
33
|
+
│ ├── extractText.py 讀取 PDF / Word / Excel / HTML / 文字檔
|
|
34
|
+
│ ├── visionOCR.py Apple Vision OCR(macOS)
|
|
35
|
+
│ ├── visionOCR.swift OCR 輔助程式原始碼
|
|
36
|
+
│ ├── scanText.py 斷句、比對單詞與片語
|
|
37
|
+
│ ├── exportVocabularyBook.py 匯出 Excel / CSV / Anki / 欧路 / JSON / 報告
|
|
38
|
+
│ ├── buildDictionary.py 由原始詞表重建字典
|
|
39
|
+
│ └── data/
|
|
40
|
+
│ ├── cefr_words.csv CEFR 主字典(CEFR-J + Octanove)
|
|
41
|
+
│ ├── cefr_words_estimated.csv 推算等級字典(Maximax67)
|
|
42
|
+
│ └── THIRD_PARTY_NOTICES.md 字典資料的來源與授權聲明
|
|
43
|
+
├── data/ 原始詞表(CEFR-J 1.6、Octanove)與資料來源說明
|
|
44
|
+
├── sample/ 範例檔案
|
|
45
|
+
└── tests/ pytest 測試
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
## 安裝
|
|
49
|
+
|
|
50
|
+
需要 Python 3.10 以上。在專案資料夾執行:
|
|
51
|
+
|
|
52
|
+
**Windows(PowerShell)**
|
|
53
|
+
|
|
54
|
+
```powershell
|
|
55
|
+
python -m venv env
|
|
56
|
+
.\env\Scripts\Activate.ps1
|
|
57
|
+
python -m pip install -e ".[translate]"
|
|
58
|
+
python -m nltk.downloader wordnet omw-1.4
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
**macOS / Linux**
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
python3 -m venv env
|
|
65
|
+
source env/bin/activate
|
|
66
|
+
python3 -m pip install -e ".[translate,ocr]"
|
|
67
|
+
python3 -m nltk.downloader wordnet omw-1.4
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
- `[translate]`:翻譯功能(`deep-translator`),不需要可省略。
|
|
71
|
+
- `[ocr]`:圖片 PDF 的 OCR,只在 macOS 有效。
|
|
72
|
+
- `[dev]`:開發用的 `pytest`。
|
|
73
|
+
- 專案根目錄的 `requirements.txt` 列出同樣的相依套件(核心+翻譯+macOS 的 OCR),
|
|
74
|
+
也可以用 `python -m pip install -r requirements.txt` 安裝;但要使用 `vocab-scanner` 指令,仍需執行上面的 `pip install -e .`。
|
|
75
|
+
- 最後一行下載 WordNet(只需一次),用於英文定義與詞形還原。沒下載的話,程式第一次執行時也會自動嘗試下載。
|
|
76
|
+
|
|
77
|
+
> 若無法安裝 nltk 或下載 WordNet,程式仍可執行,只是會跳過「詞形還原」與「英文定義」,
|
|
78
|
+
> 改用單詞原形比對(CEFR-J 字典本身已含大量屈折形式,仍有相當涵蓋率)。
|
|
79
|
+
|
|
80
|
+
之後每次開新的終端機,先啟用虛擬環境(Windows:`.\env\Scripts\Activate.ps1`;macOS:`source env/bin/activate`)。
|
|
81
|
+
|
|
82
|
+
### OCR(macOS,選用)
|
|
83
|
+
|
|
84
|
+
OCR 使用 Apple 內建的 Vision 框架,不需要另外安裝 Tesseract。啟用條件:
|
|
85
|
+
|
|
86
|
+
- macOS 需有 **Xcode 命令列工具**(`swiftc` 可用)。終端機執行 `xcode-select --install` 即可安裝。
|
|
87
|
+
- 首次用到 OCR 時,程式會自動把 `visionOCR.swift` 編譯到 `~/.cache/vocabulary_scanner/`。
|
|
88
|
+
|
|
89
|
+
OCR 只在「PDF 沒有文字層」時才會觸發(`--ocr auto`,預設);原生文字 PDF 完全不經過 OCR,速度不受影響。
|
|
90
|
+
**Windows 不支援 OCR**:圖片檔與掃描圖片 PDF 會被略過,其他格式不受影響。
|
|
91
|
+
|
|
92
|
+
### 翻譯(選用)
|
|
93
|
+
|
|
94
|
+
翻譯需要網路連線,預設(`--translator auto`)先用 Google 翻譯(`deep-translator`);
|
|
95
|
+
Google 不回應時(例如回報 `TooManyRequests`),自動改用 [MyMemory](https://mymemory.translated.net/)。
|
|
96
|
+
翻譯結果會快取在目前資料夾的 `translation_cache/`,之後同樣的單詞離線也能用。
|
|
97
|
+
翻譯失敗的單詞不會中斷掃描,下次執行時會自動重試。
|
|
98
|
+
|
|
99
|
+
- Google 偶爾會把短時間內大量請求的電腦判定為「異常流量」並暫時封鎖(通常幾小時到一天後恢復)。
|
|
100
|
+
- MyMemory 免費、不需帳號,但每天約有 5,000 字元的免費額度(約數百個單詞),用完會在隔天恢復。
|
|
101
|
+
- 想指定翻譯服務:`--translator google` 或 `--translator mymemory`。
|
|
102
|
+
|
|
103
|
+
## 使用
|
|
104
|
+
|
|
105
|
+
安裝後會有 `vocab-scanner` 指令(也可以用 `python -m vocabulary_scanner`,效果相同)。
|
|
106
|
+
|
|
107
|
+
### 最省事的方法:完全不用手打路徑
|
|
108
|
+
|
|
109
|
+
路徑有空白時(例如 `Group 6_TAM ... Final Version.docx`)必須加引號,手動輸入很容易少一個引號就報錯。
|
|
110
|
+
最簡單的做法是讓終端機自己幫你貼:
|
|
111
|
+
|
|
112
|
+
1. 先輸入 `vocab-scanner`,**結尾留一個空格**
|
|
113
|
+
2. 從檔案總管(Windows)或 Finder(macOS)把檔案或整個資料夾拖進終端機視窗 → 路徑會自動貼上
|
|
114
|
+
3. 按 Enter
|
|
115
|
+
|
|
116
|
+
> 所有參數都是選填的。結果預設寫到目前資料夾的 `output/`;加 `--out-dir` 可以換一個輸出資料夾,
|
|
117
|
+
> 避免覆蓋上一次的結果,例如 `--out-dir output/essay`。
|
|
118
|
+
|
|
119
|
+
### 完整指令範例
|
|
120
|
+
|
|
121
|
+
```bash
|
|
122
|
+
# 掃描整個資料夾
|
|
123
|
+
vocab-scanner sample/
|
|
124
|
+
|
|
125
|
+
# 掃描多個檔案
|
|
126
|
+
vocab-scanner report.pdf notes.docx data.xlsx
|
|
127
|
+
|
|
128
|
+
# 合併進既有單詞簿(累加次數、保留來源)
|
|
129
|
+
vocab-scanner new_docs/ --merge output/vocabulary_book.csv
|
|
130
|
+
|
|
131
|
+
# 只查詢某個單詞的等級
|
|
132
|
+
vocab-scanner --lookup ambiguous
|
|
133
|
+
|
|
134
|
+
# 掃描並把單詞翻譯成繁體中文(只翻單詞,不翻定義)
|
|
135
|
+
vocab-scanner sample/ --translate zh-TW
|
|
136
|
+
|
|
137
|
+
# 支援語言名稱或代碼,例如:zh-CN(簡中)、ja(日)、ko(韓)、es(西)、fr(法)
|
|
138
|
+
vocab-scanner sample/ --translate 日文
|
|
139
|
+
|
|
140
|
+
# 強制所有 PDF 都用 OCR(macOS,通常不需要)
|
|
141
|
+
vocab-scanner scans/ --ocr force
|
|
142
|
+
|
|
143
|
+
# 完全關閉 OCR
|
|
144
|
+
vocab-scanner scans/ --ocr off
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
## 參數
|
|
148
|
+
|
|
149
|
+
| 參數 | 說明 | 預設 |
|
|
150
|
+
|------|------|------|
|
|
151
|
+
| `inputs` | 檔案或資料夾(可多個) | 無 |
|
|
152
|
+
| `--out-dir` | 輸出資料夾 | `output` |
|
|
153
|
+
| `--min-level` | 單詞簿最低等級 | `B2` |
|
|
154
|
+
| `--max-level` | 單詞簿最高等級 | `C2` |
|
|
155
|
+
| `--merge` | 合併進既有 `vocabulary_book.csv` | 無 |
|
|
156
|
+
| `--sort` | 排序方式:`level`=先依等級(A1→A2→B1→B2→C1→C2),同等級再依字母;`count`=依出現次數 | `level` |
|
|
157
|
+
| `--top` | 報告中列出的未知單詞數量 | `30` |
|
|
158
|
+
| `--no-definitions` | 不加入 WordNet 英文定義(詞形還原仍會使用) | 無 |
|
|
159
|
+
| `--no-estimated` | 只用 CEFR-J / Octanove 的人工等級,不使用推算等級 | 無 |
|
|
160
|
+
| `--lookup` | 查詢單詞等級後離開 | 無 |
|
|
161
|
+
| `--ocr` | OCR 模式:`auto`=沒有文字層才 OCR、`force`=PDF 一律 OCR、`off`=關閉 | `auto` |
|
|
162
|
+
| `--ocr-dpi` | OCR 時 PDF 渲染解析度 | `200` |
|
|
163
|
+
| `--translate` | 把單詞翻譯成指定語言(`zh-TW`、`zh-CN`、`ja`、`ko`、`es`、`fr`…;只翻單詞) | 無 |
|
|
164
|
+
| `--translator` | 翻譯服務:`auto`=先 Google,不回應時改用 MyMemory;`google`;`mymemory` | `auto` |
|
|
165
|
+
| `--translation-cache` | 翻譯快取資料夾 | `translation_cache` |
|
|
166
|
+
| `--dictionary` | 改用其他 CEFR 字典 CSV | 內建字典 |
|
|
167
|
+
|
|
168
|
+
## 輸出(預設在 `output/`)
|
|
169
|
+
|
|
170
|
+
| 檔案 | 用途 |
|
|
171
|
+
|------|------|
|
|
172
|
+
| `vocabulary_book.xlsx` | Excel 單詞簿(含「翻譯」欄與「等級統計」分頁) |
|
|
173
|
+
| `vocabulary_book.csv` | CSV 單詞簿,可作為 `--merge` 的合併檔 |
|
|
174
|
+
| `vocabulary_anki.tsv` | Anki 匯入檔(單詞/定義/例句/等級/詞性/翻譯) |
|
|
175
|
+
| `vocabulary_eudic.txt` | 欧路词典、有道等生詞本匯入檔(每行一詞) |
|
|
176
|
+
| `vocabulary_book.json` | JSON 格式 |
|
|
177
|
+
| `analysis_report.txt` | 完整分析報告(各等級分布 + 單詞簿 + 常見未知單詞) |
|
|
178
|
+
|
|
179
|
+
## 匯入字典/背單詞 App
|
|
180
|
+
|
|
181
|
+
- **Anki**:檔案 → 匯入 → 選擇 `vocabulary_anki.tsv`,分隔符選「Tab」,
|
|
182
|
+
欄位對應「單詞、定義、例句、等級、詞性、翻譯」。
|
|
183
|
+
- **欧路词典(Eudic)**:學習 → 生詞本 → 匯入 → 選 `vocabulary_eudic.txt`(每行一個單詞)。
|
|
184
|
+
- **有道/其他**:多數 App 支援匯入每行一個單詞的 `.txt`,用 `vocabulary_eudic.txt` 即可。
|
|
185
|
+
|
|
186
|
+
## 等級判定規則
|
|
187
|
+
|
|
188
|
+
- 單詞先以小寫、去重音、原形比對;比不到時用 WordNet 做詞形還原後再比對。
|
|
189
|
+
- 一個單詞若同時出現在多個等級,以「較低」等級為主(CEFR 慣例),並在 `all_levels` 保留全部等級。
|
|
190
|
+
- 片語(如 `climate change`)會以 2–4 字連詞比對,與單詞分開列在單詞簿中。
|
|
191
|
+
- 主字典查不到的單詞,改用推算字典(Maximax67)。這些單詞在 Excel 的「推算等級」欄標為「推算」,
|
|
192
|
+
在 Anki 檔與報告中等級後面加 `*`(例如 `C2*`),等級僅供參考。加 `--no-estimated` 可關閉。
|
|
193
|
+
- 網址、DOI、電子郵件會在掃描前移除,不會被當成單詞。
|
|
194
|
+
|
|
195
|
+
## 開發
|
|
196
|
+
|
|
197
|
+
```bash
|
|
198
|
+
python -m pip install -e ".[dev]"
|
|
199
|
+
python -m pytest
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
重建 CEFR 字典:`python -m vocabulary_scanner.buildDictionary`(詳見 `data/SOURCES.md`)。
|
|
203
|
+
|
|
204
|
+
## 注意事項
|
|
205
|
+
|
|
206
|
+
- 舊版 Word `.doc` 與 Excel `.xls` 不直接支援,請先用 Word/Excel 另存成 `.docx`/`.xlsx`。
|
|
207
|
+
- 掃描圖片 PDF 會自動用 OCR(macOS);解析度越高(`--ocr-dpi`)越準但越慢,頁數多時請耐心等待。
|
|
208
|
+
- 翻譯需連上網路;首次翻譯一批新單詞會較慢,之後走快取(`translation_cache/`)就快了。
|
|
209
|
+
- CEFR 等級為「近似」參考,同一個字在不同語境、不同詞性下等級可能不同。
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
# CEFR 字典資料來源
|
|
2
|
+
|
|
3
|
+
程式使用兩份字典,都放在 `src/vocabulary_scanner/data/`:
|
|
4
|
+
|
|
5
|
+
| 字典 | 內容 | 來源 |
|
|
6
|
+
|---|---|---|
|
|
7
|
+
| `cefr_words.csv`(主字典) | 約 1 萬筆人工標注等級(A1–C2) | CEFR-J 1.6 + Octanove C1/C2 1.0 |
|
|
8
|
+
| `cefr_words_estimated.csv`(推算字典) | 約 6.8 萬個主字典沒有的單詞,等級為推算值 | Maximax67 Words-CEFR-Dataset |
|
|
9
|
+
|
|
10
|
+
掃描時先查主字典;**只有主字典查不到**時才用推算字典,這些單詞在輸出檔中標為「推算」(Excel)或 `*`(Anki、報告)。
|
|
11
|
+
不想使用推算等級時,掃描加上 `--no-estimated`。
|
|
12
|
+
|
|
13
|
+
## 1. CEFR-J Wordlist (ver 1.6)
|
|
14
|
+
|
|
15
|
+
- 涵蓋 A1、A2、B1、B2
|
|
16
|
+
- Compiled by Yukio Tono, Tokyo University of Foreign Studies (TUFS)
|
|
17
|
+
- 取自 http://www.cefr-j.org/download.html (`CEFRJ_wordlist_ver1.6.zip`,2020-03-24 更新版,下載於 2026-11-18)
|
|
18
|
+
- 原始檔:`data/cefrj-vocabulary-profile-1.6.csv`,由 zip 內試算表的 `ALL` 工作表轉換而成
|
|
19
|
+
(欄位:headword, pos, CEFR, CoreInventory 1, CoreInventory 2, Threshold)。原始 zip 未保留,需要時可從官網重新下載。
|
|
20
|
+
- 與 1.5 版([openlanguageprofiles/olp-en-cefrj](https://github.com/openlanguageprofiles/olp-en-cefrj) 上的版本)的差異:
|
|
21
|
+
補上英式/異體拼法(afterwards、storey、emphasise、tonne 等)並新增 being、having。
|
|
22
|
+
- 授權:可免費使用於研究與商業用途,惟須適當引用;版權屬東京外國語大學 Tono Laboratory。
|
|
23
|
+
|
|
24
|
+
## 2. Octanove Vocabulary Profile C1/C2 (ver 1.0)
|
|
25
|
+
|
|
26
|
+
- 涵蓋 C1、C2,由 Octanove Labs 製作,取自 [openlanguageprofiles/olp-en-cefrj](https://github.com/openlanguageprofiles/olp-en-cefrj)(截至 2026-11-18 仍為最新版)
|
|
27
|
+
- 原始檔:`data/octanove-vocabulary-profile-c1c2-1.0.csv`
|
|
28
|
+
- 授權:Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0)
|
|
29
|
+
|
|
30
|
+
## 3. Maximax67 Words-CEFR-Dataset(推算等級)
|
|
31
|
+
|
|
32
|
+
- 取自 [Maximax67/Words-CEFR-Dataset](https://github.com/Maximax67/Words-CEFR-Dataset)(`csv/` 資料夾,下載於 2026-11-18)
|
|
33
|
+
- 原始檔(約 13 MB)未保留在專案中。需要重建推算字典時,把 `words.csv`、`word_pos.csv`、`pos_tags.csv`
|
|
34
|
+
從 https://github.com/Maximax67/Words-CEFR-Dataset/tree/main/csv 下載到 `data/maximax67/`。
|
|
35
|
+
- 等級是以 CEFR-J 為基礎,再依 Google Books 詞頻、詞形與詞幹**推算**出來的(1.0=A1 … 6.0=C2),不是人工標注,準確度較低。
|
|
36
|
+
- 建立推算字典時的處理:
|
|
37
|
+
- 去掉主字典已有的單詞
|
|
38
|
+
- 去掉專有名詞、數字、外來字、符號(詞性標記 NNP、NNPS、CD、FW、LS、POS、SYM)
|
|
39
|
+
- 去掉少於 3 個字母或含數字、符號的字
|
|
40
|
+
- 只保留 WordNet 中當作一般單詞的字(去掉只當人名、地名的字)
|
|
41
|
+
- 同一單詞有多個詞性時取最低等級,四捨五入到最接近的 CEFR 等級
|
|
42
|
+
- 授權:MIT License,Copyright (c) 2024 Belikov Maxim(全文見 `src/vocabulary_scanner/data/THIRD_PARTY_NOTICES.md`,會隨套件一起發佈)
|
|
43
|
+
|
|
44
|
+
## 引用方式(建議)
|
|
45
|
+
|
|
46
|
+
> The CEFR-J Wordlist Version 1.6. Compiled by Yukio Tono, Tokyo University of Foreign Studies.
|
|
47
|
+
> Octanove Vocabulary Profile C1/C2 (ver 1.0), Octanove Labs, CC BY-SA 4.0.
|
|
48
|
+
> Words CEFR Dataset by Belikov Maxim (Maximax67), MIT License.
|
|
49
|
+
|
|
50
|
+
## 重新產生
|
|
51
|
+
|
|
52
|
+
在專案資料夾執行(需要已下載 WordNet):
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
python -m vocabulary_scanner.buildDictionary
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
預設讀取 `data/` 內的 CEFR-J 1.6、Octanove 與 `data/maximax67/`,寫入兩份字典。
|
|
59
|
+
`data/maximax67/` 沒有原始檔時,只重建主字典,保留現有的推算字典;只想重建主字典也可以加 `--no-estimated`。
|
|
60
|
+
|
|
61
|
+
說明:當一個單詞同時出現在多個等級時,程式取「較低」等級作為主要等級
|
|
62
|
+
(符合 CEFR「該詞最早於此等級習得」的慣例),同時在 `all_levels` 保留全部等級。
|