ts-package-starter - v1.3.0
    Preparing search index...

    ts-package-starter - v1.3.0

    use-wg

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

    CI License: MIT

    English

    • 中文字（繁體及簡體）→ 威妥瑪拼音轉換
    • 可設定聲調格式（上標、數字、無）
    • 處理中英文混合文字
    • 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⁴

    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

    Settings

    Member Visibility

    On This Page

    use-wg