Taiwan Braille Converter

Primary use cases

1. 繁體中文轉台灣點字

• Trigger examples: 「把這句中文翻成台灣點字」「將這段繁中轉成盲文」「請輸出國語點字」
• Expected result: 先判斷讀音，再輸出每字的注音拆解與 braille cells；必要時標示多音字假設。

2. 台灣點字轉回注音或中文

• Trigger examples: 「把這串點字翻回中文」「解析這段盲文」「請先回譯成注音再給中文候選」
• Expected result: 先穩定回復為注音，再提供中文候選；若存在歧義，清楚列出候選與依據。

3. 建立/修正轉換工具或 skill

• Trigger examples: 「幫我做台灣點字轉換器」「建立 braille translation skill」「修正台灣點字 mapping」
• Expected result: 產出正確 skill 結構、規則文件、腳本、測試與打包檔。

Workflow overview

1. 先確認輸入是中文、注音、還是點字。
2. 若輸入是中文，先做詞級或字級讀音決策。
3. 將注音解析為聲母 + 韻母/結合韻 + 聲調。
4. 套用台灣點字對照表產生 braille cells。
5. 若輸入是點字，先反解為注音，再決定是否回譯中文候選。
6. 遇到歧義時，不隱藏不確定性；把假設講清楚。
7. 若是工程任務，優先使用 scripts/ 內的 deterministic 工具完成轉換與驗證。

Success criteria

Quantitative

• Forward conversion deterministic for all entries covered by the rule table.
• Braille to Zhuyin recovery deterministic for all entries covered by the rule table.
• Validation script catches malformed braille cells, invalid tone placement, and unsupported syllables.
• Packaging passes format_check.py and quick_validate.py with no errors.

Qualitative

• 明確區分「規則層確定」與「中文候選有歧義」。
• 所有示例都能逐字拆解。
• 輸出可直接用於教學、測試、或進一步整合進程式。

Instructions

Step 0: Confirm input type

先分類使用者輸入：

• Traditional Chinese：含漢字、標點、數字、夾雜英數。
• Zhuyin：已經提供注音與聲調。
• Braille：已經提供 Unicode braille cells，例如 ⠛⠥⠂。
• Engineering request：要求建立 skill、函式庫、測試、CLI、規則表、資料格式。

若輸入型別不明，先做最小判定：

• 含多數漢字 → 當成中文。
• 含 ㄅㄆㄇㄈ 等符號 → 當成注音。
• 含 Unicode braille pattern → 當成 braille。

Step 1: If the input is Chinese, resolve pronunciation first

中文轉點字時，嚴格遵守：先決定注音，再轉點字。

處理順序：

1. 優先查詞級字典（多字詞優先於單字）。
2. 找不到時退回字級字典。
3. 若仍無法確定：
   • 對常見多音字做語境判斷。
   • 無法穩定判斷時，明示假設讀音。
4. 輕聲不可視為第一聲；要保留輕聲資訊。
5. 第一聲不可省略；每個字都要有聲調。

Step 2: Parse Zhuyin into phonological structure

每個音節要被解析為以下其中之一：

• 聲母 + 韻母 + 聲調
• 聲母 + 結合韻 + 聲調
• 零聲母 + 韻母/結合韻 + 聲調
• 捲舌/空韻字 + 聲調

規則：

• 結合韻必須視為一個單位，不可再拆成兩個獨立韻符號。
• 聲調一律放在該字音節最後。
• 一個中文字音節通常輸出為 2 到 3 個 braille cells。
• 字音不可被拆到兩行中間；若任務涉及排版，整個音節視為不可分割單位。

Step 3: Convert Zhuyin to Taiwan braille

使用 scripts/tw_braille_core.py 的固定規則表。流程如下：

1. 聲母對應到 braille cell。
2. 韻母或結合韻對應到 braille cell。
3. 聲調對應到 braille cell。
4. 將一個音節的 cells 直接串接。
5. 多個字之間預設以空格分開，方便檢查與教學；若使用者要求連續輸出，可改為無空格模式。

Step 4: If the input is braille, back-translate in two phases

反向轉換不可直接宣稱唯一中文答案。必須分兩階段：

1. Braille → Zhuyin
   • 這一步在規則覆蓋範圍內應該是 deterministic。
2. Zhuyin → Chinese candidates
   • 這一步可能有同音歧義。
   • 優先詞級候選，再退回字級候選。
   • 回覆時應清楚標示：
     • 穩定注音
     • 中文候選
     • 哪些位置存在歧義

Step 5: Punctuation, digits, Latin text, and mixed content

這個 skill 的核心腳本優先處理中文音節點字。若任務涉及混排，採用下列原則：

• 中文音節照台灣國語點字規則處理。
• 標點、數字、拉丁字母、單位符號必須明示使用哪一套對照表。
• 若使用者只問中文句子轉點字，且沒有混排，優先使用純中文規則。
• 若有混排而對照表未完全提供，應：
  1. 先完成中文部分。
  2. 明示哪些符號依賴外部表或額外規範。
  3. 不要捏造未定義的點位。

Step 6: Output format

優先使用下列輸出結構：

A. 中文轉點字

1. 原文
2. 注音拆解
3. 每字 braille 拆解
4. 最終 braille 串
5. 若有歧義，附上假設

B. 點字轉中文

1. 原始 braille
2. 回復注音
3. 中文候選
4. 歧義說明

C. 工程任務

1. 交付物清單
2. 檔案結構
3. 核心規則
4. 驗證方式
5. 限制與後續擴充點

Step 7: Deterministic tooling

可直接使用：

• python scripts/tw_braille_cli.py forward --text "人人生而自由"
• python scripts/tw_braille_cli.py reverse --braille "⠛⠥⠂ ⠛⠥⠂ ⠊⠵⠄ ⠱⠂ ⠓⠱⠐ ⠎⠂"
• python scripts/tw_braille_validate.py

Step 8: Finalization and QA

交付前檢查：

1. 轉換前後是否先走過注音層。
2. 是否把結合韻誤拆。
3. 是否每個字都有聲調。
4. 是否在反向翻譯時誠實處理同音歧義。
5. 若是 skill/package，必須跑：

python /home/oai/skills/scripts/format_check.py .
python /home/oai/skills/scripts/quick_validate.py .

Testing plan

Triggering tests

• Should trigger:

  • 「把這句繁中翻成台灣盲文」
  • 「請將這串點字轉回中文」
  • 「幫我建立台灣點字 translation skill」
  • 「解釋國語點字的聲調規則」

• Should NOT trigger:

  • 「把英文翻成英文點字（UEB）」
  • 「說明中國大陸漢語盲文」
  • 「一般 OCR 轉文字」

Functional tests

• Test case: syllable decomposition

  • Given: ㄖㄣˊ
  • When: forward conversion
  • Then: returns ⠛⠥⠂

• Test case: phrase conversion

  • Given: 人人生而自由
  • When: Chinese to braille
  • Then: emits annotated output and final braille string

• Test case: braille reverse

  • Given: ⠛⠥⠂
  • When: reverse conversion
  • Then: returns zhuyin ㄖㄣˊ

• Test case: ambiguity surfacing

  • Given: a braille syllable with multiple Chinese homophone candidates
  • When: braille to Chinese
  • Then: lists candidates instead of asserting a single answer without evidence

Troubleshooting

• Symptom: 中文轉點字結果看似合理，但讀音錯

• Cause: 直接用字形或錯誤字級讀音，沒有先做詞級讀音判斷

• Fix: 先查詞級字典，再退回字級讀音

• Symptom: 點字回中文只有一個答案，但明顯可能有多個同音字

• Cause: 把注音回譯誤當成唯一字形映射

• Fix: 先輸出注音，再列中文候選與歧義

• Symptom: 一個字被拆成過多 braille cells

• Cause: 將結合韻誤拆成兩個韻符號

• Fix: 使用結合韻表優先匹配

Resources

• scripts/tw_braille_core.py: 核心規則與雙向轉換。
• scripts/tw_braille_cli.py: CLI 包裝。
• scripts/tw_braille_validate.py: 自我驗證腳本。
• references/rulebook.md: 規則說明與設計原則。
• references/mapping-tables.md: 聲母、韻母、結合韻、聲調對照。
• references/test-cases.md: 代表性測試案例。
• references/quality_checklist.md: 上線前檢查清單。