將中文字轉換為威妥瑪拼音的 TypeScript 函式庫。
- 中文字（繁體及簡體）→ 威妥瑪拼音轉換
- 可設定聲調格式（上標、數字、無）
- 處理中英文混合文字
- URL 安全輸出模式
- 上下文感知的多音字處理
- 完整的 TypeScript 型別定義
- 命令列工具（CLI）
npm install use-wg直接透過 npx 使用：
# 基本用法
npx use-wg "台灣" # 輸出: t'ai²-wan¹
# URL 安全模式
npx use-wg "台灣" --url-safe # 輸出: tai-wan
# 聲調格式
npx use-wg "高雄" --tone number # 輸出: kao1-hsiung2
npx use-wg "高雄" --tone none # 輸出: kao-hsiung
# 從 stdin 讀取
echo "台灣" | npx use-wg
# JSON 輸出（含分段資訊）
npx use-wg "台灣" --json
# 拼音轉換模式
npx use-wg --pinyin "zhong1" # 輸出: chung¹| 選項 | 簡寫 | 說明 | 預設值 |
|---|---|---|---|
--url-safe |
-u |
輸出 URL 安全格式 | false |
--tone <format> |
-t |
聲調格式: superscript, number, none | superscript |
--separator <sep> |
-s |
音節分隔符號 | - |
--capitalize |
-c |
首字母大寫 | false |
--json |
-j |
輸出 JSON 格式 | false |
--pinyin |
-p |
拼音轉威妥瑪模式 | false |
import { toWadeGiles } from "use-wg";
// 基本轉換
toWadeGiles("台灣").text; // "t'ai²-wan¹"
toWadeGiles("台北").text; // "t'ai²-pei³"
toWadeGiles("高雄").text; // "kao¹-hsiung²"// 上標聲調（預設）
toWadeGiles("高雄", { toneFormat: "superscript" }).text; // "kao¹-hsiung²"
// 數字聲調
toWadeGiles("高雄", { toneFormat: "number" }).text; // "kao1-hsiung2"
// 無聲調
toWadeGiles("高雄", { toneFormat: "none" }).text; // "kao-hsiung"產生僅包含 ASCII 字元的輸出，適用於網址、檔案名稱和識別碼：
toWadeGiles("台灣", { urlSafe: true }).text; // "tai-wan"
toWadeGiles("氣功", { urlSafe: true }).text; // "chi-kung"URL 安全模式會自動：
- 移除聲調標記
- 將
ü轉換為u - 移除撇號（
'） - 輸出小寫
- 將空格轉換為連字號（
-）
轉換器能智慧處理混合文字：
toWadeGiles("Hello 世界!").text; // "Hello shih⁴-chieh⁴!"
toWadeGiles("iPhone 手機 Pro").text; // "iPhone shou³-chi¹ Pro"
toWadeGiles("2024年").text; // "2024nien²"toWadeGiles("台北", {
toneFormat: "superscript", // 'superscript' | 'number' | 'none'
separator: "-", // 音節分隔符號
preserveNonChinese: true, // 保留非中文字元
capitalize: false, // 首字母大寫
polyphoneMode: "auto", // 'auto' | 'all'
urlSafe: false, // 僅 ASCII 輸出
});import { pinyinToWadeGiles } from "use-wg";
pinyinToWadeGiles("zhong1"); // "chung¹"
pinyinToWadeGiles("guo2"); // "kuo²"
pinyinToWadeGiles("qi4"); // "ch'i⁴"import { containsChinese } from "use-wg";
containsChinese("Hello 世界"); // true
containsChinese("Hello World"); // false取得詳細的轉換資訊：
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⁴ |
將中文文字轉換為威妥瑪拼音。
參數：
text(string) - 要轉換的中文文字options(WadeGilesOptions) - 選用的設定選項
回傳值： WadeGilesResult
將拼音音節轉換為威妥瑪拼音。
參數：
pinyin(string) - 帶有選用聲調數字的拼音音節options({ toneFormat?: ToneFormat }) - 選用的聲調格式
回傳值： string
檢查字串是否包含中文字元。
參數：
text(string) - 要檢查的文字
回傳值： boolean
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[];
}執行效能測試：npm run benchmark
| 測試 | 輸入 | 平均時間 (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
# 安裝相依套件
npm install
# 執行測試
npm test
# 建置
npm run build
# 型別檢查
npm run type-checkMIT License - 詳見 LICENSE 檔案。
Gary Lai - @imgarylai