feat: Misaki互換中国語IPA出力 — v1.10.0 (#56) - #59
Merged
Conversation
Mi1 フェーズ1枚目。声母22エントリ、韻母36エントリ、声調5エントリの Misaki互換マッピングテーブルを新規作成するタスク。PinyinToIpa.cs との 差異（j/q→ʨ/ʨʰ, z/c→ʦ/ʦʰ, 二重母音の非音節化符号, 声調矢印）を 全エントリで明示した。 関連: #56
Mi1 フェーズ2枚目。T01で定義したマッピングテーブルを使用して Convert/ConvertSyllable メソッドを実装するタスク。そり舌母音(zh/ch/sh/r+i)、 歯茎母音(z/c/s+i)、半母音省略(y/w)の特殊処理を含む。PinyinToIpa/ PinyinToPiperIpa/PinyinToMisaki の共通部分を抽象基底クラスで統合する リファクタリング案もセクション6に記載。 関連: #56
Mi2 フェーズ1枚目。PinyinToMisakiをChineseG2PEngineの公開APIに統合する タスク。RunPipelineパターンに沿って ToMisakiIpa / ToMisakiIpaBatch を 追加。既存のToPiperIPAパターンを踏襲し、BatchConversionHelperの静的 メソッド委譲パターンでアロケーションを回避する設計とした。 関連: #56
Mi2 フェーズ2枚目。ChineseMisakiIpaTests.cs を新規作成し、声調マッピング、 声母マッピング、韻母マッピング、そり舌/歯茎母音、声調変調、エッジケース、 Issue #56再現、バッチAPI、Dispose後、他API比較、回帰確認の12カテゴリ 約105件のテストを実装するタスク。既存 ChinesePiperIpaTests.cs の パターンを踏襲し、E2Eテスト中心の方針とした。 関連: #56
Mi3 フェーズ1枚目。README.md(4箇所)、CLAUDE.md(進捗テーブル)、 設計ドキュメント、マイルストーン計画を更新するタスク。パフォーマンス テスト(ToMisakiIpa vs ToIPA の1.2倍以内)とMisaki Python実装との 出力比較テスト5種も含む。 関連: #56
Mi3 フェーズ2枚目(最終)。v1.10.0(MINOR bump、新API追加)として計11 ファイルのバージョン更新、CI 6マトリクス確認、NuGet/UPM同時リリース、 Issue #56フォローアップコメント投稿を行うタスク。リリース後の将来課題 (Multilingual統合、Misaki v1.1注音パス、他言語Kokoro互換)も記載。 関連: #56
3エージェント(アーキテクト/マッピング戦略/テスタビリティ)による並列レビューで 以下を追加: T01: - アーキテクトレビュー(PinyinToZhuyinの除外分析、4方式比較、段階的移行工程表) - マッピング戦略再検討(TSV外部化、差分マッピング、Source Generator、6方式比較表) T02: - アーキテクトレビュー(4層分解、4方式C#実装例、record+switch式推奨) - テスタビリティ観点(internal static問題、PinyinConversionResult構造体化、 TryConvert+エラー粒度、Conditionalトレース、InternalsVisibleTo確認) 結論: 現行の独立テーブル方式をT02スコープで維持しつつ、将来の record+switch式 抽象化への移行を可能にする「ファサード維持・エントリ順序統一・Unicode定数化」を 実践的推奨とする。 関連: #56
3エージェント(API設計/テスト戦略/システム統合)による並列レビューで以下を追加:
T03 (+373行):
- API設計レビュー(現行31メソッドの爆発問題、戦略パターン+enum OutputFormat
実装例、Fluent API設計、v1.10→v2.0のSemVerロードマップ、他言語命名整合性)
- システム統合レビュー(Multilingual層のIMisakiCapableProcessor拡張、
Unity IL2CPP対応、KokoroSharp統合サンプル3種、NuGet/UPM両配布制約、
他言語拡張の命名規則統一)
T04 (+738行):
- テスト戦略レビュー(TSV駆動テスト完全実装コード、Verify.Xunit Snapshot、
tools/DotNetG2P.MisakiEval ツール設計、既存Piperテスト統一戦略で68%削減案、
KoreanBenchmarkDataLoaderの既存例参照)
- システム統合レビュー(MultilingualMisakiIpaTests先行配置、Preserve属性
リフレクション検証、KokoroSharp非依存契約テスト、埋め込み辞書検証、
他言語共通テスト命名規則{Lang}MisakiIpaTests)
主要発見: CapabilityAdapters.cs の IIpaTextBatchProcessor は標準IPAのみ対応で
Multilingual経由のMisakiルートが未整備。ChineseG2PEngine.csは既に[Preserve]
付与済みでT03のメソッド追加で自動カバー。
関連: #56
3エージェント(ドキュメント戦略/リリース戦略/全体振り返り)による並列レビューで 以下を追加: T05 (+235行): - ドキュメント戦略(DocFXは整備済みだがGitHub Pages公開フロー未定義、 コードXMLDocをSSoTとしたREADME/DocFX自動生成、英語版は逆転発想でXMLDoc 英語SSoT、conventional commits日本語折衷、段階的ロードマップ) - 全体振り返り(Mi1+Mi2統合2フェーズ案、チケット粒度6→3枚再構成、 TSVテスト+ドキュメント並列化30-40%短縮、Phase1/2横断論点8項目のADR化、 Mi4英語Misaki教訓7項目) T06 (+513行): - リリース戦略(release-please+日本語CHANGELOG設定、PublicApiAnalyzer導入、 Nightly+GitHub Packages 3層feed、Misaki上流監視週次ワークフロー、 独立バージョニング7.5人日試算、Infra-1〜7再編) - 全体振り返り(-preview.N先行リリース、軽量リリースフロー、preview版 フィードバック活用、ADR導入5件、教訓9項目、Mi4起票前チェックリスト ADR新設提案) 結論: 次回Mi起票前にT05/T06§Fを統合した「Mi4起票前チェックリスト」を ADRに新設することを推奨。全6チケット+3フェーズレビュー完了。 関連: #56
Misaki 互換中国語G2Pの第一ステップとして、声母・韻母・声調の全
マッピングテーブルを定義する内部静的クラスを新規追加。
- src/DotNetG2P.Chinese/Conversion/PinyinToMisaki.cs (新規)
- 声母 22 エントリ Dictionary<Initial, string>
* j/q は合字 ʨ/ʨʰ (U+02A8) を使用 (標準IPA tɕ/tɕʰ との差異)
* z/c は合字 ʦ/ʦʰ (U+02A6) を使用 (標準IPA ts/tsʰ との差異)
- 韻母 36 エントリ Dictionary<Final, string>
* 二重母音 ai/ei/ao/ou → ai̯/ei̯/au̯/ou̯ (非音節化符号 U+032F)
* iao/iu/uai/ui も同様に非音節化符号付与
* ong/iong は u̯ŋ/iu̯ŋ の表記
- 声調 5 エントリ string[] (矢印記号 → ↗ ↓ ↘)
- そり舌母音 ɻ̩ / 歯茎母音 ɹ̩ は標準IPAと同一
- テスタビリティ用 internal アクセサ 5 種
(GetInitialMisaki / GetFinalMisaki / GetToneArrow /
GetRetroflexApical / GetAlveolarApical)
- tests/DotNetG2P.Tests/ChineseG2P/PinyinToMisakiMappingTests.cs (新規)
- 声母 22 + 韻母 36 + 声調 5 の全エントリを検証する 127 テスト
- Misaki 固有の差異 (ʨ/ʦ 合字、非音節化符号、矢印声調) に
focused テストを追加
- 全 Initial/Final 網羅性テスト
全127テスト成功。PinyinToIpa/PinyinToPiperIpa に影響なし。
Ref: T01 (docs/tickets/T01-misaki-mapping-tables.md), Mi1, Issue #56
T01 で定義したマッピングテーブルを使い、Convert/ConvertSyllable の
公開/内部メソッドを追加。PinyinToIpa.ConvertSyllable の変換ロジック
（半母音省略・そり舌母音・歯茎母音・声調付与）を踏襲しつつ、
テーブル参照のみを Misaki 用に差し替えた。
- src/DotNetG2P.Chinese/Conversion/PinyinToMisaki.cs
- public Convert(string) / Convert(string, bool includeTones)
- internal ConvertSyllable(PinyinSyllable, bool)
- private IsRetroflex / IsAlveolar / ShouldOmitSemivowel
- 処理フロー: null/空チェック → ToneConverter.ToToneMarked
→ PinyinParser.TryParse → ConvertSyllable
- ConvertSyllable ステップ:
声母 (Y/W 半母音省略判定) → 韻母 (そり舌/歯茎母音の特別処理)
→ 声調矢印 (includeTones && !Neutral のときのみ)
- tests/DotNetG2P.Tests/ChineseG2P/PinyinToMisakiConvertTests.cs (新規)
- 61 件のテスト:
* 4声 + 軽声の矢印変換
* 数字声調形式 (ma1-ma4) の正規化
* includeTones=false の声調省略
* j/q/z/c の Misaki 合字 (ʨ/ʨʰ/ʦ/ʦʰ)
* 二重母音の非音節化符号 (ai̯/au̯/ei̯/ou̯/iau̯/iou̯/uai̯/uei̯)
* ong/iong の u̯ŋ/iu̯ŋ 表記
* そり舌母音 (zhi/chi/shi/ri)
* 歯茎母音 (zi/ci/si)
* y/w 半母音省略 (yi/yin/ying/yu/yue/yuan/yun/wu)
* ゼロ声母 (a/e/o)
* null/空/不正入力のエッジケース
* PinyinToIpa との差分確認 (j 声母・ai 韻母・声調マーカー)
- Issue #56 参照例 (nǐ/hǎo) の個別音節変換
テスト結果:
- PinyinToMisakiConvertTests: 61/61 成功
- PinyinToMisakiMappingTests: 127/127 成功 (T01 分)
- Chinese 全体 (perf除く): 1497/1497 成功、回帰なし
Ref: T02 (docs/tickets/T02-misaki-convert-method.md), Mi1, Issue #56
…書き換え
Phase 1 レビューエージェントが hexgrad/misaki 公式ソースを取得・実測した結果、
旧実装 (推定仕様ベース) と Misaki 実出力に多数の乖離を発見。
uv misaki 0.9.4 で 137 件の gold standard を実測し、全面書き換え。
### 声母 (21 エントリ)
- j/q → ʨ/ʨʰ (U+02A8、合字) — 旧仕様と同一 (correct)
- z/c → ʦ/ʦʰ (U+02A6) — 旧仕様と同一 (correct)
- zh/ch → ꭧ/ꭧʰ (U+AB67) ← **旧 ʈʂ/ʈʂʰ から変更**
(Kokoro 82M vocab に U+AB67 含有を確認)
- Y/W は声母テーブルから除外 (compound final 層で処理)
### 韻母 (36 エントリ、Prefix + Tone + Suffix 方式)
- 声調位置: **末尾付与→韻母内挿入** (例: "an"→"a{tone}n")
- U+032F: テンプレートから事前除去 (legacy_call strip 相当)
- ɻ̩/ɹ̩ → **ɨ (U+0268) 直接** (retone 相当)
- ong/iong: **ʊŋ/jʊŋ** (旧 u̯ŋ/iu̯ŋ は誤り)
- i 系: **j 半母音付与** (ia→ja, ian→jɛn, ie→je 等)
- u 系: **w 半母音付与** (ua→wa, uo→wo, uan→wan 等)
- ü 系: üe→**ɥe** (U+0265)、üan→**ɥɛn** (旧 yɛ/yan は誤り)
- Er: **ɚ** (U+025A、旧 əɻ は誤り)
- O: **wo** (bpmf+o)、**ɔ** (単独感嘆詞)
### Y/W 複合韻母 (23 エントリ、新規テーブル)
- DotNetG2P PinyinParser は "wang" を W+Ang にパースするため、
Misaki の "uang" 相当に変換する (Initial,Final)→(Prefix,Suffix,OmitInitial) lookup
- 省略ケース: yi→i, yin→in, ying→iŋ, yu→y, yun→yn, wu→u
### テスト
- PinyinToMisakiMappingTests: 127→172 件 (+45)
- PinyinToMisakiConvertTests: 61→150 件 (+89)
- Chinese 全体 (perf除く): 1631 件成功、回帰なし
- 全期待値は uv misaki 0.9.4 の実測 gold standard に基づく
### チケット
- T01/T02 を Misaki 公式準拠で全面書き換え (Phase 1-R 教訓を追加)
検証済み:
- Kokoro 82M vocab: ꭧ/ʨ/ʦ/ɨ/ɥ/ʊ/ə/ɤ/ɛ/ɚ/ɔ/→/↗/↓/↘ 全て含有
- Y/W 23 組合せ: Misaki と全件一致 (独立実測)
- gold standard 137+770=907 件: エラーゼロ
Ref: T01, T02, Mi1, Issue #56
T03: ChineseG2PEngine に ToMisakiIPA/ToMisakiIPABatch API を追加。 既存の ToIPA/ToPiperIPA と同一の RunPipeline パターンで実装。 API 命名は IPA 全大文字で統一 (ToMisakiIPA)。 T04: ChineseMisakiIpaTests.cs に 130 件の統合テストを実装。 声調矢印・声母(ʨ/ʦ/ꭧ合字)・韻母(Prefix+Suffix)・そり舌/歯茎(ɨ)・ 声調変調・Y/W OmitInitial・bpmf+o・エッジケース・Issue#56再現・ バッチAPI・Dispose・回帰確認の 12 セクション。 レビュー指摘による改善: - API 命名統一 (ToMisakiIpa→ToMisakiIPA) - IsRetroflex/IsAlveolar 重複分岐を統合 - Assert.Equal 完全一致テスト 14 件追加 - Tone sandhi 設計判断を XMLDoc に文書化
T05: ドキュメント更新 - README.md: Misaki互換IPA のコードサンプル・特徴説明・APIテーブル追加 - CLAUDE.md: 中国語テスト数 1776+、Misaki互換IPA対応を進捗テーブルに反映 - docs/guides/misaki-milestones.md: Mi1-Mi3 全マイルストーン完了 - docs/guides/misaki-compatible-chinese.md: API名統一(ToMisakiIPA)、Phase 1-R知見追記 T06: v1.10.0 リリース準備 - Directory.Build.props + 全10 package.json のバージョンを 1.9.0 → 1.10.0 に更新 - 破壊的変更なし（既存API のシグネチャ・挙動は v1.9.x と同一）
レビュー指摘による修正: - T01-T06 全チケットの status を「未着手」→「完了」に更新 - T03-T05 チケット内の API名を ToMisakiIpa → ToMisakiIPA に統一 (213箇所) - CHANGELOG.md に v1.10.0 エントリを追加 (Misaki互換IPA API) - README.md の「4種の出力スタイル」→「多彩な出力スタイル」に修正 - CLAUDE.md の進捗表記を「C1-C6 + Mi1-Mi3完了」に更新
There was a problem hiding this comment.
Pull request overview
This PR adds a Misaki (Kokoro TTS)–compatible Chinese IPA output path to DotNetG2P.Chinese, including a dedicated pinyin→Misaki-IPA converter, new ChineseG2PEngine public APIs, and extensive test coverage, plus repository-wide version bump to v1.10.0.
Changes:
- Add
PinyinToMisakiconversion with Misaki-specific initials/finals/tone-arrow rules and Y/W compound handling. - Expose
ToMisakiIPA/ToMisakiIPABatchAPIs onChineseG2PEngine(withincludeTonesoverloads). - Add comprehensive unit/integration tests and update docs + package versions for the v1.10.0 release.
Reviewed changes
Copilot reviewed 29 out of 29 changed files in this pull request and generated 8 comments.
Show a summary per file
| File | Description |
|---|---|
src/DotNetG2P.Chinese/Conversion/PinyinToMisaki.cs |
Implements Misaki-compatible pinyin→IPA conversion (tone arrows, ligatures, special vowels, Y/W compounds). |
src/DotNetG2P.Chinese/ChineseG2PEngine.cs |
Adds ToMisakiIPA + batch APIs integrated via existing RunPipeline/batch helper patterns. |
tests/DotNetG2P.Tests/ChineseG2P/PinyinToMisakiMappingTests.cs |
Validates mapping tables (initials/finals/tones/YW compounds) and key deltas vs standard IPA. |
tests/DotNetG2P.Tests/ChineseG2P/PinyinToMisakiConvertTests.cs |
Validates end-to-end pinyin conversion outputs against Misaki 0.9.4 gold data behavior. |
tests/DotNetG2P.Tests/ChineseG2P/ChineseMisakiIpaTests.cs |
Integration tests through ChineseG2PEngine.ToMisakiIPA* including sandhi behavior, batch APIs, and regressions. |
README.md |
Documents the new Misaki-compatible API and adds examples + API table entries. |
docs/guides/misaki-compatible-chinese.md |
Adds a design guide for Misaki-compatible Chinese output (needs accuracy fixes per comments). |
docs/guides/misaki-milestones.md |
Adds milestone tracking doc (needs method-name/example accuracy fixes per comments). |
docs/guides/toc.yml |
Adds guide entries to documentation TOC. |
docs/tickets/T05-documentation-qa.md |
Adds internal ticket doc (contains outdated examples/types that need alignment). |
docs/tickets/T03-engine-api-integration.md |
Adds internal API-integration ticket documentation. |
docs/tickets/README.md |
Adds a ticket index for the Misaki-compatible effort. |
CLAUDE.md |
Updates project status/version and Chinese row notes for Misaki IPA support. |
CHANGELOG.md |
Adds v1.10.0 release notes (contains a future date that should be corrected). |
Directory.Build.props |
Bumps build/package version to 1.10.0. |
src/DotNetG2P.Core/package.json |
UPM package version bump to 1.10.0. |
src/DotNetG2P.Chinese/package.json |
UPM package version bump to 1.10.0. |
src/DotNetG2P.English/package.json |
UPM package version bump to 1.10.0. |
src/DotNetG2P.French/package.json |
UPM package version bump to 1.10.0. |
src/DotNetG2P.Korean/package.json |
UPM package version bump to 1.10.0. |
src/DotNetG2P.MeCab/package.json |
UPM package version bump + dependency bump to 1.10.0. |
src/DotNetG2P.Multilingual/package.json |
UPM package version bump + dependency bumps to 1.10.0. |
src/DotNetG2P.Portuguese/package.json |
UPM package version bump to 1.10.0. |
src/DotNetG2P.Spanish/package.json |
UPM package version bump to 1.10.0. |
src/DotNetG2P.Swedish/package.json |
UPM package version bump to 1.10.0. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- misaki-compatible-chinese.md: U+032F 記述除去、バッチ戻り値型修正、zh/chꭧ合字の記述更新 - misaki-milestones.md: API名 ToMisakiIPA 統一、出力例の U+032F 除去 - T05-documentation-qa.md: 出力例修正、バッチ戻り値型 string[]→IReadOnlyList<string>
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 30 out of 30 changed files in this pull request and generated 2 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Coverage SummaryTarget: ubuntu-latest / .NET 9 |
- PinyinToMisaki.cs: Y/W が compound テーブルにない場合 string.Empty を返すガード追加 - PinyinToMisakiMappingTests.cs: Assert.IsType<bool>(found) → Assert.False(found) に修正
docs/guides/misaki-milestones.md から docs/tickets/ への相対リンクが DocFX の content スコープ外のため InvalidFileLink 警告 (7件) が発生。 --warningsAsErrors で CI が失敗していた。リンクをテキスト参照に変更。
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 30 out of 30 changed files in this pull request and generated 3 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- PinyinToMisaki.cs: Y/W 未定義組み合わせの早期リターンを特別ケース判定の前に移動 (Y+Er 等が Er 処理を先に通過する問題を修正) - ChineseMisakiIpaTests.cs: Separator オプション (空文字/ハイフン) テスト2件追加 - misaki-compatible-chinese.md: 出力例を ni↓ xau↓ (スペース区切り) に修正、 音節区切り説明を「語間」→「音節間」に修正
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
DotNetG2P.Chineseに追加新規 API
ToMisakiIPA(text)ToMisakiIPA(text, includeTones)ToMisakiIPABatch(texts)ToMisakiIPABatch(texts, includeTones)実装詳細
Phase 1 (Mi1): PinyinToMisaki コア変換
Phase 2 (Mi2): API統合 + テスト
Phase 3 (Mi3): ドキュメント + リリース準備
Test plan
Closes #56