Ngày rà soát: 4 tháng 10 năm 2026
Trả lời nhanh
Hãy quản lý tài nguyên i18next cùng phiên bản ứng dụng: có người phụ trách, khóa ổn định, mô tả biến và bằng chứng kiểm tra. Khi nghiệm thu, cần xem cả câu dịch lẫn điều kiện chọn, tải và hiển thị câu đó. JSON hợp lệ chưa chứng minh khách hàng sẽ nhận đúng tiếng Việt. Fallback giúp giao diện tiếp tục hoạt động nhưng có thể che những phần chưa dịch.
Điểm cần nhớ
- Chia tài nguyên theo chức năng và trách nhiệm bảo trì.
- Viết thông điệp hoàn chỉnh, giải thích dữ liệu truyền vào biến.
- Kiểm tra trường hợp không có, một và nhiều đối tượng.
- Quy định rõ hành trình nào được dùng ngôn ngữ dự phòng.
- Phát hành mã ứng dụng và bản dịch tương thích với nhau.
- Rà soát giao diện sau bước kiểm tra tự động.
Nên chia namespace và đặt tên khóa như thế nào?
Namespace là nhóm bản dịch có tên trong i18next. Thư viện hỗ trợ nhiều namespace và cho phép cấu hình nhóm mặc định.[1] Cách chia nên phục vụ người quản lý nội dung và quy trình phát hành, thay vì chỉ nhằm giảm độ dài của tệp.
Với ứng dụng nhận yêu cầu báo giá, có thể bắt đầu bằng common, quote và account. Người phụ trách báo giá xem nội dung gửi yêu cầu mà không phải tìm giữa các thiết lập tài khoản. Chỉ đưa một nút vào nhóm dùng chung khi ý nghĩa thực sự giống nhau. “Open” để mở tài liệu khác với trạng thái phiếu hỗ trợ chưa đóng.
LocalizeZone đề xuất tên khóa theo ý nghĩa, chẳng hạn quote.submit, thay cho button3. Khi sửa câu chữ nhưng giữ nguyên hành động, thường có thể giữ khóa. Nếu thay đổi ý nghĩa nghiệp vụ, hãy cân nhắc khóa mới và giữ tài nguyên cũ cho những phiên bản ứng dụng còn được hỗ trợ.
| Nhóm tài nguyên | Trách nhiệm điển hình | Ngữ cảnh cần gửi | Câu hỏi nghiệm thu |
|---|---|---|---|
| Thao tác chung | Hủy việc chưa hoàn tất | Màn hình và hậu quả khi hủy | Các màn hình có cùng ý nghĩa không? |
| Yêu cầu báo giá | Gửi thông tin để xem xét | Trạng thái biểu mẫu, bước tiếp theo | Có vô tình hứa báo giá ngay không? |
| Tải tệp | Hướng dẫn đính kèm | Loại tệp, giới hạn thực tế | Nội dung có đúng quy tắc máy chủ không? |
| Tài khoản | Sửa tùy chọn nhận thông báo | Người nhận và phạm vi thông báo | Khách hiểu điều gì sẽ thay đổi không? |
| Giao dịch | Hiển thị thanh toán chờ xử lý | Trạng thái giao dịch đã xác nhận | Có nhầm với thanh toán thành công không? |
| Hỗ trợ | Giải thích phản hồi chậm | Giờ hỗ trợ, hướng xử lý | Khách biết bước tiếp theo không? |
Bảng này là đề xuất phân trách nhiệm. Chỉ đổi cấu trúc khi có vấn đề bảo trì cụ thể.
Khi nào nên dùng biến trong câu dịch?
Dùng biến cho dữ liệu chỉ biết lúc chạy, như tên khách hoặc số tệp. Không nên ráp câu từ các mảnh đã dịch; hướng dẫn chính thức giải thích rằng cách ráp này có thể gây khó khăn về ngữ pháp.[2]
Ví dụ Chào {{name}}. cho phép dịch cả thông điệp và giữ nguyên tên biến, thay vì phải suy luận cách ghép ba khóa.
Mỗi biến cần có tên, kiểu dữ liệu, nguồn và ví dụ. Cho biết giá trị có thể rỗng, dài hoặc do người dùng nhập không. Mã dự án cần giữ nguyên; tiền tệ cần quy tắc định dạng riêng. Người dịch không nên tự thay đổi ý nghĩa dữ liệu để câu nhìn thuận mắt hơn.
Theo tài liệu, i18next mặc định escape giá trị nội suy và có tùy chọn tắt hành vi này.[3] Cần kiểm tra cả nơi hiển thị: nút văn bản, thành phần giao diện và chèn HTML trực tiếp không có cùng trách nhiệm. Đừng tắt escape chỉ vì thấy ký tự lạ; hãy tìm nguyên nhân trong toàn bộ đường xử lý.
Nếu nội dung cần chữ đậm hoặc liên kết, hãy quy định thành phần nào được phép, biến nào thuộc dữ liệu khách và ai kiểm tra tích hợp. Tệp dịch không nên chứa markup tùy ý mà người rà soát không hiểu mục đích.
Ví dụ tài nguyên Việt–Anh có cấu trúc ra sao?
Giữ thông điệp đủ nghĩa và giữ nguyên tên biến giữa hai ngôn ngữ. Ví dụ tự xây dựng dưới đây thuộc namespace quote, dùng kiểu hậu tố plural hiện hành. Tiếng Việt sử dụng nhánh cardinal other; thông điệp không có tệp được tách riêng để phù hợp trạng thái sản phẩm.
Tệp quote.json tiếng Anh:
{
"welcome": "Hello, {{name}}.",
"attachments_zero": "No files attached.",
"attachments_one": "{{count}} file attached.",
"attachments_other": "{{count}} files attached.",
"review": "We will review your request.",
"review_business": "Our team will review your company request."
}Tệp quote.json tiếng Việt:
{
"welcome": "Chào {{name}}.",
"attachments_zero": "Chưa đính kèm tệp.",
"attachments_other": "Đã đính kèm {{count}} tệp.",
"review": "Chúng tôi sẽ xem xét yêu cầu của bạn.",
"review_business": "Đội ngũ sẽ xem xét yêu cầu của công ty bạn."
}Tùy chọn count chọn câu theo số lượng; nhánh _zero có thể cung cấp câu riêng khi bằng không.[4] Tùy chọn context chọn biến thể theo ngữ cảnh.[5] Ở đây business là loại yêu cầu đã biết, không phải thông tin suy đoán từ tên hay địa chỉ khách.
Khi đã đưa hai đối tượng vào enQuote và viQuote, có thể khởi tạo instance độc lập như sau:
import i18next from 'i18next';
const appI18n = i18next.createInstance();
await appI18n.init({
lng: 'vi',
fallbackLng: 'en',
supportedLngs: ['en', 'vi'],
ns: ['quote'],
defaultNS: 'quote',
resources: {
en: { quote: enQuote },
vi: { quote: viQuote }
},
interpolation: { escapeValue: true }
});
appI18n.t('welcome', { name: 'Lan' });
appI18n.t('attachments', { count: 3 });
appI18n.t('review', { context: 'business' });Đây là ví dụ khởi tạo, chưa gồm phần nhập tài nguyên, chọn ngôn ngữ và dựng giao diện. Kiểm tra cục bộ bằng i18next 26.4.2 trên Node.js 24.18.0 trả về Chào Lan., Đã đính kèm 3 tệp. và câu dành cho yêu cầu doanh nghiệp. Kiểm tra còn bao gồm số lượng 0, 1, ngữ cảnh mặc định, escape và fallback. Kết quả này không thay thế kiểm thử trình duyệt.
Vì sao fallback có thể che phần chưa dịch?
Fallback cho phép tìm tài nguyên dự phòng khi thiếu câu được yêu cầu. i18next hỗ trợ fallback theo ngôn ngữ và namespace.[6] Có văn bản đọc được không đồng nghĩa hành trình đã hoàn chỉnh bằng tiếng Việt.
Giả sử lỗi tải tệp rơi về câu tiếng Anh. Kiểm tra chỉ yêu cầu kết quả không rỗng sẽ đạt, dù khách chưa nhận đúng hướng dẫn tiếng Việt. Với trạng thái quan trọng, hãy ghi rõ ngôn ngữ và ý nghĩa mong đợi, không chỉ điều kiện “có chữ trên màn hình”.
LocalizeZone đề xuất kiểm tra riêng hai chế độ. Chế độ sản phẩm xác nhận chính sách dự phòng hoạt động đúng. Chế độ rà soát độ bao phủ xác định khóa nào thiếu ở ngôn ngữ đích; câu tiếng Anh không được tính thành phần tiếng Việt đã hoàn thành.
Mỗi lỗi nên có khóa, hành trình, ngôn ngữ yêu cầu, mức ảnh hưởng và người xử lý. Với nhãn hỗ trợ ít rủi ro, nhóm có thể chấp nhận dự phòng tạm thời. Với thao tác xóa dữ liệu hay hướng dẫn thanh toán, có thể cần sửa trước phát hành. Đây là quyết định nghiệp vụ của nhóm, không phải điều thư viện tự quyết định.
Cần lưu ý gì khi tải bản dịch theo nhu cầu?
Tải tài nguyên tạo thêm trạng thái chờ: giao diện có thể sẵn sàng trước namespace cần dùng. i18next hỗ trợ backend tải bản dịch; khi kết hợp tài nguyên đóng gói sẵn và tải sau, có thể cần partialBundledLanguages.[7] Hãy đối chiếu với cấu hình thực tế.
Trước khi mở màn hình, cần quy định cách xử lý lúc chờ tải. Thử mạng chậm, yêu cầu thất bại và đổi ngôn ngữ giữa lúc điều hướng. Khách không nên nhìn thấy mã khóa hoặc hành động sai nghĩa chỉ vì tài nguyên đến muộn.
Phân biệt lỗi tải với thiếu nội dung. Lỗi mạng cần phương án chờ hoặc khôi phục; thiếu khóa cần sửa bản dịch. Hai vấn đề phải có người chịu trách nhiệm. Cache nên xác định phiên bản tài nguyên tương thích với mã ứng dụng, thay vì luôn lấy tệp mới nhất mà không kiểm tra.
Không đặt bí mật trong cấu hình trình duyệt. Tài nguyên chỉ chứa nội dung phù hợp với khách. Dịch nhãn quản trị không tạo quyền; phân quyền thuộc ứng dụng.
Bảng kiểm tra trước phát hành nên gồm những gì?
CI, tức tích hợp liên tục, nên phát hiện lỗi tài nguyên có thể kiểm tra lặp lại. Sau kiểm tra cấu trúc và biến, vẫn cần rà soát những trạng thái khách hàng mà việc đọc tệp không chứng minh được.
| Hạng mục | Cách kiểm tra | Bằng chứng lưu lại | Xử lý khi không đạt |
|---|---|---|---|
| Cấu trúc JSON | Parse từng tệp phát hành | Tên tệp và kết quả | Chặn tài nguyên không hợp lệ |
| Thông điệp bắt buộc | Kiểm tra khóa theo hành trình | Báo cáo ngôn ngữ và màn hình | Bổ sung nội dung còn thiếu |
| Biến lúc chạy | So tên biến với đặc tả | Danh sách biến từng câu | Sửa trước khi hợp nhất |
| Số lượng | Chạy với không, một và nhiều | Câu thực tế của mỗi ngôn ngữ | Kiểm tra nhánh và cách diễn đạt |
| Ngữ cảnh | Thử loại đã biết và mặc định | Đầu vào, thông điệp kết quả | Bổ sung câu trung tính |
| Fallback | Cố ý bỏ một câu trong fixture | Câu và ngôn ngữ được chọn | Xác nhận chính sách rồi khôi phục |
| Tải tài nguyên | Giả lập chậm và thất bại | Trạng thái chờ, khôi phục | Sửa điều hướng hoặc tải |
| Bố cục | Thử màn hình hẹp, dữ liệu dài | Ảnh gắn với phiên bản | Sửa câu hoặc giao diện |
| Khả năng tiếp cận | Kiểm tra nhãn và thông báo | Ghi nhận thao tác | Sửa thông điệp hỗ trợ |
| Tương thích phiên bản | Thử cặp mã và tài nguyên hỗ trợ | Mã phiên bản, kết quả | Chặn cặp không tương thích |
Bảng này là tiêu chí đề xuất, không phải tính năng có sẵn trong mọi dự án i18next. Nên dùng dữ liệu thử ổn định, có một vài trường hợp khó: tên dài, mã chứa nhiều hệ chữ, số lượng bằng không và trường tùy chọn bị bỏ trống.
Cấu hình cũng cần được rà soát. returnEmptyString và cách xử lý khóa thiếu ảnh hưởng kết quả trả về; saveMissing cần backend phù hợp.[8] Tiện ích dùng khi phát triển không nên trở thành đường ghi tài nguyên production ngoài kiểm soát.
Nên đồng bộ bản dịch với CI/CD như thế nào?
Gắn mã phát hành với cặp ứng dụng và tài nguyên đã duyệt. Nhóm cần truy ngược được một câu đang hiển thị đến bản dịch, trạng thái phê duyệt và bản build liên quan.
Quy trình thực tế có thể gồm: trích xuất khóa thay đổi, bổ sung ngữ cảnh, dịch phạm vi mới, kiểm tra biến, chạy fixture, rà soát giao diện, phê duyệt rồi phát hành. Nếu cập nhật câu chữ riêng, phải xác nhận những phiên bản ứng dụng nào đọc được tài nguyên đó.
Tách sửa cấu trúc khỏi thay nội dung khi có thể, rồi kiểm tra bản kết hợp. Khi quay lại phiên bản trước, phải khôi phục cặp tương thích.
Khuyến nghị thực tế của LocalizeZone
Hồ sơ gửi bản địa hóa nên nêu ngôn ngữ hỗ trợ, sơ đồ namespace, framework hiển thị, phiên bản thư viện và lịch phát hành. Kèm ảnh màn hình cùng giải thích biến để người dịch hiểu hành động, giới hạn và bước tiếp theo.
Nếu cần rà soát thông điệp Việt–Anh và hành trình sản phẩm, xem dịch vụ bản địa hóa phần mềm. Mẫu tài nguyên có ngữ cảnh và môi trường thử giúp xác định phạm vi công việc rõ hơn một số lượng từ chưa được giải thích.
Câu hỏi thường gặp
Có phải mỗi trang cần một namespace?
Không. Cách chia cần phù hợp trách nhiệm nội dung và nhu cầu tải. Chia quá nhỏ có thể làm trùng câu và tăng công bảo trì.
Các ngôn ngữ có cần cùng bộ hậu tố plural?
Không nên ép giống nhau. Kiểm tra nhóm số lượng của từng ngôn ngữ, thông điệp không có đối tượng nếu cần và kết quả thực tế.
Fallback tiếng Anh có đủ để ra mắt tiếng Việt?
Fallback hỗ trợ hoạt động theo chính sách đã thống nhất. Nó không chứng minh toàn bộ hành trình đã dịch hoặc sẵn sàng nghiệm thu.
Người dịch được đổi tên biến không?
Có thể đổi vị trí biến trong câu theo ngữ pháp. Không tự đổi tên biến đã thống nhất vì ứng dụng có thể không truyền đúng dữ liệu.
Frontend có phải luôn tắt escape?
Không nên áp dụng một cấu hình cho mọi dự án. Cần xem framework, nơi dựng nội dung và kiểm tra kết quả của cả đường hiển thị.
Cần gửi gì cho đơn vị bản địa hóa?
Gửi tệp tài nguyên, quy tắc namespace và khóa, ảnh màn hình, đặc tả biến và tiêu chí nghiệm thu. Không gửi mật khẩu hay hồ sơ khách thật.
Nguồn và phương pháp
Các hành vi thư viện được đối chiếu tài liệu chính thức i18next. Bảng phân trách nhiệm, tiêu chí phát hành và ví dụ báo giá là đề xuất tự xây dựng. Fixture được chạy cục bộ với gói chính thức i18next 26.4.2; chưa kiểm tra trình duyệt, bộ tải backend, React hoặc hệ thống production. Dữ liệu ví dụ không phải hồ sơ khách hàng. Nhật ký nguồn và kết quả kiểm tra được lưu trong hồ sơ biên tập; phần dưới chỉ ghi tên tài liệu, không có liên kết ngoài.
Tài liệu tham khảo
[1] Tài liệu i18next — Namespaces — dự án i18next.
[2] Tài liệu i18next — Best Practices — dự án i18next.
[3] Tài liệu i18next — Interpolation — dự án i18next.
[4] Tài liệu i18next — Plurals — dự án i18next.
[5] Tài liệu i18next — Context — dự án i18next.
[6] Tài liệu i18next — Fallback — dự án i18next.
[7] Tài liệu i18next — Add or Load Translations — dự án i18next.
[8] Tài liệu i18next — Configuration Options — dự án i18next.
Bài viết liên quan
- Hướng dẫn bản địa hóa JSON: Chuỗi, biến và lỗi thường gặp
- So sánh XLIFF, JSON, PO và ARB trong bản địa hóa
- Cách bản địa hóa sản phẩm SaaS cho người dùng Việt Nam
- Bản địa hóa Flutter bằng ARB: Hướng dẫn thực hành
- Checklist 50 mục kiểm tra trước khi ra mắt website tại Việt Nam
- Hướng dẫn UX Writing tiếng Việt cho nút bấm, biểu mẫu và thông báo lỗi