← Học

Khắc phục sự cố

Mỗi mục ở đây là một lỗi có thật mà đã có người gặp phải. Mỗi mục đều nêu rõ triệu chứng, nguyên nhân và cách khắc phục — phần lớn đều quy về một trong ba nguyên nhân: cụm từ không có trong dự án, SDK chưa bao giờ được khởi tạo, hoặc một placeholder bị viết sai cho ngữ cảnh.

Không có gì được dịch — mọi cụm từ vẫn ở ngôn ngữ gốc

Khi mọi thứ đều hiển thị văn bản gốc, gần như chắc chắn SDK đã khởi tạo thất bại. Theo thiết kế, nó lỗi một cách êm (giao diện của bạn không bao giờ được hỏng), nên tín hiệu rõ ràng duy nhất là console của trình duyệt — hãy kiểm tra nó trước. Các nguyên nhân thường gặp, theo thứ tự khả năng xảy ra:

1. CORS. Yêu cầu đầu tiên của SDK là authorize-project; nếu API của bạn không đưa origin của ứng dụng vào danh sách cho phép, trình duyệt sẽ chặn yêu cầu này và quá trình khởi tạo dừng ngay tại đó. Hãy nhớ rằng một origin chính là scheme + host + port chính xác — localhost:5173 và localhost:5174 là hai origin khác nhau, và máy chủ dev thường tự đổi sang cổng khác khi cổng quen thuộc đã bị chiếm. Hãy thêm mọi cổng mà bạn thực sự dùng để phát triển vào danh sách cho phép.
2. Sai thông tin xác thực. ID dự án / khóa API bị thiếu hoặc nhập sai sẽ khiến cùng lệnh gọi ủy quyền này thất bại. Bảng điều khiển hiển thị yêu cầu bị lỗi và URL.
3. Bạn đang xem ngôn ngữ gốc. Ở ngôn ngữ gốc, "bản dịch" chính là văn bản nguồn — nên không có gì thay đổi để thấy. Hãy chuyển sang một ngôn ngữ đích để thử nghiệm.

# The SDK's first call is an authorize-project request.
# If the browser blocks it, NOTHING translates. Check the console for:
Access to fetch at 'https://your-api/api/authorize-project/...'
from origin 'http://localhost:5173' has been blocked by CORS policy

# Fix: allowlist the app's EXACT origin (scheme + host + port) on the API.
CORS_ALLOWED_ORIGINS=http://localhost:5173,https://app.example.com

Một cụm từ không dịch được (nhưng các cụm khác thì được)

Cụm từ trong mã của bạn chính là khóa tra cứu — cụm từ chính là khóa. Nếu một cụm từ hiển thị bằng văn bản gốc trong khi các cụm từ lân cận đều được dịch, thì khóa đó không có trong danh mục của dự án:

• Cụm từ này chưa bao giờ được đăng ký. Việc đăng ký diễn ra thông qua khám phá token, và chỉ có khóa ghi mới thực hiện được. Nếu cụm từ phát sinh khi ứng dụng chạy bằng khóa chỉ đọc, thì nó chưa từng được gửi đi đâu cả — hãy chạy màn hình đó một lần trong môi trường phát triển với khóa ghi, hoặc thêm cụm từ trong bảng điều khiển.
• Văn bản đã thay đổi. Bất kỳ chỉnh sửa nào — một từ, dấu câu, thậm chí khoảng trắng — đều biến nó thành một cụm từ mới chưa có bản dịch nào. Các bản dịch cũ vẫn tồn tại dưới khóa cũ. Điều này đặc biệt gây rắc rối với các khối nội dung: một khối <Translate> được tách token từ phần markup của nó, nên việc sửa văn bản hoặc cấu trúc của khối sẽ làm thay đổi nội dung được tra cứu, và khối đó sẽ âm thầm quay về văn bản gốc cho đến khi dạng mới được đăng ký và dịch.
• Bản dịch máy chưa theo kịp. Một cụm từ vừa đăng ký có thể có bản dịch chậm hơn một chút, và ngôn ngữ nằm ngoài danh sách ngôn ngữ đích của dự án sẽ không bao giờ có bản dịch. Hãy kiểm tra cụm từ trong bảng điều khiển: đã đăng ký chưa? đã được dịch sang ngôn ngữ này chưa?

Tại sao các cụm từ bị thiếu không gây ra lỗi?

Đây là chủ ý thiết kế. Trong môi trường production, hệ thống dịch phải lùi về văn bản gốc dễ đọc chứ không bao giờ làm hỏng trang — vì vậy một cụm từ chưa đăng ký sẽ hiển thị văn bản gốc và SDK im lặng. Mặt trái là: với khóa chỉ đọc, cụm từ bị thiếu sẽ âm thầm bị bỏ qua. Không có gì được ghi log, không có gì được đăng ký, và bạn chỉ biết khi có người dùng thấy tiếng Anh. Quy trình giúp tránh điều này là tách khóa — phát triển với khóa ghi để mọi cụm từ mà giao diện hiển thị đều được phát hiện, rồi mới phát hành với khóa chỉ đọc.

# Development — write key: new phrases are discovered,
# registered, and machine-translated as you build.
VITE_LANGSYS_API_KEY=write-key

# Production — read-only key: fetches the finished catalog only.
# Unregistered phrases silently render their source text.
VITE_LANGSYS_API_KEY=read-only-key

Trình giữ chỗ của tôi hiển thị nguyên văn — "Hi %name%" hoặc "Hi {name}"

• Trong các lệnh gọi t(), placeholder dùng một cặp ngoặc nhọn {name}, và phép nội suy chỉ chạy khi bạn truyền tham số: t('Hello, {name}!', 'Greetings', { name }).
• Trong markup <Translate>/<Phrase> dưới React, Vue hoặc Svelte, hãy viết placeholder dưới dạng %name%. Trình biên dịch của framework sẽ xử lý {name} trần như một biểu thức trước khi SDK kịp nhìn thấy; còn %name% vẫn được giữ nguyên sau khi biên dịch và SDK sẽ chuẩn hóa nó trở lại thành {name} khi thu thập. {name} thông thường vẫn dùng tốt trong HTML thuần, nơi không có cú pháp template nào gây xung đột.
• Thiếu params? Nếu không truyền params, mẫu sẽ được hiển thị nguyên trạng — đó chính là chuỗi %name% mà bạn đang thấy.

Ban đầu chạy tốt, nhưng bị lỗi sau khi tôi chuyển đổi qua lại giữa các locale

Hãy cập nhật SDK. Các lỗi thực tế đã được sửa trong phần này: việc quay lại ngôn ngữ ban đầu/SSR khiến danh mục trước đó vẫn còn hiệu lực (đã sửa trong langsys-js-typescript 0.2.2), và các thành phần dùng Translate/Phrase của khối nội dung có thể treo vô thời hạn trên danh mục được nạp sẵn từ máy chủ (đã sửa trong 0.2.3). Nếu bạn thấy chuỗi thuộc ngôn ngữ cũ hoặc các khối không bao giờ được xử lý xong, hãy đối chiếu phiên bản đã cài đặt với nhật ký thay đổi của SDK cơ sở trước khi gỡ lỗi mã của riêng bạn.

Phía máy chủ: trang trả về lỗi 500 thay vì giảm cấp êm

Client của PHP SDK sẽ ném lỗi khi được khởi tạo mà không có thông tin xác thực — nên một ứng dụng Laravel (hoặc PHP thuần) có LANGSYS_API_KEY trống sẽ thất bại ngay lúc container phân giải, trước khi bất kỳ bản dịch nào được chạy. Hãy thiết lập thông tin xác thực (hoặc, với ứng dụng bắt buộc phải khởi động được khi không có chúng, hãy bind một client giả như cách các ứng dụng demo đang làm). Khi đã có thông tin xác thực, các lỗi API khi chạy sẽ được xử lý theo hướng giảm cấp: nếu API không truy cập được hoặc từ chối, ứng dụng sẽ hiển thị văn bản gốc và báo cáo ngoại lệ — trang sẽ không bao giờ bị sập.

Phía máy chủ: yêu cầu đầu tiên bị treo, sau đó mọi thứ đều nhanh

Thời gian chờ HTTP của PHP SDK là 30 giây, và một phiên bản API đang được đánh thức từ trạng thái nhàn rỗi có thể gần chạm ngưỡng này ngay ở lần gọi đầu tiên. Yêu cầu đó hoặc hoàn tất chậm (và làm nóng bộ nhớ đệm danh mục — mọi yêu cầu sau đó đều được phục vụ từ bộ nhớ đệm), hoặc hết thời gian chờ và hiển thị văn bản gốc. Nếu lần tải trang đầu tiên sau một khoảng thời gian không hoạt động bị chậm, đó là lý do: do API đang khởi động, không phải lỗi từ phần tích hợp của bạn.

Phía máy chủ: tôi đã render bằng write key nhưng cụm từ không xuất hiện trong dashboard

Các cụm từ được phát hiện sẽ được đưa vào hàng đợi trong lúc xử lý yêu cầu và được gửi đi sau khi phản hồi đã được trả về — đó là terminable middleware của Laravel. Hãy làm mới dashboard một lúc sau khi trang tải xong, đừng làm trong khi đang tải. Với các môi trường chạy worker tồn tại lâu (Octane, FrankenPHP, RoadRunner), hãy đảm bảo bạn đang dùng tích hợp do SDK cung cấp — hook shutdown của PHP thuần sẽ không bao giờ được kích hoạt giữa các yêu cầu của worker.

Kết xuất phía máy chủ: bản dịch của yêu cầu này lẫn sang yêu cầu khác

SDK JS cơ sở chỉ giữ danh mục của một ngôn ngữ tại một thời điểm — nó là singleton cấp module. Máy chủ Node kết xuất các ngôn ngữ khác nhau cho các yêu cầu đồng thời sẽ bị xung đột (race). Hãy tải danh mục cho từng yêu cầu và khởi tạo client từ đó, theo mẫu trong các hướng dẫn Next.js, Nuxt và SvelteKit, hoặc chạy mỗi ngôn ngữ trong một tiến trình riêng.