Tolgee平台本地开发环境搭建指南
前言
Tolgee是一个开源的本地化平台，为开发者提供便捷的国际化解决方案。本文将详细介绍如何在本地搭建Tolgee平台的开发环境，帮助开发者快速上手项目开发工作。
环境准备
在开始之前，请确保你的开发机器已安装以下必备软件：
- Java 21：Tolgee后端基于Java开发，需要JDK 21或更高版本
- Docker：用于运行数据库等依赖服务
- Node.js 18+：前端开发需要Node.js环境
- Intellij Idea（可选）：推荐使用这款IDE进行Java/Kotlin开发
项目初始化
获取项目代码是开发的第一步。使用以下命令克隆项目仓库（注意使用--depth=1参数可以只克隆最新提交，节省时间和空间）：
git clone --depth 1 <项目仓库地址>
启动开发环境
Tolgee平台采用前后端分离架构，需要分别启动后端和前端服务。
后端服务启动
有两种启动方式：
- 使用Intellij Idea：直接运行预配置的"Backend localhost"运行配置
- 命令行启动：
./gradlew server-app:bootRun --args='--spring.profiles.active=dev'
前端服务启动
同样有两种方式：
- 使用Intellij Idea：运行"Frontend localhost"配置
- 命令行启动：
cd webapp && npm ci && npm run start
启动完成后，在浏览器中访问http://localhost:3000即可看到Tolgee平台的界面。
测试相关
后端测试
后端测试包括单元测试和集成测试：
./gradlew test
也可以在IDE中直接运行单个测试用例。
端到端测试
端到端测试需要额外配置，具体可参考项目中的E2E测试文档。
后端配置
开发环境下，可以通过创建backend/app/src/main/resources/application-dev.yaml文件来覆盖默认配置。以下是一些常用配置示例：
spring:
jpa:
show-sql: true # 显示SQL语句，方便调试
tolgee:
front-end-url: http://localhost:3000 # 前端地址
file-storage-url: http://localhost:8080 # 文件存储地址
Spring Boot会根据激活的profile（这里是dev）加载对应的配置文件。
数据库迁移管理
Tolgee使用Liquibase进行数据库版本管理。要生成数据库变更日志，可运行：
./gradlew diffChangeLog
常见问题：
- 命令名称必须为diffChangeLog（注意大写L）
- 如果遇到Docker命令找不到的问题，可以尝试禁用Gradle守护进程：
./gradlew diffChangeLog --no-daemon
代码静态分析
前端代码检查
提交代码前建议运行以下检查：
cd webapp
npm run prettier # 代码格式化
npm run tsc # TypeScript类型检查
npm run eslint # 代码质量检查
也可以配置IDE插件自动完成这些检查。
后端代码检查
Kotlin代码格式化：
./gradlew ktlintFormat
使用Tolgee应用中的翻译
如果你有Tolgee应用的访问权限，可以创建webapp/.env.development.local文件来使用应用中的翻译资源：
VITE_APP_TOLGEE_API_URL=https://app.tolgee.io
VITE_APP_TOLGEE_API_KEY=你的API密钥
常见问题排查
MacOS下Gradle命令找不到
在Mac上运行E2E测试时，可能会遇到命令找不到的问题。这是因为IDEA启动Gradle守护进程时路径设置不正确。解决方法：
pkill -f '.*GradleDaemon.*' # 终止现有守护进程
open -a 'IntelliJ IDEA Ultimate' # 从终端启动IDEA
这样IDEA会继承终端的正确环境变量，Gradle守护进程也能正确启动。
结语
本文详细介绍了Tolgee平台的本地开发环境搭建流程，涵盖了从环境准备到项目启动、测试、配置管理等各个方面。希望这些信息能帮助你顺利开始Tolgee平台的开发工作。如果在使用过程中遇到其他问题，可以参考项目文档或社区讨论。
