Hướng dẫn bản địa hóa JSON: Chuỗi, biến và lỗi thường gặp

Rà soát nguồn: 4 tháng 10 năm 2026

Trả lời nhanh

Dịch giá trị khách nhìn thấy, giữ cấu trúc khóa và cú pháp thông điệp đã thống nhất. Cung cấp ngữ cảnh, bảo vệ biến, kiểm JSON và thử trong sản phẩm. JSON là định dạng dữ liệu, không quyết định mọi thư viện xử lý lồng nhau, số nhiều hoặc markup thế nào. Ghi rõ framework và quy ước trước khi trao đổi tệp.

Điểm cần nhớ

• Giữ khóa ổn định nếu kỹ thuật chưa duyệt thay đổi.
• Dịch câu hoàn chỉnh, tránh ghép mảnh.
• Giữ biến như hợp đồng dữ liệu.
• Tách cú pháp, framework và giao diện.
• Không tự thêm ghi chú vào tài nguyên runtime.
• Thử lỗi, số lượng và dữ liệu động dài.

Tài nguyên JSON nào cần dịch?

Dịch nhãn, hướng dẫn, lỗi, thông báo và nội dung hỗ trợ tiếp cận người dùng nhìn hoặc nghe thấy. Dữ liệu vận hành cần giữ ngoài phạm vi nếu chưa được xác định phải bản địa hóa. Phần mở rộng tệp không đủ cho biết giá trị nào được sửa.

Thống nhất thư viện, namespace, dấu phân cách khóa, cú pháp biến, markup và kiểu trả về. Tệp cấu hình có thể chứa số, boolean, mã định danh cần giữ. Phân biệt nó với danh mục thông điệp trước khi giao dịch.

RFC 8259 định nghĩa JSON và khuyến nghị tên thành viên đối tượng duy nhất.[1] Phân tích thành công không phát hiện mọi lỗi dự án: ứng dụng có thể nhận đối tượng khi màn hình cần chuỗi, hoặc giá trị đã mất do trùng tên.

Thiết kế khóa và cấu trúc lồng nhau ra sao?

Tên khóa nên mô tả nhiệm vụ sản phẩm và cấu trúc dễ đoán. quote.received là tham chiếu ổn định dù câu hiển thị thay đổi. Cần xác định dấu chấm là đường dẫn hay ký tự thật trong loader đang dùng.

Không dùng một khóa continue cho mọi màn hình nếu hành động khác nhau. Thanh toán, thiết lập tài khoản và tải tài liệu có thể cần câu khác. Chỉ chia sẻ khi ý nghĩa và ràng buộc thực sự chung; nếu không, tạo khóa theo ngữ cảnh.

Cặp mẫu sau dùng đối tượng lồng và biến kiểu i18next, chưa phải tích hợp ứng dụng hoàn chỉnh. Nguồn tiếng Anh:

{
  "quote": {
    "title": "Request a quotation",
    "received": "We received request {{requestId}}.",
    "fileLimit": "Attach files totaling less than {{limit}}.",
    "nextStep": "Request received.\nOur team will review it."
  },
  "account": {
    "welcome": "Welcome, {{name}}.",
    "saveChanges": "Save changes"
  }
}

Bản tiếng Việt giữ đường dẫn và biến:

{
  "quote": {
    "title": "Gửi yêu cầu báo giá",
    "received": "Đã nhận yêu cầu {{requestId}}.",
    "fileLimit": "Đính kèm tệp có tổng dung lượng dưới {{limit}}.",
    "nextStep": "Đã nhận yêu cầu.\nĐội ngũ sẽ xem xét nội dung."
  },
  "account": {
    "welcome": "Chào {{name}}.",
    "saveChanges": "Lưu thay đổi"
  }
}

Ứng dụng cung cấp giới hạn; người dịch không tự đặt. Hai bản phải cùng mô tả ranh giới. Nếu hệ thống cho phép bằng giới hạn, nguồn cũng cần đổi; không âm thầm sửa quy tắc chưa rõ bằng bản dịch.

Bảo vệ biến dữ liệu như thế nào?

Giữ tên và dấu bao chính xác nhưng cho phép đổi vị trí tự nhiên. i18next có biến đặt tên và mặc định escape giá trị.[2] Hệ thống khác có thể dùng cú pháp, cách dựng khác; cần nêu môi trường thật trong yêu cầu.

Giải thích dữ liệu sau biến: name là người, tổ chức hay tệp? limit đã có đơn vị chưa? requestId chứa ký tự đặc biệt nào? Câu trả lời ảnh hưởng cách viết và kiểm tra.

Nên dùng câu có biến di chuyển được thay vì ghép “Welcome” với tên bằng hai mảnh. Giữ dấu câu trong thông điệp khi phù hợp. Không đổi {{name}} thành {{ten}}, thêm khoảng trắng vào mã hay ghi cứng tên khách minh họa.

Escape và xuống dòng ảnh hưởng gì?

Giữ JSON hợp lệ khi có dấu ngoặc kép, gạch chéo ngược hoặc ký tự điều khiển. Dùng serializer và công cụ kiểm của dự án, tránh thay thế thủ công. RFC 8259 quy định escape chuỗi và trao đổi UTF-8.[1]

Trong mẫu, \n mã hóa ký tự xuống dòng. Sau phân tích, chuỗi có ký tự đó; giao diện có xuống dòng trực quan không còn tùy ngữ cảnh dựng. Không thể suy bố cục từ việc parse thành công.

Kiểm đường đi từ tệp nguồn qua bảng tính, công cụ dịch, build tới màn hình. Gạch chéo ngược và chữ n được xuất sai có thể hiện nguyên ra. Đổi thành dòng mới thật nằm trong dấu ngoặc kép JSON có thể làm tệp không hợp lệ.

Không dùng comment hay dấu phẩy cuối trong JSON thông thường. Nếu dự án dùng JSONC hoặc biến thể, nêu tên và kiểm hỗ trợ thực tế. Editor chấp nhận chưa chắc loader runtime chấp nhận.

Số nhiều và ngữ cảnh nên xử lý ra sao?

Theo quy ước thư viện được chọn, không coi JSON có bộ máy số nhiều riêng. i18next mô tả chọn theo count và hậu tố phụ thuộc phiên bản.[3] Ghi phiên bản, thử số lượng thay vì sao hai dạng cho mọi ngôn ngữ.

Tiếng Anh có thể cần thông điệp khác cho một và nhiều. Tiếng Việt có thể giữ danh từ giống nhau nhưng ứng dụng vẫn phải tìm được tài nguyên theo quy tắc cấu hình. Thử không, một, nhiều và trạng thái riêng của sản phẩm.

Giải thích từ đa nghĩa: “Open” có thể là hành động hoặc trạng thái. “Charge” cần biết lĩnh vực. Ảnh màn hình, chữ xung quanh, giới hạn và mô tả hành động giúp tránh câu đúng ngữ pháp nhưng sai nhiệm vụ.

Tài nguyên lồng cũng cần thử theo loader. i18next có tùy chọn trả đối tượng, mảng.[4] Không giả định gọi khóa cha tự trả chuỗi cuối. Xác định ứng dụng cần thông điệp lá, cấu trúc hay tập hợp.

HTML và rich text trong JSON cần lưu ý gì?

Xem markup là hợp đồng dựng riêng. Ưu tiên cách xử lý rich text có cấu trúc được ứng dụng hỗ trợ thay vì chèn HTML tùy ý. Nêu thẻ hoặc token thành phần được phép và bảo vệ khi dịch.

Chuỗi parse được vẫn có thể không an toàn nếu đưa vào ngữ cảnh HTML không phù hợp. Không tắt escape chỉ để định dạng xuất hiện. Nhờ kỹ thuật xem framework, thành phần và yêu cầu làm sạch. Một cài đặt escape không chứng minh toàn ứng dụng an toàn.

Xem trước với giá trị thật, có ngoặc kép và ký tự đặc biệt của renderer. Bản dịch không được thêm hành vi thực thi hay đổi đích liên kết. Kiểm nội dung hỗ trợ tiếp cận riêng nếu định dạng nhìn thấy không phù hợp lời đọc.

Những lỗi nào cần kiểm rõ?

Ưu tiên lỗi phá hợp đồng trước sửa phong cách. Hồ sơ lỗi cần đường dẫn tài nguyên, nguồn, đích, hành vi mong muốn và cách tái hiện. Bảng dưới là tình huống tự xây dựng.

Dự phòng là quyết định, không mặc nhiên là đạt. Tiếng Anh giúp màn hình hoạt động khi phát triển nhưng có thể không được chấp nhận lúc phát hành tiếng Việt. Nêu thông điệp nào thiếu sẽ chặn và cách theo dõi chuỗi mới.

Bàn giao nên có những gì?

Giao tài nguyên đã kiểm, danh sách ngữ cảnh, thuật ngữ và câu hỏi chưa xử lý. Nêu phiên bản nguồn, ngôn ngữ đích, biến bảo vệ và kiểm tra đã thống nhất. Sau này có thể so xuất tệp mà không đoán nguồn dùng để dịch.

Khi hỏi bản địa hóa phần mềm, gửi JSON đại diện, ảnh màn hình và framework. Phân biệt chỉ dịch, rà soát ngôn ngữ hay thử trong bản chạy. Gửi qua trang báo giá để phạm vi phản ánh nhu cầu triển khai.

Trước phát hành, có ba lớp: parse và lint; thử gọi khóa, biến trong framework; xem giao diện. Kiểm tệp tại máy chỉ chứng minh lớp đầu, không thay hai lớp kia. Ghi rõ trong bàn giao lớp nào thực sự đã làm.

Câu hỏi thường gặp

Người dịch có dịch khóa JSON không?

Thường không. Khóa là tham chiếu ứng dụng. Chỉ đổi khi kỹ thuật quản lý di chuyển, cập nhật nơi gọi và quy tắc kiểm.

Mọi giá trị JSON đều dịch được không?

Không. Cấu hình, mã và kiểu dữ liệu có thể phục vụ vận hành. Xác định phạm vi trước, giữ phần ngoài phạm vi.

JSON.parse có phát hiện khóa trùng không?

Không phải công cụ lint phát hiện trùng. Cần kiểm nguồn phù hợp vì parser có thể nhận tệp nhưng mất giá trị trước.[1]

{{name}} có phải tính năng chung của JSON không?

Không. Đó là quy ước biến của hệ thống như i18next.[2] JSON lưu chuỗi, runtime diễn giải token.

JSON hợp lệ vẫn làm hỏng giao diện được không?

Có. Quy tắc gọi, kiểu, biến, dựng và bố cục vẫn có thể sai. Kiểm tệp và hành vi sản phẩm riêng.

Cần gì để dự trù dự án?

Gửi tệp, phiên bản nguồn, màn hình, ngôn ngữ, quy ước framework và lịch phát hành. Nêu ai tích hợp, có cần rà soát tích hợp không.

Nguồn và phương pháp

Đối chiếu RFC 8259 và tài liệu i18next ngày 4 tháng 10 năm 2026. Cặp tài nguyên, bảng QA là ví dụ tự xây dựng. Parse, so đường dẫn và kiểm biến có thể tái hiện tại máy; không khẳng định đã thử tích hợp i18next, trình duyệt hoặc đánh giá bảo mật toàn ứng dụng.

Tài liệu tham khảo

[1] IETF / RFC Editor. RFC 8259: The JavaScript Object Notation Data Interchange Format.

[2] i18next documentation. Interpolation.

[3] i18next documentation. Plurals.

[4] i18next documentation. Objects and arrays.

Bài viết liên quan

• 100 thuật ngữ giao diện Anh–Việt thường gặp trong SaaS và ứng dụng
• Cách bản địa hóa sản phẩm SaaS cho người dùng Việt Nam
• So sánh XLIFF, JSON, PO và ARB trong bản địa hóa
• Giải thích ICU MessageFormat qua các ví dụ bản địa hóa
• Cẩm nang bản địa hóa tiếng Việt cho phần mềm và SaaS
• Hướng dẫn định dạng ngày giờ, số và tiền tệ trong tiếng Việt