use-wg

將中文字轉換為威妥瑪拼音的 TypeScript 函式庫。

English

功能特色

• 中文字（繁體及簡體）→ 威妥瑪拼音轉換
• 可設定聲調格式（上標、數字、無）
• 處理中英文混合文字
• URL 安全輸出模式
• 上下文感知的多音字處理
• 完整的 TypeScript 型別定義
• 命令列工具（CLI）

安裝

npm install use-wg

CLI 命令列工具

直接透過 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¹

CLI 選項

| 選項 | 簡寫 | 說明 | 預設值 | | ------------------- | ---- | ----------------------------------- | ----------- | | --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"

URL 安全模式

產生僅包含 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⁴ |

API 參考

toWadeGiles(text, options?)

將中文文字轉換為威妥瑪拼音。

參數：

• text (string) - 要轉換的中文文字
• options (WadeGilesOptions) - 選用的設定選項

回傳值： WadeGilesResult

pinyinToWadeGiles(pinyin, options?)

將拼音音節轉換為威妥瑪拼音。

參數：

• pinyin (string) - 帶有選用聲調數字的拼音音節
• options ({ toneFormat?: ToneFormat }) - 選用的聲調格式

回傳值： string

containsChinese(text)

檢查字串是否包含中文字元。

參數：

• 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-check

授權

MIT License - 詳見 LICENSE 檔案。

作者

Gary Lai - @imgarylai