Thêm đa ngôn ngữ vào ứng dụng Next.js của bạn.
Dịch các tệp địa phương, nội dung Markdown và trang HTML của bạn qua một lần gọi API duy nhất. Hoạt động với App Router, next-intl và bất kỳ thiết lập định tuyến i18n nào.
Next.js cung cấp cho bạn định tuyến. Nó không cung cấp bản dịch.
Next.js App Router có hỗ trợ tích hợp xuất sắc cho định tuyến dựa trên địa phương. Các thư viện như next-intl giúp quản lý tệp dịch và chuyển đổi địa phương trở nên đơn giản. Điều mà chúng không giải quyết là bản dịch thực tế — ai đó phải tạo nội dung đã được dịch cho mọi ngôn ngữ, và người đó thường là bạn. Với hầu hết các nhóm, quy trình làm việc là sao chép JSON tiếng Anh vào DeepL, sửa định dạng bị hỏng, dán kết quả trở lại, lặp lại cho từng ngôn ngữ. Nó chậm, dễ sai sót và không mở rộng được.
Quy trình phổ biến nhất là viết tất cả chuỗi giao diện người dùng bằng tiếng Anh trong mã nguồn, sau đó dịch tệp messages.json cho từng ngôn ngữ mục tiêu. Về lý thuyết điều này đơn giản. Thực tế, việc giữ đồng bộ hơn 10 tệp địa phương với các thay đổi nguồn trở thành điểm đau lặp đi lặp lại. Mỗi khi bản sao tiếng Anh thay đổi, mọi tệp địa phương đều cần cập nhật. Khi sử dụng API dịch tiêu chuẩn cho việc này, tên khóa bị hỏng, các biến giữ chỗ bị dịch, và cấu trúc JSON lệch giữa các địa phương — gây ra lỗi thời gian chạy tinh vi khó truy tìm.
PolyLingo phù hợp với thiết lập i18n Next.js hiện có của bạn.
Nếu bạn sử dụng next-intl hoặc bất kỳ thư viện i18n nào khác, các thông điệp của bạn đã ở dạng JSON. PolyLingo lấy JSON đó, gửi qua mô hình dịch thuật và trả về các bản dịch cho mọi ngôn ngữ mục tiêu — với các khóa giữ nguyên, cấu trúc lồng nhau không thay đổi và các giá trị chuỗi được dịch chính xác. Bạn có thể gọi nó từ script xây dựng, webhook hoặc giao diện PolyLingo. Kết quả sẽ được đặt trực tiếp vào thư mục messages của bạn.
Quy trình: viết tệp messages.json tiếng Anh của bạn. Chạy một script duy nhất gọi API PolyLingo với tệp nguồn và tất cả mã ngôn ngữ mục tiêu. Nhận một tệp JSON dịch cho mỗi ngôn ngữ, với cấu trúc giống hệt. Ghi mỗi tệp vào thư mục messages/. Cam kết. Xong.
Đối với các trang web nhiều nội dung với Markdown trong CMS (Sanity, Contentful), cách tiếp cận tương tự áp dụng cho nội dung: xuất dưới dạng Markdown hoặc HTML, dịch, ghi lại vào CMS qua API của nó. Toàn bộ quy trình có thể chạy như một bước xây dựng hoặc kích hoạt webhook.
// This repository: frontend/scripts/translate-messages.mjs
// Chunks large namespaces (e.g. home) so the model stays within output limits.
//
// export POLYLINGO_API_KEY=pl_xxx
// npm run i18n:polylingo
//
// Writes messages/es.json, fr.json, … from messages/en.json via POST /v1/translate
// with format: "json". See MARKETING_I18N.md for options and CI notes.
//
// Minimal one-shot pattern (fine for small message files):
//
// const source = readFileSync('./messages/en.json', 'utf8')
// const { translations } = await fetch(apiUrl + '/translate', {
// method: 'POST',
// headers: { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
// body: JSON.stringify({
// content: source, format: 'json', source: 'en',
// targets: ['es', 'fr', 'de'], model: 'standard',
// }),
// }).then((r) => r.json())
//
// for (const [lang, raw] of Object.entries(translations)) {
// const obj = typeof raw === 'string' ? JSON.parse(raw) : raw
// writeFileSync(`./messages/${lang}.json`, JSON.stringify(obj, null, 2))
// }// i18n.ts (next-intl v4)
import { getRequestConfig } from 'next-intl/server'
export const locales = [
'en', 'ar', 'bn', 'cs', 'da', 'de', 'el', 'es', 'fa', 'fi',
'fr', 'he', 'hi', 'id', 'it', 'ja', 'ko', 'ms', 'nl', 'no',
'pl', 'pt', 'ru', 'sv', 'sw', 'th', 'tr', 'uk', 'vi', 'zh',
] as const
export type Locale = (typeof locales)[number]
export default getRequestConfig(async ({ requestLocale }) => {
const locale = await requestLocale
return {
locale,
messages: (await import(`./messages/${locale}.json`)).default,
}
})// package.json
{
"scripts": {
"dev": "next dev",
"build": "next build",
"i18n:polylingo": "node scripts/translate-messages.mjs",
"translate:build": "npm run i18n:polylingo && next build"
}
}Tại sao PolyLingo phù hợp với quy trình i18n Next.js
- ✓Dịch trực tiếp các tệp messages/*.json — các khóa luôn được giữ nguyên
- ✓Dịch nội dung Markdown cho bài viết blog và trang tài liệu
- ✓Hoạt động với next-intl, next-i18next và các thiết lập tùy chỉnh
- ✓REST API tích hợp với script xây dựng và webhook CMS
- ✓Tất cả 36 ngôn ngữ trong một yêu cầu duy nhất
- ✓Gói miễn phí — 100.000 token mỗi tháng
- ✓Kho này tự sử dụng quy trình làm việc: npm run i18n:polylingo tái tạo các địa phương marketing từ messages/en.json (xem MARKETING_I18N.md).
- ✓Hoạt động với App Router và Pages Router
- ✓Tệp đầu ra sẵn sàng để cam kết — không cần định dạng lại
Thiết lập đa ngôn ngữ trong ứng dụng Next.js của bạn
Thiết lập next-intl với tệp thông điệp tiếng Anh của bạn
Cài đặt next-intl và cấu hình i18n.ts cùng middleware. Viết tất cả chuỗi giao diện người dùng trong messages/en.json. Cấu trúc tệp theo nhu cầu ứng dụng — phẳng hoặc lồng nhau. Đây sẽ là nguồn dữ liệu duy nhất của bạn.
Chạy script dịch
Sử dụng API JSON PolyLingo từ một script Node nhỏ (xem mã phía trên). Trong monorepo này, chạy npm run i18n:polylingo từ frontend/ với POLYLINGO_API_KEY được thiết lập — nó chia nhỏ namespace lớn để đảm bảo độ tin cậy. Các lần chạy điển hình mất chưa đến một phút cho toàn bộ gói marketing.
Cam kết các tệp địa phương và triển khai
Các tệp địa phương được tạo ra là JSON hợp lệ với cấu trúc giống hệt nguồn. Cam kết chúng vào repo của bạn. Thêm script dịch vào pipeline CI để giữ các địa phương đồng bộ với mọi thay đổi nội dung.
Các trường hợp sử dụng đa ngôn ngữ Next.js
Ứng dụng SaaS và bảng điều khiển
Dịch toàn bộ thư viện chuỗi giao diện người dùng trong một lần chạy script. Hỗ trợ tất cả các tính năng định dạng của next-intl — ngày tháng, số, số nhiều — vì cấu trúc JSON được giữ nguyên chính xác.
Trang nội dung và blog
Đối với các trang Next.js nhiều nội dung sử dụng Sanity hoặc Contentful, dùng PolyLingo để dịch nội dung trang cũng như chuỗi giao diện người dùng — cùng API, cùng đảm bảo giữ nguyên định dạng.
Thương mại điện tử với các biến thể vùng miền
Dịch tên sản phẩm, mô tả, trang danh mục và giao diện thanh toán. Dùng mô hình Nâng cao cho bản sao marketing nơi giọng điệu thương hiệu quan trọng, mô hình Tiêu chuẩn cho chuỗi giao diện chức năng.
Câu hỏi thường gặp
Điều này có hoạt động với Next.js App Router không?
Có. Tích hợp PolyLingo chỉ là một script đọc và ghi các tệp JSON — không phụ thuộc vào nội bộ Next.js. Nó hoạt động với App Router, Pages Router hoặc bất kỳ framework nào. Ví dụ cấu hình next-intl sử dụng API v4 với requestLocale, tương thích với Next.js 13, 14 và 15.
Nếu messages.json của tôi thay đổi thường xuyên thì sao?
Mẫu đề xuất là thêm script dịch vào pipeline CI/CD của bạn, kích hoạt khi có thay đổi ở messages/en.json. Điều này giữ tất cả các tệp địa phương đồng bộ tự động. Với các nhóm thay đổi bản sao thường xuyên, điều này hoàn toàn ngăn ngừa lệch địa phương.
PolyLingo có hoạt động với next-i18next cũng như next-intl không?
Có. next-i18next sử dụng cùng cấu trúc JSON địa phương. Script dịch hoạt động giống hệt — chỉ cần trỏ đến thư mục public/locales/en/ và ghi kết quả ra các thư mục địa phương khác. Định dạng JSON tương thích như nhau.
Còn nội dung động không có trong tệp messages thì sao?
Nội dung động — bài blog, mô tả sản phẩm, nội dung do người dùng tạo — nên được dịch ở tầng dữ liệu, hoặc trong CMS của bạn hoặc qua script xây dựng xử lý nội dung trước khi đến Next.js. PolyLingo xử lý Markdown, HTML và văn bản thuần một cách hiệu quả cho mục đích này.
Tôi có thể chỉ dịch các chuỗi đã thay đổi kể từ lần chạy trước không?
Dịch gia tăng (chỉ dịch các khóa thay đổi) đang trong kế hoạch phát triển. Hiện tại script dịch lại toàn bộ tệp. Với hầu hết tệp thông điệp (dưới 20KB), điều này đủ nhanh để chạy mỗi lần cam kết. Với tệp rất lớn, chia theo namespace là cách khuyến nghị.
Có cách nào xem lại bản dịch trước khi đưa vào sản xuất không?
Mẫu đề xuất là cam kết các tệp địa phương đã dịch vào nhánh hoặc PR riêng để xem xét trước khi gộp vào nhánh chính. Đây là thực hành chuẩn cho các nhóm cần đánh giá chất lượng dịch thuật bằng con người. PolyLingo tạo bản dịch lần đầu tốt — với hầu hết chuỗi giao diện, đầu ra mô hình Tiêu chuẩn không cần chỉnh sửa.
Hướng dẫn liên quan
Dịch tệp địa phương đầu tiên của bạn trong chưa đầy 5 phút.
Khóa API miễn phí. Không cần thẻ tín dụng. Dán JSON thông điệp của bạn và xem kết quả ngay lập tức.
Lấy khóa API của bạnScript dịch mất 5 phút để thiết lập. Gói miễn phí — không cần thẻ tín dụng.