Cách Dịch Tệp JSON i18next trong React & Next.js (2026)
Bạn vừa hoàn thành một ứng dụng React cần được triển khai bằng 12 ngôn ngữ vào thứ Sáu tới. Các tệp ngôn ngữ của bạn nằm trong public/locales/en/common.json, bạn có 340 khóa cho mỗi ngôn ngữ, và các token bên trong chuỗi của bạn trông như {{userName}} và {{count}} nằm rải rác khắp các đối tượng lồng nhau. Bạn dán JSON vào ChatGPT, và nó trả về {{ nombreUsuario }}, các khoảng trắng thừa, và một nửa số khóa số nhiều bị đổi tên. Ứng dụng của bạn bị lỗi khi build.
Nếu bạn đã từng thử tự động dịch JSON i18next, bạn sẽ hiểu nỗi đau này. Định dạng JSON rất linh hoạt, đó chính là lý do tại sao hầu hết các công cụ dịch thuật làm hỏng nó. Vấn đề thực sự không phải là chất lượng của mô hình ngôn ngữ - mà là các công cụ AI thông thường không hiểu các quy tắc cấu trúc của i18next.
Hướng dẫn này sẽ giải thích điều gì khiến JSON i18next khác biệt so với các định dạng ngôn ngữ khác, tại sao các phương pháp dịch thuật ngây thơ lại làm hỏng các ứng dụng React và Next.js, và cách tự động dịch một cách an toàn trên hàng chục ngôn ngữ mà không cần xem xét thủ công từng khóa.
i18next JSON là gì và Tại sao Dịch thuật Lại Khó khăn
i18next là thư viện i18n được sử dụng rộng rãi nhất trong hệ sinh thái JavaScript. Nó cung cấp sức mạnh cho React (react-i18next), Next.js (next-i18next, App Router next-intl), Vue và các dịch vụ backend Node. Nó lưu trữ các chuỗi có thể dịch được trong các tệp JSON phẳng hoặc lồng nhau, mỗi tệp cho một ngôn ngữ.
Một tệp điển hình trông như thế này:
{
"welcome": "Welcome, {{userName}}!",
"cart": {
"empty": "Your cart is empty",
"items_one": "{{count}} item in your cart",
"items_other": "{{count}} items in your cart"
},
"errors": {
"network": "Network error. <strong>Please retry</strong>."
}
}
Điều này có vẻ đơn giản, nhưng có ba điều khiến việc dịch nó bằng AI tổng quát trở nên nguy hiểm.
Các Token Nội suy Có tính Cấu trúc, không phải Văn bản
Chuỗi {{userName}} không phải là một từ - nó là một trình giữ chỗ mà runtime thay thế bằng dữ liệu. Thêm một khoảng trắng ({{ userName }}), đổi tên nó, hoặc dịch định danh bên trong và runtime sẽ lỗi ngầm hoặc ném ngoại lệ. Một số dịch giả đã "nhiệt tình" chuyển đổi {{count}} thành {{conteo}} trong tiếng Tây Ban Nha. Ứng dụng của bạn giờ đây cố gắng nội suy một biến không tồn tại và hiển thị trình giữ chỗ thô cho người dùng của bạn.
Các Khóa Số nhiều là các Hậu tố "Thần kỳ"
i18next phát hiện số nhiều bằng các hậu tố: _zero, _one, _two, _few, _many, _other. Đây không phải là các chuỗi tùy ý - chúng phải khớp với các danh mục số nhiều CLDR cho ngôn ngữ mục tiêu. Tiếng Anh chỉ sử dụng _one và _other. Tiếng Nga, tiếng Ả Rập và tiếng Ba Lan sử dụng tới sáu danh mục. Nếu dịch giả của bạn bỏ _other hoặc đổi tên nó, chuỗi dự phòng sẽ bị hỏng.
Các Khóa Lồng nhau Phải Giữ nguyên vẹn
Không giống như các tệp .po của Gettext, vốn là các cặp khóa-giá trị phẳng, các tệp i18next có thể lồng nhau tùy ý. Một dịch giả cẩu thả có thể làm phẳng cấu trúc, thay đổi tên khóa để khớp với văn bản đã dịch, hoặc sắp xếp lại các đối tượng. Lời gọi t('cart.items_other') trong mã của bạn sẽ không còn được giải quyết nữa.
Các Giải pháp Tồi mà Nhà phát triển Thường thử Đầu tiên
Mọi nhóm đều trải qua cùng một chu kỳ thất bại ba giai đoạn trước khi họ đầu tư vào một giải pháp thực sự.
Giai đoạn Một: Dán vào ChatGPT
Bạn sao chép 200 khóa vào ChatGPT, hỏi "dịch JSON này sang tiếng Tây Ban Nha," và dán kết quả trở lại. Nó hoạt động cho 180 khóa. Hai mươi khóa có khoảng trắng được thêm vào bên trong {{...}}, ba khóa có hậu tố số nhiều được viết lại, và một thẻ <strong> bị dịch thành <fuerte>. Bản dựng của bạn hoặc thất bại hoặc âm thầm gửi các chuỗi bị lỗi đến môi trường production.
Giai đoạn Hai: API Dịch của Google
Bạn kết nối API REST của Google Translate, lặp qua JSON của bạn, và gửi từng giá trị. Tốc độ tuyệt vời. Chất lượng thì không. API của Google xử lý mỗi chuỗi một cách riêng lẻ - không có ngữ cảnh về ứng dụng của bạn, không hiểu rằng {{count}} là một trình giữ chỗ, không nhận thức được rằng khóa cart.empty khác với cart.items_one. Bạn vẫn cần xem xét thủ công từng khóa.
Giai đoạn Ba: Các Nền tảng TMS Thương mại
Bạn đăng ký một hệ thống quản lý dịch thuật. Họ tính phí theo từ, yêu cầu tích hợp GitHub, và ràng buộc bạn vào các gói thuê bao hàng tháng. Đối với một dự án phụ hoặc một ứng dụng độc lập, chi phí nhanh chóng trở nên không khả thi - và bạn vẫn gặp phải các vấn đề hỏng trình giữ chỗ tương tự nếu công cụ của họ không phân tích cú pháp định dạng i18next một cách cụ thể.
Các chế độ lỗi tương tự cũng xuất hiện trong các quy trình làm việc của Gettext. Hướng dẫn của chúng tôi về cách dịch tệp .po mà không làm hỏng các biến mã đề cập đến vấn đề tương tự cho WordPress và các stack dựa trên Gettext khác.
Cách Tiếp cận An toàn: Dịch thuật Nhận biết Cú pháp
Cách duy nhất đáng tin cậy để dịch i18next JSON ở quy mô lớn là với một công cụ phân tích cú pháp định dạng trước, khóa cú pháp, và chỉ gửi văn bản có thể dịch được đến AI.
Đây là những gì xử lý nhận biết cú pháp làm ẩn bên dưới:
- Phân tích cú pháp JSON thành một cây trừu tượng, bảo toàn các đường dẫn khóa và lồng ghép.
- Xác định các token nội suy (
{{name}},{{count, number}},{{date, datetime}}) và thay thế chúng bằng các ID trình giữ chỗ. - Xác định các thẻ HTML bên trong các thành phần Trans (
<0>,<strong>,<br/>) và khóa chúng. - Phát hiện các khóa số nhiều bằng hậu tố và ánh xạ chúng tới các quy tắc CLDR cho ngôn ngữ mục tiêu.
- Chỉ gửi văn bản đã được làm sạch đến LLM với ngữ cảnh về đường dẫn khóa.
- Chèn lại các token và thẻ gốc vào đúng vị trí của chúng.
- Xác thực đầu ra - nếu bất kỳ trình giữ chỗ nào bị thiếu hoặc sai định dạng, sẽ hoàn nguyên về nguồn.
Đây là nguyên tắc tương tự giúp dịch PO dựa trên đám mây an toàn. Nếu bạn tò mò về kiến trúc cơ bản, bài viết so sánh chất lượng dịch AI của chúng tôi sẽ phân tích cách các LLM khác nhau xử lý các ràng buộc này.
Từng bước: Dịch i18next JSON bằng SimplePoTranslate
SimplePoTranslate hỗ trợ i18next JSON nguyên bản trên các gói Pro và Lifetime. Gói miễn phí hiện bao gồm .po và .pot - nâng cấp hoặc sử dụng bản dùng thử để truy cập JSON.
1. Chuẩn bị Tệp Nguồn của Bạn
Sử dụng tệp tiếng Anh (hoặc ngôn ngữ nguồn) của bạn làm tệp chính. Đảm bảo đó là JSON hợp lệ và chứa tất cả các khóa mà ứng dụng của bạn sử dụng. Một lỗi phổ biến là để lại các khóa lỗi thời hoặc không sử dụng, điều này làm tiêu tốn hạn mức dịch thuật của bạn cho các chuỗi mà bạn sẽ không bao giờ hiển thị.
# From your project root
cp public/locales/en/common.json ~/Desktop/common.json
2. Tải lên SimplePoTranslate
Đăng nhập vào bảng điều khiển của bạn, nhấp vào Bản dịch Mới, và tải lên common.json. Nền tảng tự động phát hiện định dạng i18next. Chọn ngôn ngữ mục tiêu của bạn từ 41 ngôn ngữ được hỗ trợ, chọn một sắc thái (chuyên nghiệp, thân mật, tiếp thị), và gửi.
3. Để Công cụ Hoạt động
Bên dưới, tệp được phân tích cú pháp, được chia thành các lô an toàn, và dịch song song. Các token nội suy được khóa. Các hậu tố số nhiều được bảo toàn và ánh xạ tới các quy tắc CLDR của ngôn ngữ mục tiêu. HTML bên trong các thành phần Trans vẫn nguyên vẹn.
4. Tải xuống Tệp ZIP
Bạn nhận lại một tệp ZIP chứa JSON đã dịch cộng với các định dạng thay thế (.php cho ứng dụng PHP, .po cho khả năng tương thích đa công cụ). Kéo JSON vào public/locales/es/common.json và triển khai lại.
unzip common_es.zip
mv common.json public/locales/es/common.json
npm run build
5. Lặp lại hoặc Xử lý theo Lô
Đối với tất cả 12 ngôn ngữ mục tiêu, hãy gửi 12 công việc. Hạn mức gói Pro bao gồm hàng chục ứng dụng SaaS điển hình. Đối với các monorepo với nhiều tệp namespace, tải lên từng tệp riêng biệt hoặc xử lý chúng theo trình tự.
Tích hợp Bản dịch Trở lại Ứng dụng của Bạn
Khi bạn đã có các tệp JSON đã dịch, việc tích hợp là phần dễ dàng. Một vài điều cần lưu ý:
- Xác minh các danh mục số nhiều. Chạy một bài kiểm tra nhanh cho mỗi ngôn ngữ: hiển thị một thành phần với
count={0},count={1},count={5}và xác nhận cả ba đều tạo ra chuỗi chính xác. - Kiểm tra các ngôn ngữ RTL. Nếu bạn dịch sang tiếng Ả Rập, tiếng Do Thái hoặc tiếng Ba Tư, giao diện người dùng của bạn cần CSS nhận biết RTL. Hướng dẫn dịch RTL cho WordPress của chúng tôi bao gồm các mẫu CSS cũng áp dụng cho các ứng dụng React.
- Thiết lập chuỗi dự phòng. Cấu hình i18next để dự phòng về tiếng Anh nếu một khóa bị thiếu, để trạng thái giữa quá trình triển khai không làm ứng dụng bị lỗi đối với người dùng.
- Khóa tệp nguồn của bạn trong CI. Thêm một kiểm tra từ chối các PR khi
en/common.jsonthay đổi mà không tạo lại các ngôn ngữ khác. Lệch dịch thuật là nguyên nhân lớn nhất gây ra lỗi i18n trong sản phẩm.
Đối với các nhóm triển khai trên React, Next.js và phía máy chủ, việc tạo ra mọi định dạng từ một nguồn duy nhất là một lợi thế lớn. Bài viết của chúng tôi về một tệp đầu vào, năm định dạng đầu ra giải thích tại sao đầu ra đa định dạng lại quan trọng cho việc bảo trì dài hạn.
Khi JSON không Đủ: Xử lý các Trường hợp Phức tạp
Một vài trường hợp đặc biệt cần được chăm sóc thêm.
Định dạng Tin nhắn ICU
Nếu dự án của bạn sử dụng cú pháp ICU ({count, plural, one {1 item} other {# items}}), i18next coi nó là nội suy nhưng cấu trúc phức tạp hơn. Đảm bảo công cụ dịch thuật của bạn nhận diện các tham số ICU và không dịch các tên danh mục như one, other, hoặc các định danh định dạng như plural, number, date.
Thành phần Trans với các Node React
<Trans> hiển thị các thành phần React bên trong các chuỗi đã dịch, được lập chỉ mục (<0>, <1>). Người dịch phải bảo toàn thứ tự thẻ chính xác. Khóa cú pháp của SimplePoTranslate xử lý điều này, nhưng nếu bạn sử dụng một công cụ khác, hãy xác minh trước khi triển khai.
Các Tệp Namespace
Các ứng dụng lớn chia ngôn ngữ thành các namespace: common.json, dashboard.json, checkout.json. Dịch từng tệp một cách độc lập - không hợp nhất chúng. Chất lượng ngữ cảnh cao hơn khi các đường dẫn khóa của mỗi namespace được giữ trong phạm vi.
Tổng kết
Dịch i18next JSON cho một ứng dụng React hoặc Next.js không phải là việc chọn mô hình AI tốt nhất. Đó là việc tôn trọng các quy tắc cấu trúc của định dạng: các nội suy, hậu tố số nhiều, khóa lồng nhau và thẻ HTML phải được bảo toàn trong suốt quá trình. Các công cụ AI thông thường coi JSON là văn bản không có cấu trúc. Các công cụ nhận biết cú pháp phân tích cú pháp nó thành dữ liệu có cấu trúc và chỉ chạm vào các bề mặt có thể dịch được.
Nếu bạn đang triển khai một ứng dụng đa ngôn ngữ và đã từng sao chép-dán JSON vào các giao diện trò chuyện, bạn đã biết chi phí: hàng giờ xem xét thủ công cho mỗi ngôn ngữ, các lỗi sản xuất ngẫu nhiên, và một chồng ngày càng tăng các dạng số nhiều bị hỏng. Một quy trình nhận biết định dạng sẽ loại bỏ mọi chế độ lỗi đó.
Sẵn sàng dịch các tệp JSON i18next của bạn một cách an toàn? Hãy thử SimplePoTranslate miễn phí - không yêu cầu thẻ tín dụng. Tải lên một lần, triển khai bằng 41 ngôn ngữ.