Tolgee多語系前端串接紀錄

紀錄tolgee服務已架設好後
後續串接前端專案

使用1: 專案git push > 撈取tolgee上最新語系 > commit紀錄語系更新 > 部屬到環境
使用2: new pipeline(gitlab build > pipelines) > 部屬到環境

編輯詞條的分工

動作在哪裡做原因
新增詞條(key)本地 JSON,經 git push 送上 Tolgeekey 跟著程式碼一起產生
修改既有文案一律在 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 namei18n-bot
RoleMaintainer
Scopes只勾 write_repository
Expiration date設定一個日期並記下來,過期後同步會失敗

建立後 token 只會顯示一次,請立刻複製,下一步要用。

取得 Tolgee API key

登入 Tolgee,進入該專案後建立一把專案 API key,權限需包含 keys 的檢視與新增,以及 translations 的檢視與編輯。
懶惰的話就直接開Admin

新增 CI/CD 變數

到 Settings > CI/CD > Variables,按 Add variable,新增兩個變數:

KeyValue設定
TOLGEE_API_KEY4.2 取得的 Tolgee API keyMasked and hidden;不勾 Expand variable reference
I18N_PUSH_TOKEN4.1 建立的 Access TokenMasked 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 timezoneTaipei
Target branchmain

排程列表右側的播放鍵可以立即執行一次。排程觸發時只會跑 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 即可。

關於站主

Shiro

因為興趣無限擴張,一直很猶豫要不要寫一個很雜的Blog,後來還是這麼做了。

聯絡:shiro050102✦gmail.com  ✦請自行更換成@