use-wg

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