国际化库渐进迁移与一致性验证
为项目制定国际化库迁移方案,生成适配层和转换脚本,并验证多语言输出一致性。
完整提示词
<context>
i18n migrations fail in two ways: a big-bang rewrite that breaks hundreds of strings in languages nobody on the team reads, and a conversion that changes keys, so the translation tool sees every message as new and translators are asked to redo work. The safe path keeps keys stable, converts message syntax mechanically with a real parser on both sides (i18next double-brace interpolation and `_one`/`_other` suffix keys become one ICU `{count, plural, ...}` message; gettext source-text keys need a key map), routes all call sites through a thin adapter so old and new libraries can run side by side during the transition, rewrites call sites with a codemod based on the syntax tree rather than search and replace, and proves parity by rendering every message in every locale with representative arguments through both libraries and diffing the output. Differences are expected in a few places (whitespace, number formatting defaults, escaping) and must be reviewed, not ignored.
</context>
<task>
Plan and start migrating from {{from_library}} to {{to_library}} in:
{{project}}
1. Run build, type check and tests and record the baseline. Stop and report if they fail.
2. Inventory: count call sites by API (translate function, component, hook, server helper), catalogs and keys per locale, message features in use (plurals, selects, nesting, references between messages, formatting, rich text), configuration (fallbacks, detection, loading), and integrations (extraction scripts, the translation tool's file format, CI checks).
3. Mapping: a table from each source feature to the target equivalent, and features with no direct equivalent that need a decision. Keys stay the same unless the target forbids their shape; if so, define a deterministic key map and confirm with the translation tool's owner that history can be kept.
4. Migration plan: an ordered, incremental plan (adapter first, catalogs converted by script, call sites migrated per area, old library removed last), with a checkpoint after each step. Present it and wait for confirmation before changing code.
5. Adapter: after confirmation, add a thin module exposing the API the app needs, backed by the old library, and route call sites through it where that is cheap.
6. Conversion: write a script that parses each source message with the source syntax's parser and emits the target syntax, never with regular expressions; convert catalogs for every locale, keeping comments and metadata the target format supports. Write the codemod for call sites using a syntax-tree tool, and run it on one area first.
7. Parity check: a script that renders every key in every locale with representative arguments (counts that hit each plural category, each select case, a date and a number) through both libraries and reports differences. Review each difference and classify it as expected or a bug.
8. Switch the first area to the new library behind the adapter, run build, type check, tests and parity, and report.
</task>
<constraints>
- No key renames without a deterministic map and confirmation.
- Do not remove the old library until parity is clean and every area is migrated.
- Do not hand-edit converted translations; fix the converter and rerun.
- Stop after the plan for confirmation, and after the first area for review.
{{> guardrails/scope-discipline}}
{{> guardrails/verify-before-done}}
</constraints>
<output_format>
## Baseline
Build, type check, tests and the inventory counts.
## Mapping
| Source feature | Target equivalent | Decision needed |
## Migration plan
Ordered steps with checkpoints.
## Adapter
The adapter module.
## Conversion
Catalog converter and codemod, with the first area's results.
## Parity check
The script and differences found, classified.
## Verification
Commands and results after the first area.
## Remaining work
Areas left, open decisions and removal criteria for the old library.
</output_format>可替换内容
- {{from_library}}
- {{to_library}}
- {{project}}
- {{> guardrails/scope-discipline}}
- {{> guardrails/verify-before-done}}
分类与标签
编程开发、国际化迁移、代码转换、适配层、回归验证