Tolgee多語系前端串接紀錄

紀錄tolgee服務已架設好後
後續串接前端專案
使用1: 專案git push > 撈取tolgee上最新語系 > commit紀錄語系更新 > 部屬到環境
使用2: new pipeline(gitlab build > pipelines) > 部屬到環境
編輯詞條的分工
| 動作 | 在哪裡做 | 原因 |
| 新增詞條(key) | 本地 JSON,經 git push 送上 Tolgee | key 跟著程式碼一起產生 |
| 修改既有文案 | 一律在 Tolgee 線上改 | 本地改既有值不會生效,下次同步會被線上內容蓋回 |
| 刪除詞條 | 程式移除後,到 Tolgee 手動刪 | 本地刪掉但線上還在,下次同步會被拉回來 |
創建專案

Tolgee設定語系 範例為設定了三種語系
tag需要與前端專案中json檔名一致
後面因應.tolgeerc設定裡的"format": “JSON_TOLGEE"需要調整設定
預設會是開啟狀態的,為了配合"format": “JSON_ICU"

本機設定
Tolgee CLI
先專案安裝Cli: npm install –save-dev @tolgee/cli
本機身分登入tolgee
終端機:
cd 專案網址
npx tolgee login --api-url https://tolgee伺服器位置 專案key(Project API keys來自Tolgee)
確認是否有成功是npx tolgee login –list
以及需要確保字典檔是JSON格式
建立 .tolgeerc
專案根目錄建立 .tolgeerc,內容如下。
{
"$schema": "https://docs.tolgee.io/cli-schema.json",
"projectId": 4,
"apiUrl": "tolgee伺服器url",
"format": "JSON_TOLGEE",
"pull": {
"path": "./src/i18n/langs",
"supportArrays": true,
"states": [
"TRANSLATED",
"REVIEWED",
"UNTRANSLATED"
]
},
"push": {
"files": [
{
"path": "./src/i18n/langs/zh-TW.json",
"language": "zh-TW"
},
{
"path": "./src/i18n/langs/en.json",
"language": "en"
},
{
"path": "./src/i18n/langs/ja.json",
"language": "ja"
}
],
"forceMode": "KEEP",
"convertPlaceholdersToIcu": false
}
}
註記:forceMode 一定要是 KEEP。它代表 push 時只新增線上沒有的詞條,既有詞條的值不動。若設成 OVERRIDE,本地的舊內容會蓋掉 PM 在線上改好的文案。
在 package.json 加上指令
在 scripts 區塊加入兩行,方便本地手動同步:
“i18n:pull": “tolgee pull",
“i18n:push": “tolgee push"
修改 .gitlab-ci.yml
共兩處修改。
第一處:在 workflow.rules 加一條,放行排程觸發的 pipeline(放在 – when: never 之前):
– if: '$CI_PIPELINE_SOURCE == “schedule"'
第二處:新增 sync_i18n job,放在 include: 之前:
sync_i18n:
stage: .pre
image: "$IMAGE_NAME"
tags: ["$RUNNER_TAG"]
rules:
- if: '$CI_COMMIT_TAG'
when: never
- if: '$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_MESSAGE =~ /^chore\(i18n\): sync from Tolgee/'
when: never
- if: '$CI_PIPELINE_SOURCE == "schedule"'
- if: '$CI_PIPELINE_SOURCE == "web" && $CI_COMMIT_BRANCH == $CONDITION_BRANCH'
- if: '$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == $CONDITION_BRANCH'
- when: never
script:
- ': "${TOLGEE_API_KEY:?為空。若為 Protected CI/CD Variable,請確認此 branch 已設為 protected}"'
- ': "${I18N_PUSH_TOKEN:?為空。若為 Protected CI/CD Variable,請確認此 branch 已設為 protected}"'
# 版本需與 package.json 的 @tolgee/cli 一致
- npx --yes @tolgee/[email protected] push
- npx --yes @tolgee/[email protected] pull
- git add src/i18n/langs
- |
if git diff --cached --quiet; then
echo "=== 語系無變更,不需 commit ==="
exit 0
fi
- git diff --cached --stat
- git config user.name "i18n-bot"
- git config user.email "[email protected]"
- 'git commit -m "chore(i18n): sync from Tolgee"'
- PUSH_OPT=""
- if [ "$CI_PIPELINE_SOURCE" = "push" ]; then PUSH_OPT="-o ci.skip"; fi
- git push $PUSH_OPT "${CI_SERVER_PROTOCOL}://oauth2:${I18N_PUSH_TOKEN}@${CI_SERVER_HOST}:${CI_SERVER_PORT}/${CI_PROJECT_PATH}.git" "HEAD:${CONDITION_BRANCH}"
artifacts:
paths:
- src/i18n/langs/
expire_in: 1 hour
這個 job 依序做三件事:把 git 上新增的詞條送上 Tolgee、把 Tolgee 最新內容拉回來、有差異就以 i18n-bot 的名義 commit 回 main。
初次測試
第一次要在本地把現有詞條送上 Tolgee,並確認拉回來的格式與本地一致。
npm run i18n:push
npm run i18n:pull
到tolgee伺服器端查看是否成功上傳了應對的語系檔

GitLab 設定
建立 Project Access Token

這個 token 讓 CI 能把語系 commit 推回 main。到專案的 Settings > Access tokens,按 Add new token:
| 欄位 | 填寫內容 |
| Token name | i18n-bot |
| Role | Maintainer |
| Scopes | 只勾 write_repository |
| Expiration date | 設定一個日期並記下來,過期後同步會失敗 |
建立後 token 只會顯示一次,請立刻複製,下一步要用。
取得 Tolgee API key
登入 Tolgee,進入該專案後建立一把專案 API key,權限需包含 keys 的檢視與新增,以及 translations 的檢視與編輯。
懶惰的話就直接開Admin
新增 CI/CD 變數
到 Settings > CI/CD > Variables,按 Add variable,新增兩個變數:
| Key | Value | 設定 |
| TOLGEE_API_KEY | 4.2 取得的 Tolgee API key | Masked and hidden;不勾 Expand variable reference |
| I18N_PUSH_TOKEN | 4.1 建立的 Access Token | Masked and hidden;不勾 Expand variable reference |

Protect variable:只有在 main 是 protected branch 時才可以勾。若 main 不是 protected branch 卻勾了,job 會拿不到變數而失敗。請與專案內其他變數(例如 DEPLOY_PATH)的設定保持一致。
確認 main 的 push 權限
到 Settings > Repository > Protected branches,查看 main 的 Allowed to push and merge:
• 若是 Maintainers:4.1 選了 Maintainer 就可以,不用再調整。
• 若是 No one:要把 i18n-bot 加進允許名單,否則 bot 的 commit 會被拒絕。
建立排程(選用,目前我沒用)
不建排程的話,Tolgee 的修改要等有人 push 到 main 或手動按 New pipeline 才會進 git。若希望定時自動同步,到 Build > Pipeline schedules 按 New schedule:
| 欄位 | 填寫內容 |
| Description | 例如「同步 Tolgee 語系並部署」 |
| Interval pattern | 例如 0 8,13 * * 1-5(平日 8 點與 13 點) |
| Cron timezone | Taipei |
| Target branch | main |
排程列表右側的播放鍵可以立即執行一次。排程觸發時只會跑 sync_i18n,有變更才會接著部署。
驗證設定是否成功
git有commit後
gitlab上Build>Pipelines查看任務狀態

#4063的任務有包含部屬, 有將i18n-bot建立的#4064更新的內容抓回來

日常操作
| 想做的事 | 做法 |
| 新增詞條 | 在三個語系的 JSON 加上新 key,commit 並 push 到 main。CI 會自動送上 Tolgee。 |
| 修改既有文案 | 到 Tolgee 線上修改。之後 push、手動 New pipeline 或排程時間到,就會進 git 並部署。 |
| 本地拿到最新語系 | 執行 git pull。若 CI 還沒同步,可執行 npm run i18n:pull 直接從 Tolgee 取得。 |
| 專案沒有新 commit,但想更新語系 | 到 GitLab 按 New pipeline(分支選 main),或在 Pipeline schedules 按播放鍵。 |
注意:本地執行 npm run i18n:pull 後若有未 commit 的語系變更,之後 git pull 可能因衝突被拒絕。把本地的語系變更還原,或先 commit 再 pull 即可。