迁移到当前版本的 CLI
替换旧版存储桶和源内容指纹,同时保留已确认的译文,确保应用正常运行。
当前版本的 @lingo.dev/cli 使用服务端推送/拉取任务和 .lingo 项目状态。旧版 lingo.dev 软件包则使用本地存储桶处理、i18n.json 和 i18n.lock。迁移不只是更改命令名称,更要保留项目所需的行为。
保留正常运行的初始状态 #
记录已安装的版本,并将源文件、已确认的目标文件、配置和旧版 Lockfile 保存在版本控制中。确认应用能够加载这些目标文件。在限定范围内的替代方案验证可用之前,保留现有本地化配置中的路由器、提供器、语言切换器和翻译目录加载器。
记录框架和运行时版本,以及所需的源语言区域、目标语言区域和默认语言区域。测试有代表性的带语言区域前缀的路由、初始检测、回退和语言切换。将这些应用层面的检查与文件翻译迁移分开进行。
重建文件选择配置 #
创建 .lingo/config.json,设置源语言区域、目标语言区域和明确的文件条目,然后关联你有权访问的组织和本地化引擎。旧版存储桶和指纹无法仅通过重命名转换为这种配置结构。
当前 CLI 配置支持 22 种格式,包括 HTML(.html 和 .htm)、纯文本(.txt,与 v0 一样,每行一个单元)、在同一文件中用不同列存放各语言区域内容的 CSV 表格,以及 Java .properties 文件(与 v0 一样,每个键对应一个单元,lockedKeys、preservedKeys 和 ignoredKeys 的匹配方式也与 v0 相同;lockedPatterns 使用 RE2 语法,不支持环视或反向引用)。迁移 v0 的 csv 存储桶文件前,请对照 CSV 布局检查文件。请对照 Java 属性文件检查 v0 的 properties 存储桶路径:例如,messages_[locale].properties 这样的 [locale] 文件名会转换为 messages_en.properties 这样的源文件匹配模式。每个语言区域单独使用一个 CSV 文件的存储桶、MJML 存储桶,以及其他仅旧版支持的存储桶,都需要经过验证的转换方案或其他翻译途径。配置中列出了准确的枚举值、匹配器和输出模板。v0 中用于直连提供商的模型、提示词和基础 URL 设置不适用于此项目的配置结构。
扩大配置范围前,先检查一个选定的源文件及其推导出的目标路径。对于 Markdown 系列格式的属性,请使用 translateComponentProps。
接纳并更新译文 #
当前的限定范围规划和初始化规划可以接纳现有目标文件。建立基线前,请检查有代表性的文件和人工编辑内容:文件存在,并不代表其中的值与最新源内容一致。
回填会补齐缺失的普通文件,而 v0 通常会补齐现有翻译目录中缺失的键。后续这类工作应使用当前的增量源内容更新或受支持的键刷新功能。即使文本与旧键相同,重命名后的 JSON 键仍会被视为基于新路径的任务;不要依赖 v0 基于内容指纹的重命名复用机制。
增量处理时,可以保留对未变更键的目标内容所做的编辑。显式的保留键规则还提供了独立的内容归属选择。对于源文件与目标文件分开存储的格式,整文件强制处理会移除当前目标内容的上下文,并可能替换已确认的措辞,因此不能将其作为接纳现有译文的捷径。
完成当前版本的首次运行 #
按照当前版本快速入门指南完成回填和文件拉取。在没有基线的情况下直接执行首次推送,只会存储源文件字节,不会请求初始翻译。请等待或执行拉取,再将文件工作流视为完成。
将已接受的源文件、目标文件、配置和当前 Lockfile 一并提交。最新运行指针仍保留在本机用户主目录中,不会通过 Git 同步。后续拉取时会比较哈希值;仅提交有分歧的修改并不能解决冲突。lingo check 在文件层面取代了原有的冻结 Lockfile 检查:如果源文件自 .lingo/lock.json 以来发生变化,或目标文件缺失,检查就会失败;它也不会在 Lockfile 缺失时创建该文件。如果没有已提交的 Lockfile,它就无法检测源文件的变化,只会检查目标文件是否存在。
React 迁移 #
当前 React 工作流会将包含源内容和上下文字面量的调用提取为 JSONC 和声明,翻译选定的翻译目录,再加载运行时字符串映射。扩大变更范围前,先验证一个组件的回退、变量、语言区域切换和已确认的措辞。
请参阅迁移现有 React 消息和 React,完成对应软件包的迁移工作。随包附带的 lingo guide migrate 反映的是已安装版本,并不代表它与此前生成的所有配置完全一致。