Chuyển đến nội dung chính

​
Tên tệp chuẩn

Tên tệp khóa được cố định thành .hyperlocalise.lock.json. hyperlocalise hiện không đọc i18n.lock hoặc các tên bí danh khác. Giữ tệp trong thư mục gốc của dự án để run và các lệnh đồng bộ chia sẻ cùng trạng thái điểm kiểm tra. CLI ghi lockfile dưới dạng JSON thu gọn (không thụt lề) để giới hạn kích thước tệp.

​
Khóa tệp dùng để làm gì

Hãy coi tệp khóa là một điểm kiểm tra mang tính tham khảo, chứ không phải nguồn sự thật của bạn.
  • Nguồn sự thật cho nội dung có thể dịch là các tệp nguồn của bạn.
  • Nguồn sự thật cho đầu ra đã tạo là các tệp đích của bạn.
  • Nguồn sự thật cho trạng thái từ xa được đồng bộ là TMS của bạn cùng với các hiện vật cục bộ.
Tệp khóa chỉ ghi lại những gì CLI đã cố gắng hoặc đã hoàn tất, để có thể bỏ qua các công việc lặp lại. Nó không được dùng để chứng minh rằng một lần đẩy đồng bộ là an toàn. Tính an toàn của đồng bộ đến từ các tệp cục bộ hiện tại cộng với một mốc cơ sở từ xa mới được đọc tại thời điểm thực thi.

​
Lược đồ

Hình dạng hiện tại: 
{
  "adapter": "crowdin",
  "project_id": "12345",
  "last_pull_at": "2026-01-15T12:34:56Z",
  "locale_states": {
    "es-ES": {
      "revision": "rev_abc123",
      "updated_at": "2026-01-15T12:00:00Z"
    }
  },
  "run_completed": {
    "apps/web/lang/es-ES.json::checkout.submit": {
      "source_hash": "7f4f7d..."
    }
  }
}
Ý nghĩa các trường:
  • adapter: tên bộ điều hợp TMS đang hoạt động.
  • project_id: mã định danh dự án cụ thể cho adapter.
  • last_pull_at: dấu thời gian của lần kéo đồng bộ thành công gần nhất.
  • locale_states: ánh xạ checkpoint theo từng locale.
    • revision: bản sửa đổi adapter hoặc con trỏ cho logic kéo tăng dần.
    • updated_at: lần cuối điểm kiểm tra locale đó được làm mới.
  • run_completed: bản đồ hoàn thành theo từng tác vụ được run dùng cho các quyết định bỏ qua.
    • source_hash: dấu vân tay của đoạn nguồn. Các lần ghi mới sử dụng tiền tố hex chữ thường 32 ký tự của SHA-512. Các tệp khóa cũ hơn vẫn có thể lưu toàn bộ mã băm hex 128 ký tự; cả hai dạng đều được chấp nhận khi quyết định có bỏ qua công việc hay không.
    • task_hash: khi có mặt, dấu vân tay của các kích thước tác vụ (mô hình, prompt, các trường ngữ cảnh và các đầu vào liên quan). Nó sử dụng các quy tắc mã hóa giống như source_hash.

​
Vòng đời theo lệnh

​
hyperlocalise run

  • Đọc .hyperlocalise.lock.json khi lập kế hoạch công việc.
  • Bỏ qua công việc đã được đánh dấu là hoàn thành trong run_completed.
  • Duy trì các tác vụ thành công trở lại run_completed.

​
hyperlocalise sync pull

  • Có thể đọc siêu dữ liệu checkpoint của adapter và ngôn ngữ hiện có như một gợi ý về hiệu suất.
  • Tải về một ảnh chụp nhanh từ xa mới cho phạm vi được yêu cầu.
  • Cập nhật adapter, project_id, last_pull_at, và locale_states sau khi pull thành công.

​
hyperlocalise sync push

  • Có thể đọc ngữ cảnh adapter/dự án từ tệp khóa.
  • Không yêu cầu tệp khóa hoặc siêu dữ liệu sidecar để cho phép ghi.
  • Tính toán các thay đổi đẩy từ các tệp cục bộ cùng với một đường cơ sở từ xa mới cho cùng phạm vi.
  • Không thay thế thẩm quyền nội dung nguồn/đích.

​
Hướng dẫn đặt lại an toàn

Đặt lại file khóa khi trạng thái điểm kiểm tra đã cũ hoặc không còn đáng tin cậy. Các trường hợp đặt lại thường gặp:
  • bạn đã thay đổi cấu trúc văn bản nguồn rất nhiều
  • bạn đã thay đổi ánh xạ bucket hoặc mẫu đường dẫn tệp
  • bạn đã chuyển bộ điều hợp hoặc dự án
  • bạn nghi ngờ các mục checkpoint bị hỏng hoặc đã được chỉnh sửa thủ công
Các bước đặt lại an toàn:
  1. đảm bảo rằng các tệp nguồn và tệp đã tạo của bạn được commit hoặc sao lưu
  2. xóa .hyperlocalise.lock.json
  3. chạy hyperlocalise run --dry-run để kiểm tra kế hoạch lớn hơn
  4. chạy hyperlocalise run và/hoặc hyperlocalise sync pull để xây dựng lại trạng thái điểm kiểm tra
Các tác dụng phụ dự kiến sau khi đặt lại:
  • run có thể thực thi lại các tác vụ trước đó đã bị bỏ qua
  • lần kéo đồng bộ tiếp theo có thể thực hiện làm mới rộng hơn cho các ngôn ngữ địa phương
  • CLI runtime có thể tăng tạm thời cho đến khi các checkpoint được xây dựng lại

​
Các quy ước của nhóm

  • Không chỉnh sửa thủ công các trường lockfile trừ khi đang gỡ lỗi một sự cố cục bộ.
  • Giữ việc xử lý lockfile rõ ràng trong các script CI.
  • Xem xét các thay đổi của lockfile trong pull request khi hành vi chạy/đồng bộ có vẻ bất thường.