PolyMigrate

i18n-first静态站点迁移器 -唯一的网站迁移，配对您的多语言页面自动。

帐面价值的项目 · NuGet · 繁體中文說明 ·麻省理工学院

PolyMigrate将遗留的动态站点（旧的PHP站点等）转换为干净的静态站点 Markdown——它将多语言内容视为头等大事，而不是事后才想到的。 配置驱动，完全脱机可运行，构建在。net上。

状态:3.0。 提取管道、配对、验证、缩略图和孤儿页面 完成恢复，并根据真正的全站点迁移进行验证（见下文）。这个 CLI 表面、退出代码、阶段输出合同和YAML配置被冻结在一个主版本中： 新功能会对小版本产生影响，修复会对补丁产生影响，任何改变其中一个的东西都会产生影响 四面等待少校。 3.0就是这样一个版本 -在某些情况下它会改变退出代码 所以他们遵循0 / 1 / 2 / 130契约(一个孤儿探针，没有可用的答案，一个失败的 NPM启动器和一个中断的命令不再看起来像成功)，给每个部分自己的 孤儿蛞蝓名单(orphan_slugs.<section>.txt)，保持动画GIF/WebP缩略图动画，和 向库中添加探测/获取入口点和可取消的重载。配置字段、CSV列 和前文字段是不变的，但配置与一个无效的值(一个CSS选择器，一个正则表达式，一个 不是单个段的路径，格式错误的URL或语言标记，没有值的键…) 当它被每个命令加载时被拒绝，而不是在某个页面或命令碰巧使用它时被拒绝 只有一些候选人没有答案（列表是书面的，但可能不完整）。 升级前请阅读CHANGELOG中的3.0升级清单。 早期历史：2.0是一个工程版本——它缩小了 Cornhsu.PolyMigrate.Core 公众。. NET API的预期入口点，并删除未使用 配置字段;2.1修复了发布管道（arm64 NPM包，符号包） npm启动器只能启动2.3.1以后的Windows/Linux arm64版本。 封闭了一个盲区 verify -没有链接的页面被报告为良好，因为a 链接跟踪审计从未到达它们-并添加 slugs 跟踪源站点 这还在更新中。 升级到2.2可以改变一个传球 verify 进入1号出口。 2.3读取源站点自己的 hreflang 声明（见下文），并在新的 hreflang_map.csv． 看到 更新日志 查看迁移说明。

为什么

每个多语种机构网站（政府、大学、非政府组织、宗教组织） 面临着同样痛苦的迁移步骤：手动匹配每个页面的语言版本。 没有现有的工具可以解决这个问题——通用的抓取器每次提取一个页面，然后离开 配对给你。PolyMigrate:

• 对自动 其中文件名是对称的(/ch/news/x ↔ /en/news/x 共享一个 translation_key)，
• 阅读网站自己的内容 hreflang 声明 - - - - - - <link rel="alternate" hreflang> 就是那个 配对标志着网站的作者 声明 而不是工具推断出来的东西 先试过，可以跨部分配对(/ch/news/ ↔ /en/press/)，
• 启发式建议配对 两者都不适用的情况-仅在分离器上不同的鼻涕虫 （2025-light-offering vs 2025_light_offering)，共享相册，隐藏规范化日期 在蛞蝓(20240121 vs 01212024)、标题相似度；
• 诚实地报告它不能配对的东西，生成一个评审就绪的差距清单，而不是 猜错了。

注意PolyMigrate故意做了什么 不 是否：通过URL字符串匹配语言版本 相似点。 /products/， /produkte/ 和 /產品/ 相似度为0并且是相同的 页面;对称路径配对是去掉语言前缀后的精确匹配，而不是 模糊的一个。

语言不限于两个：声明任何数字 lang_map 每个输出 （frontmatter, inventory, pair）也随之扩大。所有语言环境输出都是标准的BCP-47。

关于 hreflang

遗留站点就是那些具有以下特性的站点 hreflang 是缺失还是错误——通常是由 几年后成为SEO承包商所以PolyMigrate把它当作有力的证据，而不是福音。 声明仅用于配对，如果它：

• 不是 x-default （这是“当没有匹配的时候去哪里”，不是语言版本），
• 并不指向页面本身，
• 解析到实际在您的镜像中的页面 包含同一主机，因为很多网站把 英文版本为 en.example.org，其中仅路径比较将使页面成为其 自己的翻译,
• 两端都有内容页——两端都不是站点级页面(语言选择器和 比如，这不是任何人的翻译)，
• 和 并不是许多相同语言的页面声称同一目标之一． 这是经典的 失败:一个 <link> 粘贴到站点范围的模板中，因此每个中文页面都声明 英文主页作为其英文版。一页不能翻译另外三页， 因此，所有这些要求都被放弃了，而不是变成了看起来自信的错误组合。

所有声明的内容——包括被拒绝的内容——都被写入 hreflang_map.csv 与 in_mirror / reciprocal / usable 和一个 reject_reason 命名失败的规则，因为 “我能相信这个网站的hreflang吗？”是一个你想用数据而不是总数来回答的问题。

对仍然只有永远 建议： hreflang 提高证据质量，却没有 将该工具切换为自己合并页面。这是一个深思熟虑的决定，而不是一个未完成的决定 一是它背后的测量，以及需要改变什么才能重新审视它，这些都被记录下来 doc /hreflang_。

一些久经沙场的违约

提取管道包含在实际迁移过程中发现的实际问题的修复程序 通用工具和LLM提取器会悄悄地出错：

案例研究：完整的寺庙站点迁移

PolyMigrate的管道是完成实际迁移的产品化版本 （中英双语佛寺网站）：

• 516页 镜像和提取， 4.6 GB 的媒体
• 281个翻译键； 231篇双语文章自动配对 通过对称路径
• 内置验证器: 检查了1,269个内部链接+ 4,116个媒体引用- 0错误
• 通过日期探测回收了13件孤儿物品；141张exif旋转照片固定在缩略图中

最初的Python原型的输出被用作移植时的黄金基线：466/516 提取的正文在空格归一化后是字节相同的，其余部分是 渲染等效或严格地更忠实。

还有两个数字：

• 重新运行速度快了7倍：媒体哈希被缓存 (size, mtime)进行了一次完整的重跑 4.6 GB的站点 从30.1秒下降到4.6秒。
• 输出可以按原样部署： redirect_map 自动填充新路径，和 PolyMigrate同时发射两个 nginx相依 和一个 Netlify _redirects 锉刀 花了半天手写的301来复制一个文件。

安装使用

两个通道-选择您已经拥有的运行时。 同样的工具，同样的行为。

npx cornhsu-polymigrate extract site.yaml   # Node — no .NET install needed
dotnet tool install -g Cornhsu.PolyMigrate  # .NET 10

npm构建附带了一个独立的本机二进制文件，并且只下载其中一个 匹配您的平台（win32 / Linux / darwin，每个都是x64和arm64）。 一个例外: thumbs 不能在Intel mac （darwin-x64）上运行，因为Magick。净15, 它背后的图像库，不再为他们提供构建；它退出时有一个解释。 所有其他命令都在那里工作；在英特尔Mac上使用缩略图，请使用3.0.x。 迁移站点通常是一次性的工作——为一个站点安装整个SDK 跑步是大多数人无法接受的摩擦，所以工具会满足你的需求。

dotnet tool install -g Cornhsu.PolyMigrate
polymigrate extract site.yaml               # mirror HTML -> frontmatter Markdown + inventories
polymigrate verify .                        # link/media/frontmatter/unlinked-page audit, CI exit codes
polymigrate thumbs site.yaml                # EXIF-corrected, width-capped thumbnails
polymigrate probe-orphans site.yaml --section news --years 2021-2023   # -> orphan_slugs.news.txt
polymigrate fetch-orphans site.yaml --section news                      # reads orphan_slugs.news.txt
polymigrate slugs . --section news          # slugs already mirrored under ./raw (pipeable)

动画GIF/WebP缩略图保持每帧-在限制内。 缩放动画帧 帧消耗的内存和时间与帧×宽×高成比例（测量：400帧） 1300×900 GIF花了39秒和3.2 GB)。动画结束 50个像素 总的来说，或一个 动画缩略图会比原来的大，得到的是第一帧缩略图 与3.0之前的结果相同（不需要缩放的动画会按原样复制）。在极限情况下，它需要大约6秒和250 - 400mb的内存峰值，具体取决于内容 （两个100帧1000×500动图分别为250 MB和384 MB）。这个 thumbs 摘要列表 哪些文件有第一帧，为什么；这两种情况都不是失败或更改退出代码。 静止图像也有限制：1 / 1 179像素 (枕头的减压炸弹阈值- 一个270kb的GIF可以声明20000×20000，解码它需要14.8秒和1.6 GB)根本无法解码 作为一个失败的缩略图（出口1）。1亿像素的相机原件很好。

raw/ 是你无法重生的东西。 重新爬取一个网站一次需要几个小时 礼貌的请求率，并且源站点可能在您完成的那一刻被关闭 迁移——此时你的镜像是唯一剩下的副本。无PolyMigrate命令 永远删除或覆盖 raw/ 或 media/;保留它们，直到对迁移进行签名 关掉，如果源消失，备份它们。

没有。net ?上面的每个命令也运行 零安装 通过NPM -只需加上前缀： npx cornhsu-polymigrate extract site.yaml， npx cornhsu-polymigrate verify .等等。

每个站点一个YAML配置描述所有与站点相关的内容——参见 例子/ ibps-austin.yaml 对于一个完全注释的实际示例。

config_version: 1
site:
  base_url: https://legacy.example.org
url_pattern:
  lang_map: { ch: zh-Hant, en: en }     # any number of languages
  default_lang: zh-Hant
  strip_extensions: [.php]
extract:
  content: "section[id]:not(#header):not(#footer)"
pairing:
  fallback: [hreflang, slug_normalized, shared_media, date, title_similarity]

用作库

CLI是一层薄薄的外壳 Cornhsu.PolyMigrate.Core． 来驱动你自己的迁移 ．. NET代码，使用 PolyMigrator 外观-单一文档化入口点：

dotnet add package Cornhsu.PolyMigrate.Core

using PolyMigrate.Core;

var migrator = PolyMigrator.FromConfigFile("site.yaml");
var report = migrator.Extract("out/");        // out/raw, out/media -> out/content + inventories
if (report.HasErrors) { /* unsafe paths were skipped; see path_issues.csv */ }

var verify = PolyMigrator.Verify("out/");      // no config needed; reads Phase 2 output only
Console.WriteLine($"{verify.Errors} errors, {verify.Warnings} warnings");

// Orphan pages (probe-orphans / fetch-orphans). Nothing is written until you decide to.
var probe = await migrator.ProbeOrphansAsync("out/", "news", 2021, 2023);
if (probe.NoUsableAnswers) { /* the site never answered: an empty list means nothing */ }
else { await migrator.FetchOrphansAsync("out/", "news", probe.Found); }

Extract， Verify和GenerateThumbnails也有重载 CancellationToken （探测/获取方法将一个作为最后一个参数）。

布局

发展

dotnet build
dotnet test
dotnet run --project src/PolyMigrate.Cli -- --help

看到也

多語言網站搬遷最容易搬丟的東西 （繁体中文）-范畴的背景，而不是这个工具：五配对 信号按优先顺序排列，为什么“刚读” hreflang“经常错过真正的遗产网站 (一页528页， 0 声明（sitemap 404），声明必须通过的五道门 在它可用之前传递，以及为什么URL字符串相似性是这个工作的错误工具。

许可: 麻省理工学院． 所有依赖是MIT/BSD/Apache-2.0 (成像通过 魔法。网;imagessharp在4岁时被删除。X线开始需要a 构建时的许可密钥)。看到 THIRD-PARTY-NOTICES。

PolyMigrate从您指向的站点获取页面，并且可以配置为发送 饼干通过机器人挑战。 它假定站点是您的，或者您正在进行迁移 得到了业主的许可 ——这就是它的作用。检查源站点的条款 然后再指着别的东西。