A TypeScript library for converting Chinese characters to Wade-Giles romanization
npm install use-wg將中文字轉換為威妥瑪拼音的 TypeScript 函式庫。
- 中文字（繁體及簡體）→ 威妥瑪拼音轉換
- 可設定聲調格式（上標、數字、無）
- 處理中英文混合文字
- URL 安全輸出模式
- 上下文感知的多音字處理
- 完整的 TypeScript 型別定義
- 命令列工具（CLI）
``bash`
npm install use-wg
直接透過 npx 使用：
`bash基本用法
npx use-wg "台灣" # 輸出: t'ai²-wan¹
$3
| 選項 | 簡寫 | 說明 | 預設值 |
| ------------------- | ---- | ----------------------------------- | ----------- |
|
| -u | 輸出 URL 安全格式 | false |
| --tone | -t | 聲調格式: superscript, number, none | superscript |
| --separator | -s | 音節分隔符號 | - |
| --capitalize | -c | 首字母大寫 | false |
| --json | -j | 輸出 JSON 格式 | false |
| --pinyin | -p | 拼音轉威妥瑪模式 | false |程式庫使用方式
$3
`typescript
import { toWadeGiles } from "use-wg";// 基本轉換
toWadeGiles("台灣").text; // "t'ai²-wan¹"
toWadeGiles("台北").text; // "t'ai²-pei³"
toWadeGiles("高雄").text; // "kao¹-hsiung²"
`$3
typescript
// 上標聲調（預設）
toWadeGiles("高雄", { toneFormat: "superscript" }).text; // "kao¹-hsiung²"// 數字聲調
toWadeGiles("高雄", { toneFormat: "number" }).text; // "kao1-hsiung2"
// 無聲調
toWadeGiles("高雄", { toneFormat: "none" }).text; // "kao-hsiung"
`$3
產生僅包含 ASCII 字元的輸出，適用於網址、檔案名稱和識別碼：
typescript
toWadeGiles("台灣", { urlSafe: true }).text; // "tai-wan"
toWadeGiles("氣功", { urlSafe: true }).text; // "chi-kung"
`URL 安全模式會自動：
- 移除聲調標記
- 將
轉換為 u
- 移除撇號（）
- 輸出小寫
- 將空格轉換為連字號（-）$3
轉換器能智慧處理混合文字：
`typescript
toWadeGiles("Hello 世界!").text; // "Hello shih⁴-chieh⁴!"
toWadeGiles("iPhone 手機 Pro").text; // "iPhone shou³-chi¹ Pro"
toWadeGiles("2024年").text; // "2024nien²"
`$3
typescript
toWadeGiles("台北", {
toneFormat: "superscript", // 'superscript' | 'number' | 'none'
separator: "-", // 音節分隔符號
preserveNonChinese: true, // 保留非中文字元
capitalize: false, // 首字母大寫
polyphoneMode: "auto", // 'auto' | 'all'
urlSafe: false, // 僅 ASCII 輸出
});
`$3
typescript
import { pinyinToWadeGiles } from "use-wg";pinyinToWadeGiles("zhong1"); // "chung¹"
pinyinToWadeGiles("guo2"); // "kuo²"
pinyinToWadeGiles("qi4"); // "ch'i⁴"
`$3
typescript
import { containsChinese } from "use-wg";containsChinese("Hello 世界"); // true
containsChinese("Hello World"); // false
`$3
取得詳細的轉換資訊：
typescript
const result = toWadeGiles("台北");console.log(result.text); // "t'ai²-pei³"
console.log(result.segments);
// [
// { original: "台", pinyin: "tai2", wadeGiles: "t'ai", tone: 2 },
// { original: "北", pinyin: "bei3", wadeGiles: "pei", tone: 3 }
// ]
`威妥瑪拼音對照表
主要轉換規則：
| 漢語拼音 | 威妥瑪拼音 | 範例 |
| -------- | ---------- | -------------- |
| b → p | ba → pa | 八 bā → pa¹ |
| p → p' | pa → p'a | 怕 pà → p'a⁴ |
| d → t | da → ta | 大 dà → ta⁴ |
| t → t' | ta → t'a | 他 tā → t'a¹ |
| g → k | ga → ka | 高 gāo → kao¹ |
| k → k' | ka → k'a | 看 kàn → k'an⁴ |
| j → ch | ji → chi | 雞 jī → chi¹ |
| q → ch' | qi → ch'i | 氣 qì → ch'i⁴ |
| x → hs | xi → hsi | 西 xī → hsi¹ |
| zh → ch | zhi → chih | 知 zhī → chih¹ |
| z → ts | zi → tzu | 子 zǐ → tzu³ |
| c → ts' | ci → tz'u | 次 cì → tz'u⁴ |
| r → j | ri → jih | 日 rì → jih⁴ |
| si → ss | si → ssu | 四 sì → ssu⁴ |
API 參考
$3
將中文文字轉換為威妥瑪拼音。
參數：
-
(string) - 要轉換的中文文字
- options (WadeGilesOptions) - 選用的設定選項回傳值：
WadeGilesResult$3
將拼音音節轉換為威妥瑪拼音。
參數：
-
(string) - 帶有選用聲調數字的拼音音節
- options ({ toneFormat?: ToneFormat }) - 選用的聲調格式回傳值：
string$3
檢查字串是否包含中文字元。
參數：
-
(string) - 要檢查的文字回傳值：
boolean型別定義
typescript
type ToneFormat = "superscript" | "number" | "none";interface WadeGilesOptions {
toneFormat?: ToneFormat; // 預設: 'superscript'
separator?: string; // 預設: '-'
preserveNonChinese?: boolean; // 預設: true
capitalize?: boolean; // 預設: false
polyphoneMode?: "auto" | "all"; // 預設: 'auto'
urlSafe?: boolean; // 預設: false
}
interface WadeGilesResult {
text: string;
segments: WadeGilesSegment[];
}
interface WadeGilesSegment {
original: string;
pinyin: string;
wadeGiles: string;
tone?: number;
alternatives?: string[];
}
`效能
執行效能測試：
| 測試 | 輸入 | 平均時間 (ms) | 每秒運算次數 |
| ---------------- | --------------------------------- | ------------- | ------------ |
| 短文字 (2 字) |
| 0.0037 | 273,321 |
| 中等長度 (8 字) | 這是一個測試句子 | 0.0108 | 92,664 |
| 長文字 (11 字) | 台北市信義區忠孝東路四段 | 0.0150 | 66,465 |
| 中英混合 | Hello 世界! This is a test 測試 | 0.0063 | 159,867 |
| 含數字 | 2024年台灣之旅 | 0.0064 | 157,288 |
| URL 安全（短） | 台灣 | 0.0031 | 318,489 |
| URL 安全（混合） | My 台灣 Trip 2024年 | 0.0057 | 176,106 |平均：約 180,000 次/秒
系統需求
- Node.js >= 22
- npm >= 10.0.0
開發
`bash
安裝相依套件
npm install執行測試
npm test建置
npm run build型別檢查
npm run type-check
``MIT License - 詳見 LICENSE 檔案。
Gary Lai - @imgarylai