ICU MessageFormat: ví dụ bản địa hóa Anh–Việt

Ngày rà soát: 4 tháng 10 năm 2026

Trả lời nhanh

ICU MessageFormat mô tả một thông điệp hoàn chỉnh với biến và điều kiện chọn câu. Khi bản địa hóa, giữ đúng tên biến, cú pháp và ý nghĩa nghiệp vụ; điều chỉnh phần chữ theo tiếng Việt. Trước khi giao tài nguyên, cần xác định thư viện đọc chuỗi và phiên bản đang dùng. Một bản dịch tự nhiên vẫn có thể lỗi khi ứng dụng nhận số lượng hoặc loại khách hàng khác với ví dụ đã xem.

Điểm cần nhớ

Dịch cả thông điệp, tránh ghép các mảnh câu.
Ghi rõ ý nghĩa và kiểu dữ liệu của từng biến.
Phân biệt số chính xác với nhóm ngữ pháp.
Có nhánh dự phòng phù hợp cho giá trị lạ.
Kiểm tra số lượng và số thứ tự riêng biệt.
Đọc kết quả chạy trước khi duyệt giao diện.

Mẫu thông điệp kiểm soát điều gì?

Mẫu chứa phần chữ và các đối số trong ngoặc nhọn. API MessageFormat của ICU cho phép đổi vị trí đối số theo cấu trúc câu.[1] Với Thanks, {name}. và Cảm ơn {name}., dữ liệu cung cấp tên; tài nguyên ngôn ngữ cung cấp lời cảm ơn.

Các ví dụ dưới đây dùng cú pháp ICU MessageFormat truyền thống được thư viện FormatJS đã kiểm tra hỗ trợ. Đây không phải hướng dẫn chuyển đổi sang mọi ngôn ngữ thông điệp khác. Nhãn “hỗ trợ ICU” chưa đủ để kết luận các công cụ chấp nhận toàn bộ lựa chọn định dạng giống nhau.

Với cổng báo giá, kỹ thuật sở hữu quy ước biến; phụ trách nội dung xác nhận ý nghĩa; người rà soát tiếng Việt điều chỉnh câu; QA kiểm tra kết quả. Nếu chỉ đưa chuỗi thô, người dịch phải đoán cả dữ liệu lẫn trạng thái màn hình. Tách rõ trách nhiệm giúp tìm đúng người khi cần sửa.

Người dịch cần biết gì về biến?

Giả sử name là tên hiển thị do khách nhập, không nhất thiết là tên gọi riêng. Ghi chú điều này ngay cạnh chuỗi. Nếu không, bản dịch thân thiện có thể tự thêm danh xưng hoặc giới tính mà hệ thống không biết chắc.

Bảng sau là đề xuất bàn giao của LocalizeZone, không phải quy định bắt buộc của ICU.

Nhu cầu	Thành phần mẫu	Ngữ cảnh giao cho người dịch	Tiêu chí duyệt
Gọi tên khách	`{name}`	Tên hiển thị, có dấu và khoảng trắng	Không đổi biến hoặc đoán giới tính
Báo số tệp	`{count, plural, ...}`	Số nguyên không âm, tệp được chấp nhận	Không đếm tệp đã bị từ chối
Phân biệt doanh nghiệp	`{audience, select, ...}`	Loại yêu cầu do ứng dụng cung cấp	Giá trị lạ có câu chung phù hợp
Báo thứ tự yêu cầu	`{position, selectordinal, ...}`	Số nguyên dương trong chuỗi yêu cầu	Câu thể hiện đúng thứ tự
Hiển thị số	`{count, number}`	Giá trị số và đơn vị nghiệp vụ	Định dạng không đổi đơn vị
Giới thiệu biến mẫu	Ngoặc được quote	Ví dụ hướng dẫn, không phải dữ liệu khách	Ngoặc còn nguyên khi hiển thị

Bảo vệ tên count, position, audience; dịch phần chữ trong cú pháp đã thống nhất. Nếu cần biến mới, yêu cầu sửa hợp đồng tài nguyên với kỹ thuật, không tự thêm vào tệp tiếng Việt.

Cũng cần quyết định cách xử lý giá trị trống và dài. Tên có dấu, tên doanh nghiệp nhiều từ và tên tùy chọn bị bỏ qua đều cần kết quả rõ ràng. Thư viện định dạng không quyết định thay sản phẩm rằng thông tin nào là bắt buộc khi xin báo giá.

Dùng plural và nhánh số chính xác khi nào?

FormatJS phân biệt nhóm số nhiều theo locale với bộ chọn chính xác như =0, đồng thời yêu cầu nhánh other cho cấu trúc plural.[2] Nhánh số không hữu ích khi trạng thái rỗng cần câu riêng.

Thông điệp tiếng Anh do chúng tôi xây dựng:

{count, plural, =0 {No files attached.} one {# file attached.} other {# files attached.}}

Bản tiếng Việt tương ứng:

{count, plural, =0 {Chưa đính kèm tệp.} other {Đã đính kèm # tệp.}}

Trong kiểm tra cục bộ, số 0, 1 và 3 cho kết quả “Chưa đính kèm tệp.”, “Đã đính kèm 1 tệp.” và “Đã đính kèm 3 tệp.” Đây là đầu ra của ví dụ tự xây dựng, không phải nội dung trích nguyên văn tài liệu.

CLDR 48 xếp số lượng tiếng Việt vào other; quy tắc số thứ tự vẫn có one với số 1.[3] Vì vậy không nên nói chung rằng tiếng Việt chỉ có other. Khi chuyển tài nguyên, cũng không cần giữ mọi nhánh số lượng tiếng Anh chỉ để hai tệp trông giống nhau.

Đếm tệp cần khớp trạng thái thật. Nếu khách chọn ba tệp nhưng một tệp bị từ chối, thông điệp thành công không nên báo đã nhận ba tệp. Bản dịch đúng ngữ pháp chưa chắc đúng nghiệp vụ nếu giá trị đưa vào sai.

Select diễn đạt ngữ cảnh nghiệp vụ thế nào?

Dùng bộ chọn khi một loại dữ liệu đã xác định làm thay đổi cả thông điệp. Ví dụ dùng business cho yêu cầu doanh nghiệp, còn other cho câu chung:

{audience, select, business {Your company request is ready for review.} other {Your request is ready for review.}}

Bản tiếng Việt:

{audience, select, business {Yêu cầu của doanh nghiệp đã sẵn sàng để xem xét.} other {Yêu cầu của bạn đã sẵn sàng để xem xét.}}

Giữ nguyên business nếu mã ứng dụng truyền giá trị này. Đổi thành doanhnghiep sẽ thay quy ước dữ liệu dù câu tiếng Việt vẫn nghe đúng. Giá trị không nhận diện được đi vào nhánh chung trong ví dụ.

Nhánh dự phòng không thay việc xác thực dữ liệu. Một loại yêu cầu không thể xuất hiện có thể là lỗi lập trình; hệ thống cần ghi nhận lỗi và hiển thị câu phù hợp. Không tự biến dữ liệu lạ thành mô tả tài khoản hay lời hứa thương mại.

Số thứ tự khác số lượng ra sao?

Bộ đếm yêu cầu có thể cần câu tiếng Anh “This is your 21st request.” Mẫu của chúng tôi là:

This is your {position, selectordinal, one {#st} two {#nd} few {#rd} other {#th}} request.

Cách diễn đạt tiếng Việt được chọn:

{position, selectordinal, one {Đây là yêu cầu thứ nhất của bạn.} other {Đây là yêu cầu thứ {position, number} của bạn.}}

Ví dụ đã kiểm tra gồm 1st, 2nd, 3rd, 11th, 12th, 13th, 21st; tiếng Việt gồm “thứ nhất”, “thứ 2”, “thứ 21”. Nhóm nội dung có thể chọn cách dùng chữ số cho mọi thứ tự, nhưng cần ghi thành quy ước và áp dụng đồng nhất.

Không dùng thứ tự để mô tả mã nhận diện tùy ý. Mã Q-104 chưa chắc là yêu cầu thứ 104 của khách. Nếu hiểu nhầm ý nghĩa dữ liệu, câu đúng ngôn ngữ vẫn truyền đạt sai thông tin sản phẩm.

Lồng điều kiện đến mức nào là hợp lý?

Một thông điệp về tệp của doanh nghiệp có thể kết hợp loại khách và số lượng:

{audience, select, business {{count, plural, one {Your company attached # file.} other {Your company attached # files.}}} other {{count, plural, one {You attached # file.} other {You attached # files.}}}}

Tiếng Việt có thể giữ hai biến bằng cấu trúc đơn giản hơn:

{audience, select, business {Doanh nghiệp đã đính kèm {count, number} tệp.} other {Bạn đã đính kèm {count, number} tệp.}}

Tài liệu ICU khuyến nghị thông điệp nhánh hoàn chỉnh và đề cập đặt select bên ngoài plural lồng.[4] Trong quy trình đề xuất, chúng tôi bổ sung ảnh màn hình và đầu ra mong đợi cho trạng thái khách hàng quan trọng để người rà soát đọc được cả ý nghĩa.

Không lồng điều kiện chỉ vì cú pháp cho phép. Khi trạng thái thanh toán, loại tài khoản, số tệp và tình trạng phê duyệt cùng nằm trong một mẫu, việc duyệt khó hơn. Có thể tách thông điệp theo trạng thái màn hình để trách nhiệm và tiêu chí kiểm tra rõ hơn.

Escape và offset cần ngữ cảnh gì?

Mẫu Enter '{name}' as the example token. đã cho kết quả Enter {name} as the example token. mà không cần truyền name. Đây là ngoặc hiển thị trong hướng dẫn. API MessagePattern của ICU có các chế độ apostrophe; phải xác nhận cách parser thực tế đọc chuỗi.[5]

Quote cú pháp khác với bảo vệ HTML. Kỹ thuật cần xác định cách hiển thị dữ liệu người dùng ở giao diện. Không được để tên khách biến thành mã thực thi chỉ vì tài nguyên đã được gọi là “escape đúng”.

Offset cũng cần ý nghĩa rõ. Ví dụ sau đếm tổng người rà soát, bao gồm người đang đọc thông điệp:

{count, plural, offset:1 =0 {No reviewers assigned.} =1 {You are the only reviewer.} one {You and one other reviewer.} other {You and # other reviewers.}}

Tổng bốn người cho kết quả “You and 3 other reviewers.” Bộ chọn chính xác xét số ban đầu; nhóm plural và # dùng số đã trừ offset. Không áp dụng mẫu nếu hệ thống chỉ đếm những người khác, vì khi đó phép trừ làm sai thông tin.

Kiểm tra nào hữu ích trước khi phát hành?

Chúng tôi chạy 30 kiểm tra cục bộ với intl-messageformat 12.1.2 trên Node 24.18.0. FormatJS mô tả thư viện sử dụng các dịch vụ JavaScript Intl.[6] Kết quả xác nhận mẫu trong bài, không chứng minh bố cục trình duyệt, ứng dụng di động hoặc ICU4J đã được kiểm tra.

Nhóm kiểm tra	Dữ liệu hoặc thay đổi	Bằng chứng cần thấy	Người phụ trách
Biến cơ bản	Tên Lan, hai ngôn ngữ	Câu cảm ơn đầy đủ	Người rà soát
Số lượng	0, 1, 3	Trạng thái rỗng và số tệp đúng	Sản phẩm, QA
Thứ tự tiếng Anh	1, 2, 3, 11, 12, 13, 21	Hậu tố đúng với ví dụ	Kỹ thuật
Thứ tự tiếng Việt	1, 2, 21	Cách viết thống nhất	Người rà soát
Loại dữ liệu lạ	Audience không nhận diện	Câu dự phòng phù hợp	Sản phẩm
Điều kiện lồng	Doanh nghiệp, ba tệp	Câu đầy đủ đúng đối tượng	QA
Ký tự cú pháp	Quote `{name}`, không truyền biến	Ngoặc hiển thị nguyên vẹn	Kỹ thuật
Ý nghĩa offset	Tổng 0, 1, 2, 4 người	Đếm đúng cả người đọc	Sản phẩm, QA
Thiếu biến	Câu cảm ơn không có name	Bắt lỗi trước phát hành	Kỹ thuật
Thiếu dự phòng	Plural không có other	Từ chối tài nguyên sai	Kỹ thuật

Kiểm tra lại sau khi nhập bản dịch, không chỉ trước lúc gửi tệp nguồn. Dùng đúng tài nguyên sẽ phát hành, rồi xem màn hình với giá trị dài, khung hẹp và phông tiếng Việt. Kiểm tra định dạng tự động không thay việc đọc giao diện.

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

Tiếng Việt phải có đủ nhánh tiếng Anh không?

Không. Giữ ý nghĩa dữ liệu và cấu trúc hợp lệ cho tiếng Việt. Nhánh số chính xác có thể vẫn cần dù nhánh ngữ pháp tiếng Anh không cần giữ.

Người dịch có được đổi tên biến không?

Chỉ khi đã thống nhất sửa ứng dụng. Tên biến thường là khóa chính xác được truyền lúc chạy; nên bàn giao danh sách biến cùng tài nguyên.

Nhánh số không luôn bắt buộc à?

Không. Thêm khi trạng thái rỗng cần câu riêng. Nếu câu số lượng chung đủ rõ, có thể dùng cách đơn giản hơn.

Select có xác định giới tính khách không?

Không. Nó chọn theo giá trị được cung cấp. Không suy đoán giới tính hoặc danh xưng từ tên; dùng câu trung tính khi thiếu ngữ cảnh đáng tin cậy.

Mọi thư viện hỗ trợ ICU có giống nhau không?

Không nên giả định. Cần kiểm tra cấu trúc, lựa chọn định dạng và khả năng runtime của thư viện ứng dụng thực sự sử dụng.

Gửi gì để nhận báo giá bản địa hóa?

Gửi tệp mẫu, thư viện định dạng, locale, ghi chú biến, ảnh màn hình và hạn phát hành. Nêu rõ thông điệp nào ảnh hưởng thao tác quan trọng của khách.

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

Tài liệu chính thức ICU, CLDR và FormatJS hỗ trợ các phân biệt kỹ thuật được dẫn số. Mẫu câu, bảng bàn giao và đề xuất kiểm tra do chúng tôi xây dựng cho luồng báo giá giả định. Đã chạy 30 kiểm tra chọn lọc; chưa kiểm tra triển khai khách hàng, giao diện nhiều trình duyệt hoặc runtime ICU4J.

Tài liệu tham khảo

[1] Unicode ICU — MessageFormat API, mẫu và thứ tự đối số. [2] FormatJS — ICU Message Syntax, bộ chọn và plural. [3] Unicode CLDR 48 — Language Plural Rules, mục tiếng Việt. [4] Unicode ICU — Formatting Messages, thông điệp đầy đủ và lồng. [5] Unicode ICU — MessagePattern API, chế độ apostrophe và parser. [6] FormatJS — Intl MessageFormat, runtime và API định dạng.

Chuẩn bị rà soát tài nguyên

Gửi tệp tiêu biểu tại biểu mẫu báo giá hoặc trao đổi ở trang liên hệ. Dịch vụ bản địa hóa phần mềm hỗ trợ phối hợp câu chữ, quy ước tài nguyên và QA ngôn ngữ trước đợt phát hành.

Giải thích ICU MessageFormat qua các ví dụ bản địa hóa