← Quay lại blog
A git diff view showing a locale file with three changed keys highlighted, and only those three keys being sent to the translation API below.

Bạn không cần phải dịch lại mọi thứ: cách dịch delta hoạt động trong CI

By Robert M

Bạn không cần dịch lại mọi thứ: cách dịch delta hoạt động trong CI

Khi bạn tích hợp dịch tự động vào pipeline CI của mình, một câu hỏi tự nhiên được đặt ra nhanh chóng: liệu nó có dịch lại toàn bộ tệp locale mỗi lần ai đó đẩy thay đổi không?

Nếu không có chế độ delta, thì có. Mỗi lần đẩy chạm vào tệp locale nguồn của bạn sẽ gửi toàn bộ tệp đó đến API, mọi khóa, mọi chuỗi, dù có thay đổi hay không. Đối với một dự án nhỏ ở giai đoạn đầu thì điều đó ổn. Đối với một dự án trưởng thành với hàng trăm khóa dịch trên 10 hoặc 20 ngôn ngữ, bạn đang tiêu tốn token cho các chuỗi không thay đổi kể từ lần chạy trước và nhận lại kết quả giống hệt nhau mà không có lợi ích gì.

Dịch delta giải quyết vấn đề này. Thay vì gửi toàn bộ tệp, Action sẽ so sánh tệp nguồn hiện tại của bạn với baseline đã lưu trữ, xác định chỉ các khóa được thêm hoặc sửa đổi, và chỉ gửi những khóa đó đến API. Kết quả cho các khóa không thay đổi được lấy từ các tệp dịch hiện có. Việc sử dụng token giảm xuống phù hợp với công việc thực tế được thực hiện.

Cách baseline hoạt động

Khi chế độ delta chạy lần đầu tiên, hoặc khi bạn ép buộc làm mới toàn bộ, Action sẽ dịch toàn bộ tệp nguồn và lưu trữ một biểu diễn JSON phẳng của nó dưới dạng tệp baseline trong kho mã của bạn. Ở các lần chạy tiếp theo, Action sẽ tải baseline đó, so sánh với tệp nguồn hiện tại, và xây dựng một payload chỉ chứa các khóa đã thay đổi.

Đối với các tệp locale JSON, baseline được lưu dưới dạng .polylingo-baseline.json trong thư mục messages của bạn. Đối với các tệp locale YAML, nó là .polylingo-yaml-baseline.json trong thư mục locales. Đối với các tệp lang PHP Laravel, nó là .polylingo-laravel-php-baseline.json trong thư mục lang.

Baseline được commit cùng với các tệp dịch của bạn nên nó đi kèm với kho mã. Bất kỳ nhà phát triển nào clone repo cũng sẽ có cùng baseline mà pipeline đang sử dụng.

Điều gì được tính là thay đổi

Diff hoạt động trên biểu diễn khóa phẳng của tệp nguồn của bạn. Các cấu trúc lồng nhau được làm phẳng thành các khóa theo ký hiệu chấm trước khi so sánh:

{
  "nav.home": "Trang chủ",
  "nav.about": "Về chúng tôi",
  "hero.title": "Chào mừng đến với nền tảng của chúng tôi",
  "hero.cta": "Bắt đầu"
}

Một khóa được bao gồm trong payload delta nếu:

  • Nó tồn tại trong tệp nguồn hiện tại nhưng không có trong baseline (khóa mới)
  • Nó tồn tại ở cả hai nhưng giá trị đã thay đổi (khóa đã sửa đổi) Các khóa tồn tại trong baseline nhưng không có trong tệp nguồn hiện tại (khóa bị xóa) sẽ tự động bị loại khỏi các tệp đầu ra dịch. Các khóa giống hệt nhau ở cả hai bên sẽ bị bỏ qua hoàn toàn và bản dịch hiện có của chúng được giữ nguyên.

Điều này trông như thế nào trong thực tế

Giả sử bạn có một dự án Next.js với 200 khóa dịch trong messages/en.json, đã được dịch sang 12 ngôn ngữ. Một nhà phát triển cập nhật phần nội dung hero và thêm hai khóa mới cho một thông báo tính năng. Đó là 4 khóa thay đổi trong số 200.

Không có chế độ delta, pipeline gửi tất cả 200 khóa nhân với 12 ngôn ngữ trong mỗi lần đẩy. Với chế độ delta, nó chỉ gửi 4 khóa. Việc sử dụng token cho lần chạy đó chỉ khoảng 2% so với chi phí dịch đầy đủ. Pipeline cũng nhanh hơn vì có ít dữ liệu để gửi và ít phải chờ đợi.

Trong một tháng phát triển thường xuyên, khoản tiết kiệm này tích lũy đáng kể. Hầu hết các lần đẩy chỉ chạm vào một vài chuỗi. Việc dịch lại toàn bộ chỉ xảy ra khi bạn thêm một ngôn ngữ mới hoặc đặt lại baseline một cách rõ ràng.

Ba PolyLingo GitHub Actions

Chế độ delta có sẵn trên cả ba PolyLingo translation Actions. Mỗi cái được xây dựng cho một loại nội dung và cấu trúc dự án cụ thể.

translateAction — JSON và Markdown

Action gốc. Xử lý các tệp locale JSON phẳng theo phong cách next-intl và i18next, với tùy chọn xử lý tài liệu Markdown qua async jobs API cho các tệp lớn hơn.

- uses: UsePolyLingo/translate-action@v1
  with:
    api_key: ${{ secrets.POLYLINGO_API_KEY }}
    source_file: messages/en.json
    locales: fr,de,es,ja,zh
    delta: true
    commit: true
    commit_message: "chore(i18n): sync translations"

Delta baseline: messages/.polylingo-baseline.json

github.com/UsePolyLingo/translateAction — Xem trên Marketplace

translate-action-yaml — Tệp locale YAML

Dành cho các dự án sử dụng tệp locale YAML lồng nhau: Rails i18n, Vue i18n và bất kỳ framework nào khác sử dụng định dạng YAML. Action xử lý tự động quy ước Rails về khóa locale gốc — en.yml có khóa gốc en:, và mỗi tệp đầu ra có khóa locale đích chính xác (fr:, de: v.v).

Vì API PolyLingo làm việc với JSON một cách tự nhiên, Action sẽ làm phẳng YAML lồng nhau thành JSON theo ký hiệu chấm trước khi gửi, dịch, sau đó tái tạo cấu trúc lồng nhau và ghi đầu ra YAML hợp lệ. Một lưu ý cho v1: các khóa chứa dấu chấm tự nhiên không được hỗ trợ vì xung đột với việc làm phẳng theo ký hiệu chấm.

- uses: UsePolyLingo/translate-action-yaml@v1
  with:
    api_key: ${{ secrets.POLYLINGO_API_KEY }}
    locales_dir: config/locales
    source_file: config/locales/en.yml
    locales: fr,de,es,ja
    delta: true
    commit: true

Delta baseline: config/locales/.polylingo-yaml-baseline.json

github.com/UsePolyLingo/translate-action-yaml — Xem trên Marketplace

translate-action-laravel — Tệp lang Laravel

Dành cho các dự án Laravel sử dụng tệp dịch JSON (lang/en.json, hỗ trợ cả cấu trúc lồng nhau và phẳng theo phong cách Laravel 9+) hoặc tệp lang mảng PHP (lang/en/*.php). Action tự động phát hiện định dạng dự án của bạn qua php_format: auto — nó kiểm tra lang/en.json trước và nếu không tìm thấy sẽ chuyển sang tệp mảng PHP.

Đối với tệp PHP, nó gọi PHP CLI để đọc tệp nguồn và tuần tự hóa đầu ra dịch trở lại cú pháp mảng PHP hợp lệ trong JavaScript, không cần phụ thuộc bổ sung. Các runner ubuntu-latest do GitHub lưu trữ mặc định có PHP 8.x nên không cần bước thiết lập thêm. Yêu cầu PHP 7.4 trở lên.

Một lưu ý cho v1: các khóa chứa dấu chấm không được hỗ trợ trong chế độ PHP do chiến lược làm phẳng theo ký hiệu chấm.

- uses: UsePolyLingo/translate-action-laravel@v1
  with:
    api_key: ${{ secrets.POLYLINGO_API_KEY }}
    lang_dir: lang
    source_locale: en
    locales: fr,de,es,pt,nl
    php_format: auto
    delta: true
    open_pr: true

Delta baseline: lang/.polylingo-laravel-json-baseline.json hoặc lang/.polylingo-laravel-php-baseline.json tùy theo định dạng.

github.com/UsePolyLingo/translate-action-laravel — Xem trên Marketplace

Chế độ PR so với chế độ commit

Cả ba Action đều hỗ trợ hai chế độ đầu ra.

Chế độ commit (commit: true) ghi các tệp dịch và commit trực tiếp vào nhánh hiện tại. Cài đặt đơn giản, phù hợp với các nhóm coi dịch là quy trình tự động không cần xem xét.

Chế độ PR (open_pr: true) tạo một nhánh mới (polylingo/yaml-<sha>, polylingo/laravel-<sha> v.v), ghi các tệp dịch ở đó và mở một pull request tới nhánh cơ sở của bạn. Tốt hơn cho các nhóm muốn có bước xem xét thủ công trước khi nội dung dịch được hợp nhất, hoặc cho các dự án mà chất lượng dịch ảnh hưởng trực tiếp đến trải nghiệm người dùng.

Khi cả hai được bật, chế độ PR sẽ được ưu tiên.

Chế độ PR yêu cầu quyền pull-requests: write trong workflow của bạn:

permissions:
  contents: write
  pull-requests: write

Ép buộc làm mới toàn bộ

Chế độ delta so sánh với baseline đã lưu. Nếu bạn muốn dịch lại toàn bộ bất kể baseline hiển thị gì, hãy đặt delta: false. Điều này cũng cập nhật baseline để khớp với tệp nguồn hiện tại, vì vậy các lần chạy delta tiếp theo sẽ bắt đầu từ trạng thái mới.

Làm mới toàn bộ hữu ích khi bạn thêm một ngôn ngữ mục tiêu mới, khi bạn muốn áp dụng cải tiến chất lượng dịch trong phiên bản mô hình mới, hoặc khi baseline bị lệch so với thực tế vì bất kỳ lý do nào.

- uses: UsePolyLingo/translate-action-yaml@v1
  with:
    api_key: ${{ secrets.POLYLINGO_API_KEY }}
    locales_dir: config/locales
    locales: fr,de,es,ja,zh,ko,ar
    delta: false  # làm mới toàn bộ, cập nhật baseline
    commit: true

Đầu ra cho các bước tiếp theo

Cả ba Action đều cung cấp cùng một đầu ra để bạn có thể sử dụng trong các bước workflow tiếp theo:

- uses: UsePolyLingo/translate-action@v1
  id: translate
  with:
    api_key: ${{ secrets.POLYLINGO_API_KEY }}
    source_file: messages/en.json
    locales: fr,de,es
    delta: true
    commit: true

- name: Ghi lại thống kê dịch
  run: |
    echo "Locales translated: ${{ steps.translate.outputs.locales_translated }}"
    echo "Files changed: ${{ steps.translate.outputs.files_changed }}"
    echo "Tokens used: ${{ steps.translate.outputs.tokens_used }}"

Mỗi lần chạy cũng ghi một bảng tóm tắt vào phần tóm tắt bước của GitHub Actions để bạn có thể xem việc sử dụng token và kết quả dịch mà không cần phải tìm trong nhật ký.

Bắt đầu

Cả ba Action đều có trên GitHub Marketplace. Bạn sẽ cần một khóa API PolyLingo, có thể lấy miễn phí tại usepolylingo.com. Gói miễn phí bao gồm 50.000 token mỗi tháng. Với chế độ delta được bật, hầu hết các dự án sẽ nằm trong giới hạn này khi đẩy phát triển thường xuyên.

Thêm khóa API của bạn làm bí mật trong kho mã (POLYLINGO_API_KEY) và thêm Action tương ứng vào workflow của bạn. Lần chạy đầu tiên sẽ dịch toàn bộ và thiết lập baseline. Mỗi lần chạy sau chỉ dịch những gì đã thay đổi.