10 lỗi i18n phổ biến và cách bạn tránh chúng

Một nhà phát triển viết nhãn nút trực tiếp trong JSX: <button>Submit Order</button>.

Ứng dụng được phân phối bằng tiếng Anh và hoạt động hoàn hảo. Sáu tháng sau, công ty mở rộng ra Đức.

Đội ngũ i18n phát hiện hơn 2.000 chuỗi được viết cứng. Việc bổ sung lại mất 3 tuần và gây ra 47 lỗi.

Thiết lập một khung i18n (ví dụ next-intl, react-i18next, vue-i18n) trước khi viết thành phần đầu tiên.

Tạo cấu trúc tệp tài nguyên (ví dụ messages/de.json), và tham chiếu tất cả chuỗi qua các khóa dịch như t('checkout.submitButton').

Thêm một quy tắc lint hoặc một hook pre-commit, đánh dấu chuỗi nguyên thủy trong các thành phần UI.

Một tệp dịch chứa tên công ty 'CloudForge Inc.' và thuật ngữ kỹ thuật 'OAuth 2.0 Token' ở dạng chuỗi có thể dịch.

Biên dịch viên Tây Ban Nha dịch 'CloudForge' sang 'ForjaNube' và 'OAuth 2.0 Token' sang 'token OAuth 2.0'.

Kết quả: người dùng sẽ không tìm thấy công ty với tên thật của nó, và các nhà phát triển đọc tài liệu tiếng Tây Ban Nha sẽ bị nhầm lẫn bởi các thuật ngữ chuyên ngành được dịch không quen.

Tạo một từ điển 'Không dịch' liệt kê tất cả tên thương hiệu, tên sản phẩm, pháp nhân và thuật ngữ chuyên ngành cần giữ nguyên.

Sử dụng một namespace riêng hoặc các key đặc biệt cho nội dung không dịch. Nhiều công cụ i18n hỗ trợ các segment 'khóa' mà dịch giả không thể chỉnh sửa.

Thêm chú giải/miêu tả cho các tệp dịch của bạn để giải thích ngữ cảnh: 'Đây là tên thương hiệu — không dịch' hoặc 'Thuật ngữ chuyên ngành — giữ nguyên bằng tiếng Anh'.

Nhà phát triển ghi chú: 'You have ' + count + ' items in your ' + cartType + ' cart' — hoạt động hoàn hảo bằng tiếng Anh.

Người dịch tiếng Đức nhận được ba đoạn riêng biệt và không thể tạo được một câu đúng ngữ pháp, vì trật tự từ cần được thay đổi.

Kết quả: Người dùng tiếng Đức thấy 'Sie haben 5 Artikel in Ihrem Warenkorb Standard' — thô và thiếu chuyên nghiệp.

Thay thế nối chuỗi bằng một khóa tin nhắn duy nhất với chỗ giữ chỗ: 'cart.summary': 'Bạn có {count} mặt hàng trong giỏ hàng '{cartType}''.

Gọi biến như tham số cho hàm dịch: t('cart.summary', { count: 5, cartType: 'Premium' }).

Dịch giả có thể tự do sắp xếp lại: 'Trong giỏ hàng '{cartType}', có {count} mặt hàng' — tiếng Đức đúng ngữ pháp.

Nhà phát triển viết: count + (count === 1 ? ' Datei' : ' Dateien') — xử lý đúng tiếng Đức.

Biên dịch viên tiếng Ba Lan cần 4 dạng: 1 plik, 2-4 pliki, 5-21 plików, 22-24 pliki. Toán tử ba ngôi đơn giản không thể diễn đạt được.

Kết quả: Người dùng Ba Lan thấy '5 pliki' (dạng sai) thay vì '5 plików' (dạng đúng), và ứng dụng trông như bị hỏng.

Định nghĩa tin nhắn với ICU-Syntax: 'fileCount': '{count, plural, one {# Datei} other {# Dateien}}'.

Người dịch cung cấp tất cả các dạng số nhiều cần thiết cho ngôn ngữ của họ. Tiếng Ba Lan: '{count, plural, one {# plik} few {# pliki} many {# plików} other {# pliku}}'.

Thư viện i18n của bạn sẽ tự động chọn dạng đúng tại thời điểm chạy dựa trên các quy tắc CLDR của locale đang hoạt động.

Nhà thiết kế tạo một thanh điều hướng gồm 5 nút, mỗi nút có độ rộng đúng 100px — trông rất tuyệt bằng tiếng Anh.

Phiên dịch tiếng Đức: 'Settings' sẽ thành 'Einstellungen' (13 ký tự so với 8), 'Submit' sẽ thành 'Absenden' (8 so với 6). Navbar vượt quá.

Kết quả: Trên thiết bị di động, các nút xếp chồng lên nhau hoặc văn bản bị cắt, điều này khiến điều hướng cho người dùng Đức trở nên vô dụng.

Thay thế chiều rộng cố định bằng min-width、max-width và Flex-Layouts. Sử dụng CSS Grid hoặc Flexbox để phân bổ không gian động.

Đặt container văn bản vào phá vỡ dòng: sử dụng overflow-wrap: break-word và tránh white-space: nowrap với nội dung có thể dịch.

Test UI bằng giả Localization, mở rộng tất cả chuỗi thêm 40% để mô phỏng trường hợp tệ nhất — trước khi gửi chuỗi cho người dịch.

Nhà phát triển định dạng ngày thành MM/DD/YYYY và giá thành thành $1,234.50 — đúng cho người dùng Mỹ.

Một người dùng Đức nhìn thấy ngày 03/04/2025 và hiểu nó là 3. April (DD/MM/YYYY-Konvention). Der Preis $1,234.50 sieht aus, als sollte es 1.234,50 sein.

Kết quả: Người dùng đặt vé máy bay cho ngày sai và nghi ngờ về định dạng giá. Yêu cầu hỗ trợ tăng 15% ở thị trường Đức.

Thay thế việc định dạng thủ công bằng Intl.DateTimeFormat(locale) cho dữ liệu và Intl.NumberFormat(locale, { style: 'currency', currency }) cho giá.

Lưu dữ liệu ở định dạng ISO 8601 (YYYY-MM-DD) và chỉ định dạng chúng cho hiển thị theo Locale của người dùng.

Kiểm tra các hiển thị ngày/thời gian và số quan trọng với tối thiểu 5 Locale khác nhau: en-US, de-DE, ja-JP, ar-SA và zh-CN để bao phủ các biến thể định dạng chính.

Nhà phát triển sử dụng margin-left: 16px và text-align: left trên toàn bộ ứng dụng — thói quen LTR chuẩn.

Ứng dụng bắt đầu ở Ả Rập Xê-út. Nút quay lại cho thấy tiến về phía trước, sidebars xuất hiện ở phía sai, và dữ liệu số căn chỉnh sai.

Kết quả: Người dùng Ả Rập rời khỏi ứng dụng sau 30 giây. Đội ngũ cần 4 tuần để tiến hành tái cấu trúc CSS khẩn cấp để khắc phục sự cố.

Thay thế mọi thuộc tính CSS vật lý bằng các tương đương logic: margin-left → margin-inline-start, padding-right → padding-inline-end, text-align: left → text-align: start.

Đặt dir trên phần tử gốc HTML dựa trên locale đang hoạt động. Sử dụng :dir(rtl) cho RTL overrides.

Kiểm tra tất cả các icon về ý nghĩa hướng. Thay thế icon định hướng bằng phiên bản đối xứng hoặc dùng transform: scaleX(-1) cho ngữ cảnh RTL.

Một nhà thiết kế tạo banner quảng cáo với văn bản 'Start Your Free Trial' được nhúng trực tiếp vào hình ảnh.

Đội ngũ địa phương hóa dịch tất cả chuỗi UI, nhưng banner trên trang tiếng Đức vẫn hiển thị văn bản tiếng Anh.

Kết quả: Trang đích tiếng Đức có một banner tiếng Anh khiến người dùng khó chịu. Việc tạo banner được địa phương hóa cho 15 ngôn ngữ mất 3 ngày thiết kế và trì hoãn ra mắt.

Áp dụng CSS để đặt văn bản có thể dịch lên trên nền hình ảnh: đặt lớp văn bản ở vị trí tuyệt đối trên container hình ảnh.

Đối với đồ họa thông tin hoặc sơ đồ, hãy sử dụng SVG với các phần tử <text> tham chiếu khóa dịch, thay vì nhúng chuỗi thô.

Đối với ảnh chụp màn hình ứng dụng trong tài liệu tiếp thị, tự động hóa quá trình chụp ảnh màn hình bằng các công cụ như Fastlane (di động) hoặc Playwright (Web), để chụp ảnh cho mỗi locale.

Lập trình viên thêm một khu vực 'Premium Features' mới với 15 khóa dịch. Phiên bản tiếng Anh được phát hành ngay.

Các bản dịch tiếng Pháp vẫn chưa hoàn tất. Trang tiếng Pháp hiển thị các khóa thô: 'premium.feature1.title', 'premium.feature1.description'.

Kết quả: Người dùng Pháp thấy một trang hỏng đầy các key tên phía nhà phát triển. Đội ngũ hỗ trợ nhận được hàng chục báo cáo lỗi.

Thiết lập một chuỗi fallback ngôn ngữ trong cấu hình i18n của bạn: các khóa tiếng Pháp thiếu (fr) sẽ tự động quay về tiếng Anh (en).

Thêm một trình xử lý Missing-Key để ghi lại các khóa chưa được dịch tới hệ thống giám sát của bạn (ví dụ Sentry, Datadog) mà không làm gián đoạn trải nghiệm người dùng.

Xây dựng một bảng điều khiển bao phủ dịch (translation coverage dashboard) theo dõi tỉ lệ hoàn thiện cho từng locale và chặn phát hành khi mức bao phủ dưới ngưỡng (ví dụ 95%).

Nhà phát triển thiết lập cơ sở dữ liệu MySQL với collation latin1 (tiêu chuẩn cũ). Mã nguồn ứng dụng dùng UTF-8.

Người dùng Nhật Bản đăng ký bằng tên thật. Cơ sở dữ liệu lưu '田中太郎' ở dạng bytes bị hỏng.

Kết quả: hồ sơ người dùng hiển thị văn bản bị méo. Tệ hơn nữa: tìm kiếm và sắp xếp cho tất cả các tên CJK sẽ bị hỏng, ảnh hưởng tới hàng nghìn người dùng.

Đặt tất cả các tệp nguồn ở UTF-8 (cấu hình trình soạn thảo và .editorconfig). Thêm <meta charset='UTF-8'> vào HTML và 'Content-Type: application/json; charset=utf-8' vào phản hồi API.

Cấu hình cơ sở dữ liệu ở utf8mb4 (không phải chỉ utf8, là một tập con 3-byte của MySQL). Đặt collation kết nối là utf8mb4_unicode_ci.

Chọn các phông chữ bao phủ hệ chữ mục tiêu của bạn: Latin, Cyrillic, CJK, Ả Rập, Devanagari. Sử dụng hệ thống Font Stacks hoặc Google Fonts với các Subsets ngôn ngữ để tối ưu hóa tải.