Hợp đồng lockfile

​

Tên tệp chuẩn

​

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

• 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ộ.

​

Lược đồ

{
  "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": {
        "s": "7f4f7d...",
        "t": "1a2b3c..."
      }
    }
  }
}

• 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 để quyết định bỏ qua. Các lần ghi hiện tại nhóm các mục theo đường dẫn đích.
  • khóa lồng nhau: khóa mục bên trong tệp đích.
  • s: dấu vân tay của phân đoạn nguồn.
  • t: dấu vân tay của các kích thước tác vụ, chẳng hạn như mô hình, prompt, các trường ngữ cảnh và các đầu vào liên quan.
• active_run_id: mã định danh cho một lần chạy đang diễn ra. Nó được xóa sau khi chạy thành công.
• run_checkpoint: điểm kiểm tra đầu ra tạm thời cho từng tác vụ khi chạy bị gián đoạn. Nó được nhóm theo đường dẫn đích và được xóa sau khi chạy thành công.
  • r: mã định danh lần chạy.
  • p: đường dẫn nguồn.
  • l: ngôn ngữ bản địa đích.
  • v: giá trị đầu ra theo giai đoạn.
  • s, t, và u: dấu vân tay nguồn, dấu vân tay tác vụ, và dấu thời gian cập nhật.

​

Vòng đời theo lệnh

​

hyperlocalise run

• 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.
• Có thể đọc ngữ cảnh adapter/dự án từ tệp khóa.

​

hyperlocalise sync pull

• 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.

​

hyperlocalise sync push

• 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 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.
• run có thể thực thi lại các tác vụ trước đó đã bị bỏ qua

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

• 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ó 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.

​

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

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