为remotely-save插件贡献多语言支持：从入门到实践的贡献指南

一、为什么需要多语言支持

在全球化开源社区中，多语言支持是项目国际化的核心环节。remotely-save作为一款Obsidian同步插件，通过支持多种云服务帮助用户在本地与云端之间无缝同步知识库。为其添加多语言支持，不仅能消除非英语用户的使用障碍，还能显著扩大项目的用户覆盖范围，同时为开发者提供参与开源协作的宝贵机会。

二、多语言文件结构解析

remotely-save采用分层结构管理语言文件，确保核心功能与专业版功能的翻译独立维护：

2.1 核心模块语言文件

• src/langs/en.json：英语基准翻译文件，包含所有界面文本的原始定义
• src/langs/zh_cn.json：简体中文翻译
• src/langs/zh_tw.json：繁体中文翻译

2.2 专业版模块语言文件

• pro/src/langs/en.json：专业版功能的英语翻译
• pro/src/langs/zh_cn.json：专业版功能的简体中文翻译
• pro/src/langs/zh_tw.json：专业版功能的繁体中文翻译

所有语言文件均采用JSON键值对格式，通过统一的键名实现不同语言间的内容映射。

三、贡献多语言支持的步骤

3.1 准备工作

首先克隆项目仓库到本地环境：

git clone https://gitcode.com/gh_mirrors/re/remotely-save
cd remotely-save

3.2 创建语言文件

在对应模块的langs目录下创建新的语言文件，命名格式为[语言代码].json，例如：

• 法语：fr.json
• 德语：de.json
• 日语：ja.json

3.3 翻译内容规范

翻译文件需保持与英语基准文件相同的键结构，示例格式如下：

{
  "settings_title": "设置",
  "sync_start": "开始同步",
  "sync_complete": "同步完成",
  "sync_error": "同步错误：{{errorMessage}}"
}

3.4 注册新语言

修改对应模块的langs/index.ts文件，导入新创建的语言文件并添加到导出对象：

import fr from "./fr.json";

export const LANGS = {
  en: en,
  zh_cn: zh_cn,
  zh_tw: zh_tw,
  fr: fr  // 新增语言
};

3.5 测试与验证

完成翻译后，建议进行以下验证：

1. 检查是否所有键都已正确翻译
2. 验证变量占位符（如{{variable}}）是否保留
3. 测试UI显示效果，确保文本长度适合界面布局

四、翻译最佳实践

4.1 术语一致性

• 建立专业术语表，确保技术术语翻译统一
• 参考现有翻译文件保持风格一致
• 关键功能名称建议保留英文或找到公认的译法

4.2 上下文适配

• 理解每个文本在界面中的实际使用场景
• 考虑不同语言的表达习惯，避免直译导致的语义偏差
• 确保错误提示和操作说明清晰易懂

4.3 技术细节处理

• 保留所有变量占位符，不得修改或删除
• 注意标点符号和格式的语言特异性
• 长文本需考虑换行和截断显示效果

五、国际化技术实现原理

remotely-save的国际化系统通过src/i18n.ts实现核心功能，主要机制包括：

1. 语言检测：自动根据用户系统语言设置选择匹配的翻译文件
2. 回退机制：当特定语言缺少某些键时，自动使用英语基准文本
3. 动态切换：支持在运行时切换语言并即时更新界面显示

翻译系统采用模块化设计，核心模块与专业版模块的翻译逻辑相互独立，确保功能扩展时的灵活性。

六、贡献提交流程

6.1 代码提交规范

• 创建特性分支：git checkout -b feature/add-[language]-translation
• 提交格式：feat(i18n): add [language] translation
• 确保只包含语言文件相关的更改

6.2 Pull Request 要求

• 标题格式：[i18n] Add [Language] translation
• 描述中说明翻译语言、覆盖范围及测试情况
• 确保所有文件格式正确，无语法错误

七、常见问题解答

Q1: 如何处理翻译过程中不确定的术语？

A1: 建议先参考项目现有翻译，或在GitHub讨论区提问确认。对于专业术语，可考虑保留英文原词并在括号中添加解释。

Q2: 发现现有翻译不准确或过时怎么办？

A2: 可以直接创建PR修正现有翻译，标题格式建议使用fix(i18n): correct [language] translation for [key]。

Q3: 如何测试我的翻译在实际界面中的效果？

A3: 你需要搭建本地开发环境，具体步骤可参考项目README中的开发指南。对于简单测试，也可以使用JSON验证工具检查文件格式正确性。

八、学习资源与参考

• 官方文档：项目根目录下的docs/文件夹包含详细开发指南
• 翻译示例：可参考src/langs/zh_cn.json了解翻译风格
• 社区支持：通过项目issue系统获取翻译相关帮助

九、总结与鼓励

为开源项目贡献多语言支持是参与全球协作的绝佳方式。你的每一个翻译贡献，都能帮助更多用户跨越语言障碍，享受remotely-save带来的同步便利。无论你是翻译新手还是经验丰富的国际化开发者，我们都欢迎你加入贡献者行列，共同打造更包容、更全球化的开源产品。

开源的力量在于社区的多样性，你的参与将让这个项目走得更远。立即行动，为remotely-save添加你熟悉的语言支持吧！