如何将git submodule集成到现有项目的git工作流中

核心原则 #

• 权限完全隔离：Weblate仅能访问翻译子模块独立仓库，无主项目权限
• 尽量减少开发者额外操作：普通翻译更新无需改动主项目代码
• 分支规则完全对齐现有主项目工作流，无额外学习成本

具体实施步骤 #

1. 翻译子模块初始化 #

首先把现有翻译文件夹抽离为独立git仓库，配置和主项目一致的分支规则：

• master分支：对应生产环境已上线的翻译内容
• develop分支：对应待发版的最新翻译内容
• 功能分支：分为两类，开发者新增翻译key用feature/xxx-新增翻译字段，Weblate自动生成的翻译更新用weblate/xxx-语言翻译更新

给Weblate仅开通子模块的功能分支推送权限，所有Weblate的提交必须走PR合并到develop分支，不能直接推送核心分支。

2. 主项目接入子模块 #

在主项目根目录执行命令将翻译目录替换为子模块：

# 先备份原有翻译文件，删除原目录后添加子模块
git submodule add <翻译子模块仓库地址> <原翻译文件夹路径>
git add .gitmodules <翻译文件夹路径>
git commit -m "feat: 接入翻译子模块"

配置团队成员本地git默认拉取子模块更新，避免出现翻译文件缺失的问题：

git config submodule.recurse true

3. 工作流适配规则 #

场景1：Weblate侧翻译人员更新译文

完全不需要操作主项目，流程如下：

1. 翻译人员在Weblate修改译文后，Weblate自动提交到子模块的weblate/前缀功能分支
2. 翻译负责人审核通过后合并到子模块develop分支
3. 配置CI定时任务：每小时检测子模块develop分支更新，自动给主项目develop分支提PR，更新子模块指向的commit hash
4. 主项目发版时会自动带上最新的翻译内容

场景2：开发者新增/修改翻译key

和现有工作流几乎一致，仅多一步子模块提交：

1. 开发者在主项目拉取feature/xxx功能分支，同时在子模块拉取同名feature/xxx分支
2. 新增翻译key写入子模块的对应翻译文件，业务代码正常调用翻译字段
3. 功能开发完成后，先提交子模块feature/xxx分支的改动，合并到子模块develop
4. 再更新主项目功能分支内的子模块commit引用，提交主项目PR合并到develop即可

常见问题规避 #

• 主项目所有核心分支（master/develop）引用的子模块commit必须是子模块对应核心分支中存在的commit，禁止引用未合并的功能分支commit，避免打包时找不到文件
• 成员本地拉取代码、切换分支时，统一使用git pull --recurse-submodules、git checkout --recurse-submodules命令，避免出现翻译文件版本不匹配的问题
• 子模块的master分支更新必须和主项目master分支发布同步，保证生产环境版本对应

内容的提问来源于stack exchange，提问作者Picopico