@cornhsu/polymigrate-darwin-x64 2.2.1 → 2.3.1

package/bin/PolyMigrate.Core.xml

@@ -150,6 +150,33 @@
         <member name="M:PolyMigrate.Core.Extraction.MissingImage.#ctor(System.String,System.String)">
             <summary>頁面引用但鏡像中不存在的圖 = 原站即 404(§2.6),記錄不阻斷。</summary>
         </member>
+        <member name="T:PolyMigrate.Core.Extraction.AlternateLink">
+            <summary>
+            一則 <c>&lt;link rel="alternate" hreflang&gt;</c> 宣告(§1.4):作者自己講的語言版本對應。
+            這裡只如實記錄,不判斷可不可信——解析與守門在 <see cref="T:PolyMigrate.Core.Pairing.HreflangIndex"/>。
+            </summary>
+            <param name="Hreflang">屬性原值(如 <c>en</c>、<c>zh-Hant</c>、<c>x-default</c>),不正規化。</param>
+            <param name="Href">屬性原值,可能是相對路徑。</param>
+            <param name="TargetUrl">以頁面 URL 解析後的絕對 URL。</param>
+        </member>
+        <member name="M:PolyMigrate.Core.Extraction.AlternateLink.#ctor(System.String,System.String,System.String)">
+            <summary>
+            一則 <c>&lt;link rel="alternate" hreflang&gt;</c> 宣告(§1.4):作者自己講的語言版本對應。
+            這裡只如實記錄,不判斷可不可信——解析與守門在 <see cref="T:PolyMigrate.Core.Pairing.HreflangIndex"/>。
+            </summary>
+            <param name="Hreflang">屬性原值(如 <c>en</c>、<c>zh-Hant</c>、<c>x-default</c>),不正規化。</param>
+            <param name="Href">屬性原值,可能是相對路徑。</param>
+            <param name="TargetUrl">以頁面 URL 解析後的絕對 URL。</param>
+        </member>
+        <member name="P:PolyMigrate.Core.Extraction.AlternateLink.Hreflang">
+            <summary>屬性原值(如 <c>en</c>、<c>zh-Hant</c>、<c>x-default</c>),不正規化。</summary>
+        </member>
+        <member name="P:PolyMigrate.Core.Extraction.AlternateLink.Href">
+            <summary>屬性原值,可能是相對路徑。</summary>
+        </member>
+        <member name="P:PolyMigrate.Core.Extraction.AlternateLink.TargetUrl">
+            <summary>以頁面 URL 解析後的絕對 URL。</summary>
+        </member>
         <member name="T:PolyMigrate.Core.Extraction.ExtractedPage">
             <summary>單頁抽取結果(規格 main 迴圈單檔部分的全部產物)。</summary>
         </member>
@@ -162,6 +189,9 @@
         <member name="P:PolyMigrate.Core.Extraction.ExtractedPage.NeedFetch">
             <summary>待補下載的本地影片/PDF 原始 URL(爬蟲當初沒抓 &lt;source&gt;/&lt;iframe pdf&gt;)。</summary>
         </member>
+        <member name="P:PolyMigrate.Core.Extraction.ExtractedPage.Alternates">
+            <summary>本頁 &lt;head&gt; 宣告的語言版本對應(§1.4);沒宣告的站是空清單,這很常見。</summary>
+        </member>
         <member name="T:PolyMigrate.Core.Extraction.ExtractionPaths">
             <summary>Phase 2 輸入/輸出位置。預設佈局:root/raw、root/media,輸出至 root。</summary>
         </member>
@@ -177,6 +207,18 @@
         <member name="P:PolyMigrate.Core.Extraction.ExtractionReport.SuggestedPairs">
             <summary>啟發式配對建議的組數(§1.4),待人工覆核。</summary>
         </member>
+        <member name="P:PolyMigrate.Core.Extraction.ExtractionReport.HreflangDeclared">
+            <summary>原站宣告的 <c>hreflang</c> 則數(全部,含指到站外/自我指涉/x-default)。</summary>
+        </member>
+        <member name="P:PolyMigrate.Core.Extraction.ExtractionReport.HreflangUsable">
+            <summary>其中通過全部門檻、可用於配對的則數(見 <see cref="T:PolyMigrate.Core.Pairing.HreflangIndex"/>)。</summary>
+        </member>
+        <member name="P:PolyMigrate.Core.Extraction.ExtractionReport.HreflangInFallback">
+            <summary>
+            <c>pairing.fallback</c> 有沒有列 <c>hreflang</c>。false = 上面兩個數字只是觀察,
+            這次跑完全沒拿 hreflang 配過任何一頁——不講的話,看到 usable 有數字的人會以為它有作用。
+            </summary>
+        </member>
         <member name="P:PolyMigrate.Core.Extraction.ExtractionReport.PathIssues">
             <summary>路徑安全問題(§3.4):error = 拒寫並跳過該頁;warning = 照寫但記錄(如超長路徑)。</summary>
         </member>
@@ -215,9 +257,17 @@
             純比對,不動磁碟。
             </summary>
         </member>
-        <member name="M:PolyMigrate.Core.Extraction.ExtractionPipeline.SuggestPairs(System.Collections.Generic.SortedDictionary{System.String,PolyMigrate.Core.Inventory.InventoryRecord},System.Collections.Generic.List{System.String})">
+        <member name="M:PolyMigrate.Core.Extraction.ExtractionPipeline.SuggestPairs(System.Collections.Generic.SortedDictionary{System.String,PolyMigrate.Core.Inventory.InventoryRecord},System.Collections.Generic.List{System.String},PolyMigrate.Core.Pairing.HreflangIndex)">
             <summary>對「只有單語」的 key 產生啟發式配對建議(§1.4);回傳 key → 建議,兩端各一筆。</summary>
         </member>
+        <member name="M:PolyMigrate.Core.Extraction.ExtractionPipeline.WriteHreflangMap(System.String,PolyMigrate.Core.Pairing.HreflangIndex)">
+            <summary>
+            原站宣告的 hreflang 全紀錄(§1.4)。**含不可用的**——這份檔案的用途是回答
+            「這個站的 hreflang 到底能不能信」,所以指到站外、指到 404、只有單向的那些,
+            正是最該被看見的資料。只留可用的,等於把品質問題藏起來。
+            恆輸出(沒宣告 hreflang 的站只有表頭),缺檔與空檔在診斷時意思完全不同。
+            </summary>
+        </member>
         <member name="M:PolyMigrate.Core.Extraction.ExtractionPipeline.WriteRedirectExports(System.String,System.Collections.Generic.List{PolyMigrate.Core.Inventory.Redirect})">
             <summary>301 設定檔:每種格式一個 IRedirectExporter(見 Redirects/),新增格式不必動這裡。</summary>
         </member>
@@ -227,6 +277,16 @@
             外部、錨點、mailto 等保留原樣。
             </summary>
         </member>
+        <member name="M:PolyMigrate.Core.Extraction.LinkRewriter.RouteForUrl(System.String)">
+             <summary>
+             絕對 URL → 站內路由;**不同 host 一律回 null**。
+            
+             <para>host 這一關看起來多餘,其實是 hreflang 配對的安全門:很多站的英文版在
+             <c>en.example.org</c> 而不是 <c>/en/</c>,若只比對路徑,站外的
+             <c>https://en.example.org/ch/news/a.php</c> 會算出與本站
+             <c>/ch/news/a</c> 一模一樣的路由,於是一頁被當成自己的翻譯。</para>
+             </summary>
+        </member>
         <member name="M:PolyMigrate.Core.Extraction.LinkRewriter.RouteForPath(System.String)">
             <summary>
             站內路徑 → 新路由:去動態副檔名、收攏 index。
@@ -267,6 +327,20 @@
             圖片 → 根絕對網路路徑 + 壞圖偵測,最後 HTML → Markdown。
             </summary>
         </member>
+        <member name="M:PolyMigrate.Core.Extraction.PageExtractor.ReadAlternates(AngleSharp.Dom.IDocument,System.String)">
+             <summary>
+             &lt;head&gt; 裡的 <c>&lt;link rel="alternate" hreflang&gt;</c>——全站唯一由作者「宣告」的
+             語言版本對應,其餘配對線索(路徑、相簿、日期、標題)都是推測出來的。
+            
+             <para>刻意<b>不</b>認 <c>&lt;a hreflang&gt;</c>:那是「這個連結指向的東西是什麼語言」的標註,
+             不是「本頁的某語言版本在這裡」的宣告。內文裡一句「另見 &lt;a hreflang="en"&gt;英文說明&lt;/a&gt;」
+             會被當成本頁的英文版,而那通常是另一篇文章。</para>
+            
+             <para>抽取階段一律照收(含 <c>x-default</c>、自我指涉、指到站外的),
+             可不可信留給 <see cref="T:PolyMigrate.Core.Pairing.HreflangIndex"/> 判——原始觀察與判斷分開,
+             才有辦法先量一個站的 hreflang 品質再決定要不要信它。</para>
+             </summary>
+        </member>
         <member name="M:PolyMigrate.Core.Extraction.PageExtractor.CleanupMarkdown(System.String)">
             <summary>
             與規格(markdownify)行為對齊的輸出清理:ReverseMarkdown 會留下
@@ -427,6 +501,18 @@
         <member name="M:PolyMigrate.Core.Inventory.Redirect.#ctor(System.String,System.String,System.String,System.String)">
             <summary>一筆 301:原始 URL → 新路由,附語言與配對鍵。</summary>
         </member>
+        <member name="T:PolyMigrate.Core.Inventory.HreflangLink">
+            <summary>
+            一則 hreflang 宣告,補上兩端在本站的路由(§1.4)。
+            <paramref name="TargetRoute"/> = null 代表指到站外(見 <see cref="M:PolyMigrate.Core.Extraction.LinkRewriter.RouteForUrl(System.String)"/>)。
+            </summary>
+        </member>
+        <member name="M:PolyMigrate.Core.Inventory.HreflangLink.#ctor(System.String,System.String,System.String,System.String,System.String,System.String,System.String)">
+            <summary>
+            一則 hreflang 宣告,補上兩端在本站的路由(§1.4)。
+            <paramref name="TargetRoute"/> = null 代表指到站外(見 <see cref="M:PolyMigrate.Core.Extraction.LinkRewriter.RouteForUrl(System.String)"/>)。
+            </summary>
+        </member>
         <member name="T:PolyMigrate.Core.Inventory.InventoryAggregator">
             <summary>
             逐頁把 <see cref="T:PolyMigrate.Core.Extraction.ExtractedPage"/> 摺疊成各清單的中間表示(以 translation_key 聚合各語言版本)。
@@ -439,6 +525,12 @@
             純記憶體、零 I/O —— 讓聚合邏輯不必落磁碟就能單獨測(對照 ExtractionPipeline 的全站 golden 測)。
             </summary>
         </member>
+        <member name="P:PolyMigrate.Core.Inventory.InventoryAggregator.HreflangLinks">
+            <summary>各頁宣告的 hreflang(原始觀察,未過濾);解析見 <see cref="T:PolyMigrate.Core.Pairing.HreflangIndex"/>。</summary>
+        </member>
+        <member name="P:PolyMigrate.Core.Inventory.InventoryAggregator.RouteToKey">
+            <summary>站內路由 → translation_key。hreflang 指到的頁「在不在鏡像裡」就靠這張表回答。</summary>
+        </member>
         <member name="T:PolyMigrate.Core.Inventory.MediaHashCache">
             <summary>
             媒體雜湊快取:(相對路徑, 大小, mtime)→ sha1。
@@ -673,9 +765,100 @@
             probe 不跟轉址(轉址頁不算命中);fetch 要跟(頁面可能在 301 之後)。
             </summary>
         </member>
+        <member name="T:PolyMigrate.Core.Pairing.HreflangRow">
+            <summary>
+            <c>hreflang_map.csv</c> 的一列:一則宣告,加上它經不經得起查證。
+            </summary>
+            <param name="InMirror">目標頁在鏡像裡(同 host、且該路由真的抽到過一頁)。</param>
+            <param name="Reciprocal">目標頁也宣告了一則指回來的 hreflang。</param>
+            <param name="Usable">通過全部門檻,可用於配對(不代表一定產生了建議)。</param>
+            <param name="RejectReason">不可用的原因,見 <see cref="T:PolyMigrate.Core.Pairing.HreflangIndex"/> 的常數;可用時為空字串。</param>
+        </member>
+        <member name="M:PolyMigrate.Core.Pairing.HreflangRow.#ctor(System.String,System.String,System.String,System.String,System.Boolean,System.Boolean,System.Boolean,System.String)">
+            <summary>
+            <c>hreflang_map.csv</c> 的一列:一則宣告,加上它經不經得起查證。
+            </summary>
+            <param name="InMirror">目標頁在鏡像裡(同 host、且該路由真的抽到過一頁)。</param>
+            <param name="Reciprocal">目標頁也宣告了一則指回來的 hreflang。</param>
+            <param name="Usable">通過全部門檻,可用於配對(不代表一定產生了建議)。</param>
+            <param name="RejectReason">不可用的原因,見 <see cref="T:PolyMigrate.Core.Pairing.HreflangIndex"/> 的常數;可用時為空字串。</param>
+        </member>
+        <member name="P:PolyMigrate.Core.Pairing.HreflangRow.InMirror">
+            <summary>目標頁在鏡像裡(同 host、且該路由真的抽到過一頁)。</summary>
+        </member>
+        <member name="P:PolyMigrate.Core.Pairing.HreflangRow.Reciprocal">
+            <summary>目標頁也宣告了一則指回來的 hreflang。</summary>
+        </member>
+        <member name="P:PolyMigrate.Core.Pairing.HreflangRow.Usable">
+            <summary>通過全部門檻,可用於配對(不代表一定產生了建議)。</summary>
+        </member>
+        <member name="P:PolyMigrate.Core.Pairing.HreflangRow.RejectReason">
+            <summary>不可用的原因,見 <see cref="T:PolyMigrate.Core.Pairing.HreflangIndex"/> 的常數;可用時為空字串。</summary>
+        </member>
+        <member name="T:PolyMigrate.Core.Pairing.HreflangIndex">
+             <summary>
+             把各頁宣告的 hreflang 解析成「哪個 translation_key 是哪個 key 的哪一語言版本」(§1.4)。
+            
+             <para>hreflang 是全站唯一由作者<b>宣告</b>的配對關係——其餘線索(對稱路徑、共用相簿、
+             slug 日期、標題相似度)都是工具推測出來的。但「宣告的」不等於「對的」:舊站的 hreflang
+             多半是後來 SEO 外包加的,壞掉的比對的多。所以一則宣告要能用於配對,必須通過
+             <see cref="M:PolyMigrate.Core.Pairing.HreflangIndex.RejectReason(PolyMigrate.Core.Inventory.HreflangLink,System.String)"/> 與 <see cref="F:PolyMigrate.Core.Pairing.HreflangIndex.AmbiguousTarget"/> 列出的每一道門——
+             那幾個常數就是門檻的唯一事實來源,不可用的原因也照實輸出到 <c>reject_reason</c> 欄,
+             讓「這個站的 hreflang 能不能信」有資料可答,而不是只有一個總數。</para>
+            
+             <para>刻意<b>不</b>要求互指:互指是可信度的加分,不是門檻——單向 hreflang 在真實站上
+             太常見(常常只有預設語言那半宣告)。互指與否照實記在 <c>reciprocal</c> 欄,由人判斷。
+             這一層只「建議」不合併,守門標準本來就該比直接覆寫 translation_key 寬。</para>
+            
+             <para>「為什麼不乾脆用 hreflang 直接覆寫 translation_key」是這個檔案最常被問的問題,
+             答案(含量測數字與重啟條件)在 <c>docs/hreflang_量測與決策.md</c>——
+             那是刻意的決定,不是還沒做完。</para>
+             </summary>
+        </member>
+        <member name="F:PolyMigrate.Core.Pairing.HreflangIndex.XDefault">
+            <summary>「以上皆非時去這裡」的特例值,不是語言(RFC 8288 / Google 定義)。</summary>
+        </member>
+        <member name="F:PolyMigrate.Core.Pairing.HreflangIndex.NotInMirror">
+            <summary>目標頁不在鏡像裡:指到別的 host,或指到一個原站早就下架的 URL。</summary>
+        </member>
+        <member name="F:PolyMigrate.Core.Pairing.HreflangIndex.IsXDefault">
+            <summary><c>x-default</c> 不是某個語言版本,是「都不符合時去哪」。</summary>
+        </member>
+        <member name="F:PolyMigrate.Core.Pairing.HreflangIndex.SelfReference">
+            <summary>指向自己。自我指涉是標準做法,但配對上零資訊。</summary>
+        </member>
+        <member name="F:PolyMigrate.Core.Pairing.HreflangIndex.SiteLevel">
+            <summary>兩端任一是站級頁(<c>/</c> 開頭的 key,如語言選擇頁)——它不是誰的翻譯。</summary>
+        </member>
+        <member name="F:PolyMigrate.Core.Pairing.HreflangIndex.AmbiguousTarget">
+             <summary>
+             同一個目標頁被<b>多個同語言</b>的來源頁宣告為語言版本——一頁不可能是三頁的翻譯。
+            
+             <para>這是舊站最常見的壞法:SEO 外包把同一段 <c>&lt;link&gt;</c> 複製到每一頁的模板裡,
+             於是整站的 alternate 都指向首頁。少了這道門,那種站會產出「英文首頁 = 某篇中文新聞」
+             這種建議,而且掛著 hreflang 這個最權威的證據標籤,人最容易直接採信——
+             比誠實回報 missing 糟得多。</para>
+            
+             <para>限定「同語言」是因為多語站的合法情況長得很像:中文版與日文版可以<b>各自</b>
+             宣告同一個英文版(<c>ch → en</c>、<c>jp → en</c>),那是對的,不能一起擋掉。</para>
+             </summary>
+        </member>
+        <member name="P:PolyMigrate.Core.Pairing.HreflangIndex.Rows">
+            <summary>全部宣告,含不可用的;排序 = 來源 URL、hreflang、目標 URL(ordinal)。</summary>
+        </member>
+        <member name="P:PolyMigrate.Core.Pairing.HreflangIndex.AlternatesByKey">
+            <summary>可用宣告:來源 key → (目標 key → hreflang 值)。</summary>
+        </member>
+        <member name="M:PolyMigrate.Core.Pairing.HreflangIndex.RejectReason(PolyMigrate.Core.Inventory.HreflangLink,System.String)">
+            <summary>逐則就能判斷的門檻;null = 這一則自己沒問題(還要再過 ambiguous_target)。</summary>
+        </member>
         <member name="T:PolyMigrate.Core.Pairing.UnpairedGroup">
             <summary>配對建議的候選:只有單一語言版本的 translation_key(§1.4「配不起來的」)。</summary>
         </member>
+        <member name="P:PolyMigrate.Core.Pairing.UnpairedGroup.Alternates">
+            <summary>本組頁面宣告、且通過查證的 hreflang:目標 translation_key → hreflang 值
+            (見 <see cref="T:PolyMigrate.Core.Pairing.HreflangIndex"/>)。沒宣告 hreflang 的站是空的,這很常見。</summary>
+        </member>
         <member name="T:PolyMigrate.Core.Pairing.PairSuggestion">
             <summary>一筆建議:兩個互缺對方語言的 key,附證據(如 shared_media=3)。</summary>
         </member>
@@ -705,9 +888,31 @@
         <member name="M:PolyMigrate.Core.Pairing.PairingSuggester.Evaluate(PolyMigrate.Core.Pairing.UnpairedGroup,PolyMigrate.Core.Pairing.UnpairedGroup)">
             <summary>回傳命中的證據(依 fallback 順序);空 = 無任何依據,不建議。</summary>
         </member>
+        <member name="M:PolyMigrate.Core.Pairing.PairingSuggester.HreflangToken(PolyMigrate.Core.Pairing.UnpairedGroup,PolyMigrate.Core.Pairing.UnpairedGroup)">
+            <summary>
+            兩端任一方宣告了指向對方的 hreflang → 回那個 hreflang 值,否則 null。
+            <c>pairing.fallback</c> 沒列 hreflang 時一律回 null,行為與加這個啟發式之前逐位元相同。
+            </summary>
+        </member>
         <member name="M:PolyMigrate.Core.Pairing.PairingSuggester.Score(System.Collections.Generic.List{System.Collections.Generic.KeyValuePair{System.String,System.String}})">
             <summary>排序分數:fallback 越前面的證據權重越高;shared_media 另以數量加細分。</summary>
         </member>
+        <member name="M:PolyMigrate.Core.Pairing.PairingSuggester.NormalizeSlug(System.String)">
+             <summary>
+             slug 去分隔符與大小寫。<c>2025-light-offering</c> 與 <c>2025_light_offering</c>
+             都變成 <c>2025lightoffering</c>。
+            
+             <para>這<b>不是</b>「URL 字串相似度」——那個做法配的是
+             <c>/products/</c> 與 <c>/produkte/</c>,不同語言的同一個意思字面上根本不像,
+             純粹在猜。這裡要求正規化後<b>完全相等</b>,配的是同一個字被兩邊打成不同寫法,
+             可靠度與「去語言前綴後路徑相等」同級。</para>
+            
+             <para>實際來源:香雲寺站的光明燈法會,中文 <c>2025-light-offering</c>、
+             英文 <c>2025_light_offering</c>,只差一個分隔符,而其餘三個啟發式全部落空——
+             圖是同一張的兩份拷貝各放自己語言目錄(shared_media 不成立)、slug 無日期、
+             標題一中一英(相似度 0)。</para>
+             </summary>
+        </member>
         <member name="M:PolyMigrate.Core.Pairing.PairingSuggester.BigramDice(System.String,System.String)">
             <summary>Sørensen–Dice 字元 bigram 相似度(0..1),不分大小寫。</summary>
         </member>

package/bin/polymigrate.deps.json

@@ -7,10 +7,10 @@
   "targets": {
     ".NETCoreApp,Version=v10.0": {},
     ".NETCoreApp,Version=v10.0/osx-x64": {
-      "polymigrate/2.2.1": {
+      "polymigrate/2.3.1": {
         "dependencies": {
-          "Cornhsu.PolyMigrate.Core": "2.2.1",
-          "PolyMigrate.Core": "2.2.1.0",
+          "Cornhsu.PolyMigrate.Core": "2.3.1",
+          "PolyMigrate.Core": "2.3.1.0",
           "runtimepack.Microsoft.NETCore.App.Runtime.osx-x64": "10.0.11"
         },
         "runtime": {
@@ -804,7 +804,7 @@
           }
         }
       },
-      "Cornhsu.PolyMigrate.Core/2.2.1": {
+      "Cornhsu.PolyMigrate.Core/2.3.1": {
         "dependencies": {
           "AngleSharp": "1.7.1",
           "Magick.NET-Q8-AnyCPU": "14.16.0",
@@ -813,23 +813,23 @@
         },
         "runtime": {
           "PolyMigrate.Core.dll": {
-            "assemblyVersion": "2.2.1.0",
-            "fileVersion": "2.2.1.0"
+            "assemblyVersion": "2.3.1.0",
+            "fileVersion": "2.3.1.0"
           }
         }
       },
-      "PolyMigrate.Core/2.2.1.0": {
+      "PolyMigrate.Core/2.3.1.0": {
         "runtime": {
           "PolyMigrate.Core.dll": {
-            "assemblyVersion": "2.2.1.0",
-            "fileVersion": "2.2.1.0"
+            "assemblyVersion": "2.3.1.0",
+            "fileVersion": "2.3.1.0"
           }
         }
       }
     }
   },
   "libraries": {
-    "polymigrate/2.2.1": {
+    "polymigrate/2.3.1": {
       "type": "project",
       "serviceable": false,
       "sha512": ""
@@ -874,12 +874,12 @@
       "path": "yamldotnet/18.1.0",
       "hashPath": "yamldotnet.18.1.0.nupkg.sha512"
     },
-    "Cornhsu.PolyMigrate.Core/2.2.1": {
+    "Cornhsu.PolyMigrate.Core/2.3.1": {
       "type": "project",
       "serviceable": false,
       "sha512": ""
     },
-    "PolyMigrate.Core/2.2.1.0": {
+    "PolyMigrate.Core/2.3.1.0": {
       "type": "reference",
       "serviceable": false,
       "sha512": ""

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cornhsu/polymigrate-darwin-x64",
-  "version": "2.2.1",
+  "version": "2.3.1",
   "description": "The darwin-x64 binary for Cornhsu.PolyMigrate. Install cornhsu-polymigrate instead — do not depend on this package directly.",
   "homepage": "https://cornhsu.com/polymigrate",
   "repository": {