{"id":49670269,"url":"https://github.com/imgarylai/use-wg","last_synced_at":"2026-05-06T22:18:28.575Z","repository":{"id":334298828,"uuid":"1140896820","full_name":"imgarylai/use-wg","owner":"imgarylai","description":"將中文字轉換為威妥瑪拼音的 TypeScript 函式庫。","archived":false,"fork":false,"pushed_at":"2026-04-30T02:43:10.000Z","size":205,"stargazers_count":0,"open_issues_count":5,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-30T04:24:02.903Z","etag":null,"topics":["chinese","mandarin","typescript"],"latest_commit_sha":null,"homepage":"https://imgarylai.github.io/use-wg/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/imgarylai.png","metadata":{"files":{"readme":"README.en.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-23T22:35:06.000Z","updated_at":"2026-01-30T20:03:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/imgarylai/use-wg","commit_stats":null,"previous_names":["imgarylai/use-wg"],"tags_count":6,"template":false,"template_full_name":"imgarylai/ts-package-starter","purl":"pkg:github/imgarylai/use-wg","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imgarylai%2Fuse-wg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imgarylai%2Fuse-wg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imgarylai%2Fuse-wg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imgarylai%2Fuse-wg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/imgarylai","download_url":"https://codeload.github.com/imgarylai/use-wg/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imgarylai%2Fuse-wg/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32714100,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-06T19:35:05.142Z","status":"ssl_error","status_checked_at":"2026-05-06T19:35:03.996Z","response_time":117,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chinese","mandarin","typescript"],"created_at":"2026-05-06T22:18:27.795Z","updated_at":"2026-05-06T22:18:28.561Z","avatar_url":"https://github.com/imgarylai.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# use-wg\n\nA TypeScript library for converting Chinese characters to Wade-Giles romanization.\n\n[![CI](https://github.com/imgarylai/use-wg/actions/workflows/test.yml/badge.svg)](https://github.com/imgarylai/use-wg/actions/workflows/test.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n[繁體中文](README.md)\n\n## Features\n\n- Chinese characters (Traditional \u0026 Simplified) → Wade-Giles romanization\n- Configurable tone format (superscript, number, none)\n- Mixed Chinese/English text handling\n- URL-safe output mode\n- Context-aware polyphone handling\n- TypeScript support with full type definitions\n- Command-line interface (CLI)\n\n## Installation\n\n```bash\nnpm install use-wg\n```\n\n## CLI\n\nUse directly via `npx`:\n\n```bash\n# Basic usage\nnpx use-wg \"台灣\"              # Output: t'ai²-wan¹\n\n# URL-safe mode\nnpx use-wg \"台灣\" --url-safe    # Output: tai-wan\n\n# Tone formats\nnpx use-wg \"高雄\" --tone number # Output: kao1-hsiung2\nnpx use-wg \"高雄\" --tone none   # Output: kao-hsiung\n\n# From stdin\necho \"台灣\" | npx use-wg\n\n# JSON output (with segments)\nnpx use-wg \"台灣\" --json\n\n# Pinyin mode\nnpx use-wg --pinyin \"zhong1\"    # Output: chung¹\n```\n\n### CLI Options\n\n| Option              | Short | Description                            | Default     |\n| ------------------- | ----- | -------------------------------------- | ----------- |\n| `--url-safe`        | `-u`  | Produce URL-safe output                | false       |\n| `--tone \u003cformat\u003e`   | `-t`  | Tone format: superscript, number, none | superscript |\n| `--separator \u003csep\u003e` | `-s`  | Separator between syllables            | -           |\n| `--capitalize`      | `-c`  | Capitalize first letter                | false       |\n| `--json`            | `-j`  | Output JSON format                     | false       |\n| `--pinyin`          | `-p`  | Pinyin to Wade-Giles mode              | false       |\n\n## Library Usage\n\n### Basic Conversion\n\n```typescript\nimport { toWadeGiles } from \"use-wg\";\n\n// Basic conversion\ntoWadeGiles(\"台灣\").text; // \"t'ai²-wan¹\"\ntoWadeGiles(\"台北\").text; // \"t'ai²-pei³\"\ntoWadeGiles(\"高雄\").text; // \"kao¹-hsiung²\"\n```\n\n### Tone Formats\n\n```typescript\n// Superscript tones (default)\ntoWadeGiles(\"高雄\", { toneFormat: \"superscript\" }).text; // \"kao¹-hsiung²\"\n\n// Number tones\ntoWadeGiles(\"高雄\", { toneFormat: \"number\" }).text; // \"kao1-hsiung2\"\n\n// No tones\ntoWadeGiles(\"高雄\", { toneFormat: \"none\" }).text; // \"kao-hsiung\"\n```\n\n### URL-Safe Mode\n\nProduces ASCII-only output suitable for URLs, filenames, and identifiers:\n\n```typescript\ntoWadeGiles(\"台灣\", { urlSafe: true }).text; // \"tai-wan\"\ntoWadeGiles(\"氣功\", { urlSafe: true }).text; // \"chi-kung\"\n```\n\nURL-safe mode automatically:\n\n- Removes tone markers\n- Converts `ü` → `u`\n- Removes apostrophes (`'`)\n- Outputs lowercase\n- Converts spaces to hyphens (`-`)\n\n### Mixed Chinese/English Text\n\nThe converter intelligently handles mixed text:\n\n```typescript\ntoWadeGiles(\"Hello 世界!\").text; // \"Hello shih⁴-chieh⁴!\"\ntoWadeGiles(\"iPhone 手機 Pro\").text; // \"iPhone shou³-chi¹ Pro\"\ntoWadeGiles(\"2024年\").text; // \"2024nien²\"\n```\n\n### Options\n\n```typescript\ntoWadeGiles(\"台北\", {\n  toneFormat: \"superscript\", // 'superscript' | 'number' | 'none'\n  separator: \"-\", // Separator between syllables\n  preserveNonChinese: true, // Keep non-Chinese characters\n  capitalize: false, // Capitalize first letter\n  polyphoneMode: \"auto\", // 'auto' | 'all'\n  urlSafe: false, // ASCII-only output\n});\n```\n\n### Direct Pinyin Conversion\n\n```typescript\nimport { pinyinToWadeGiles } from \"use-wg\";\n\npinyinToWadeGiles(\"zhong1\"); // \"chung¹\"\npinyinToWadeGiles(\"guo2\"); // \"kuo²\"\npinyinToWadeGiles(\"qi4\"); // \"ch'i⁴\"\n```\n\n### Utility Functions\n\n```typescript\nimport { containsChinese } from \"use-wg\";\n\ncontainsChinese(\"Hello 世界\"); // true\ncontainsChinese(\"Hello World\"); // false\n```\n\n### Segments Information\n\nAccess detailed conversion information:\n\n```typescript\nconst result = toWadeGiles(\"台北\");\n\nconsole.log(result.text); // \"t'ai²-pei³\"\nconsole.log(result.segments);\n// [\n//   { original: \"台\", pinyin: \"tai2\", wadeGiles: \"t'ai\", tone: 2 },\n//   { original: \"北\", pinyin: \"bei3\", wadeGiles: \"pei\", tone: 3 }\n// ]\n```\n\n## Wade-Giles Mapping\n\nKey conversion patterns:\n\n| Pinyin  | Wade-Giles | Example        |\n| ------- | ---------- | -------------- |\n| b → p   | ba → pa    | 八 bā → pa¹    |\n| p → p'  | pa → p'a   | 怕 pà → p'a⁴   |\n| d → t   | da → ta    | 大 dà → ta⁴    |\n| t → t'  | ta → t'a   | 他 tā → t'a¹   |\n| g → k   | ga → ka    | 高 gāo → kao¹  |\n| k → k'  | ka → k'a   | 看 kàn → k'an⁴ |\n| j → ch  | ji → chi   | 雞 jī → chi¹   |\n| q → ch' | qi → ch'i  | 氣 qì → ch'i⁴  |\n| x → hs  | xi → hsi   | 西 xī → hsi¹   |\n| zh → ch | zhi → chih | 知 zhī → chih¹ |\n| z → ts  | zi → tzu   | 子 zǐ → tzu³   |\n| c → ts' | ci → tz'u  | 次 cì → tz'u⁴  |\n| r → j   | ri → jih   | 日 rì → jih⁴   |\n| si → ss | si → ssu   | 四 sì → ssu⁴   |\n\n## API Reference\n\n### `toWadeGiles(text, options?)`\n\nConvert Chinese text to Wade-Giles romanization.\n\n**Parameters:**\n\n- `text` (string) - Chinese text to convert\n- `options` (WadeGilesOptions) - Optional configuration\n\n**Returns:** `WadeGilesResult`\n\n### `pinyinToWadeGiles(pinyin, options?)`\n\nConvert a pinyin syllable to Wade-Giles.\n\n**Parameters:**\n\n- `pinyin` (string) - Pinyin syllable with optional tone number\n- `options` ({ toneFormat?: ToneFormat }) - Optional tone format\n\n**Returns:** `string`\n\n### `containsChinese(text)`\n\nCheck if a string contains Chinese characters.\n\n**Parameters:**\n\n- `text` (string) - Text to check\n\n**Returns:** `boolean`\n\n## Types\n\n```typescript\ntype ToneFormat = \"superscript\" | \"number\" | \"none\";\n\ninterface WadeGilesOptions {\n  toneFormat?: ToneFormat; // Default: 'superscript'\n  separator?: string; // Default: '-'\n  preserveNonChinese?: boolean; // Default: true\n  capitalize?: boolean; // Default: false\n  polyphoneMode?: \"auto\" | \"all\"; // Default: 'auto'\n  urlSafe?: boolean; // Default: false\n}\n\ninterface WadeGilesResult {\n  text: string;\n  segments: WadeGilesSegment[];\n}\n\ninterface WadeGilesSegment {\n  original: string;\n  pinyin: string;\n  wadeGiles: string;\n  tone?: number;\n  alternatives?: string[];\n}\n```\n\n## Performance\n\nRun benchmark: `npm run benchmark`\n\n| Test             | Input                             | Avg (ms) | Ops/sec |\n| ---------------- | --------------------------------- | -------- | ------- |\n| Short (2 chars)  | `台灣`                            | 0.0037   | 273,321 |\n| Medium (8 chars) | `這是一個測試句子`                | 0.0108   | 92,664  |\n| Long (11 chars)  | `台北市信義區忠孝東路四段`        | 0.0150   | 66,465  |\n| Mixed text       | `Hello 世界! This is a test 測試` | 0.0063   | 159,867 |\n| With numbers     | `2024年台灣之旅`                  | 0.0064   | 157,288 |\n| URL-safe short   | `台灣`                            | 0.0031   | 318,489 |\n| URL-safe mixed   | `My 台灣 Trip 2024年`             | 0.0057   | 176,106 |\n\n**Average: ~180,000 ops/sec**\n\n## Requirements\n\n- Node.js \u003e= 22\n- npm \u003e= 10.0.0\n\n## Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Run tests\nnpm test\n\n# Build\nnpm run build\n\n# Type check\nnpm run type-check\n```\n\n## License\n\nMIT License - see the [LICENSE](LICENSE) file for details.\n\n## Author\n\nGary Lai - [@imgarylai](https://github.com/imgarylai)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimgarylai%2Fuse-wg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fimgarylai%2Fuse-wg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimgarylai%2Fuse-wg/lists"}