Giới thiệu

🎯 Mô-đun này làm gì?

Mô-đun Locales cho phép bạn quản lý hỗ trợ đa ngôn ngữ trong dự án OneEntry của bạn - lấy danh sách ngôn ngữ có sẵn, phát hiện ngôn ngữ của người dùng và xây dựng các ứng dụng quốc tế hóa phục vụ nội dung bằng nhiều ngôn ngữ khác nhau.

Hãy nghĩ về nó như là trình quản lý ngôn ngữ của bạn - thay vì mã hóa cứng ngôn ngữ trong ứng dụng của bạn, bạn lấy danh sách các ngôn ngữ đang hoạt động từ OneEntry một cách động, cho phép nội dung của bạn tự động thích ứng với các ngôn ngữ khác nhau (Tiếng Anh, Tiếng Nga, Tiếng Ả Rập, Tiếng Tây Ban Nha, v.v.).

📖 Giải thích đơn giản

Trong các ứng dụng hiện đại, bạn thường cần hỗ trợ nhiều ngôn ngữ:

🌍 Trang thương mại điện tử - Phục vụ khách hàng ở các quốc gia khác nhau (Tiếng Anh, Tiếng Pháp, Tiếng Đức)
📱 Ứng dụng di động - Thích ứng giao diện với ngôn ngữ của thiết bị người dùng
🌐 Trang web - Hiển thị nội dung bằng ngôn ngữ ưa thích của khách truy cập
📚 Tài liệu - Cung cấp trợ giúp bằng nhiều ngôn ngữ
🎮 Trò chơi - Dịch giao diện và nội dung

Vấn đề với việc mã hóa cứng ngôn ngữ:

Vấn đề:

🔄 Khó cập nhật - Cần phải triển khai lại để thêm ngôn ngữ mới
🌍 Không đồng bộ - Ngôn ngữ ứng dụng có thể khác với ngôn ngữ CMS
❌ Sự không khớp trong dịch thuật - Nội dung tồn tại trong CMS nhưng không có trong ứng dụng
🔧 Bảo trì thủ công - Cập nhật mã mỗi khi ngôn ngữ thay đổi

Giải pháp Locales:

Lợi ích:

🔄 Luôn đồng bộ - Ngôn ngữ khớp với những gì được cấu hình trong OneEntry
🌍 Động - Thêm/xóa ngôn ngữ mà không cần thay đổi mã
✅ Đã xác thực - Chỉ hiển thị ngôn ngữ có nội dung
🎯 Tập trung - Quản lý ngôn ngữ ở một nơi

✨ Khái niệm chính

Locale là gì?

Một locale là sự kết hợp giữa ngôn ngữ và khu vực xác định cách nội dung được hiển thị:

Mã ngôn ngữ - Mã ngôn ngữ ISO 639-1 (ví dụ: en, ru, ar)
Mã khu vực - Mã quốc gia ISO 3166-1 (ví dụ: US, GB, RU)
Định danh locale - Định dạng kết hợp: language_REGION (ví dụ: en_US, ru_RU, ar_SA)

Ví dụ:

Mã Locale	Ngôn ngữ	Khu vực	Mô tả
`en_US`	Tiếng Anh	Hoa Kỳ	Tiếng Anh Mỹ
`en_GB`	Tiếng Anh	Vương quốc Anh	Tiếng Anh Anh
`ru_RU`	Tiếng Nga	Nga	Tiếng Nga
`es_ES`	Tiếng Tây Ban Nha	Tây Ban Nha	Tiếng Tây Ban Nha Châu Âu
`es_MX`	Tiếng Tây Ban Nha	Mexico	Tiếng Tây Ban Nha Mexico
`ar_SA`	Tiếng Ả Rập	Ả Rập Saudi	Tiếng Ả Rập (Ả Rập Saudi)
`fr_FR`	Tiếng Pháp	Pháp	Tiếng Pháp
`de_DE`	Tiếng Đức	Đức	Tiếng Đức

Cấu trúc Locale

Mỗi locale trong OneEntry có:

{
  id: 146,                      // ID duy nhất
  shortCode: 'en',              // mã ngắn
  code: 'en_US',                // mã đầy đủ
  name: 'English (USA)',        // tên
  nativeName: 'English (USA)',  // tên bản địa
  isActive: true,               // đang hoạt động
  image: null,                  // hình ảnh
  position: 1,                  // vị trí
}

Tại sao sử dụng mô-đun Locales?

Lợi ích	Mô tả
Hỗ trợ đa ngôn ngữ	Phục vụ nội dung bằng ngôn ngữ ưa thích của người dùng
Danh sách ngôn ngữ động	Ngôn ngữ đồng bộ với cấu hình OneEntry
Phát hiện locale mặc định	Tự động xác định ngôn ngữ mặc định
Lọc locale đang hoạt động	Chỉ hiển thị ngôn ngữ đã kích hoạt
Quản lý tập trung	Cập nhật ngôn ngữ trong bảng điều khiển quản trị, không phải mã
Trải nghiệm người dùng	Cho phép người dùng chọn ngôn ngữ của họ

Các trường hợp sử dụng phổ biến

Trường hợp sử dụng	Mô tả	Ví dụ
Trình chọn ngôn ngữ	Menu thả xuống để chuyển đổi ngôn ngữ	Đầu trang web với cờ ngôn ngữ
Địa phương hóa nội dung	Lấy nội dung bằng ngôn ngữ của người dùng	Bài viết blog bằng tiếng Anh hoặc tiếng Nga
Định tuyến	Cấu trúc URL theo ngôn ngữ	`/en/about`, `/ru/about`
Logic dự phòng	Hiển thị ngôn ngữ mặc định nếu thiếu bản dịch	Hiển thị tiếng Anh nếu tiếng Tây Ban Nha không có
Sở thích của người dùng	Nhớ lựa chọn ngôn ngữ của người dùng	Lưu locale trong cookies/localStorage

📋 Những điều bạn cần biết

Locales được cấu hình trong bảng điều khiển quản trị

Bạn không thể tạo locales qua SDK - chúng được cấu hình trong bảng điều khiển quản trị OneEntry:

Bảng điều khiển quản trị OneEntry → Cài đặt → Ngôn ngữ → Thêm ngôn ngữ → Chọn locale

SDK được sử dụng để lấy thông tin locale, không phải để tạo locales.

Locales đang hoạt động và không hoạt động

Không phải tất cả các locales đã cấu hình đều có thể đang hoạt động:

Trạng thái	Ý nghĩa	Khi nào sử dụng
Đang hoạt động (`isActive: true`)	Locale được kích hoạt và có nội dung	Hiển thị trong trình chọn ngôn ngữ
Không hoạt động (`isActive: false`)	Locale bị vô hiệu hóa hoặc đang chuẩn bị	Ẩn khỏi người dùng

Thực hành tốt nhất: Luôn lọc theo isActive khi xây dựng trình chọn ngôn ngữ

Locale mặc định

Mỗi dự án OneEntry có một locale mặc định:

Locale mặc định (isDefault: true) - Ngôn ngữ chính
Được sử dụng khi không có locale nào được chỉ định
Dự phòng khi thiếu bản dịch

Mã Locale và Mã ngắn

Mỗi locale có hai định dạng mã:

Trường	Định dạng	Ví dụ	Sử dụng cho
`code`	`language_REGION`	`en_US`, `ru_RU`	Nhận diện locale đầy đủ
`shortCode`	`language`	`en`, `ru`	Nhận diện chỉ ngôn ngữ

📊 Bảng tham khảo nhanh

Phương thức	Mô tả	Trường hợp sử dụng
getLocales()	Lấy tất cả các locales (đang hoạt động và không hoạt động)	Lấy các ngôn ngữ có sẵn

❓ Câu hỏi thường gặp (FAQ)

Làm thế nào để thêm ngôn ngữ mới vào dự án của tôi?

Bạn không thể thêm locales qua SDK. Các locales được cấu hình trong bảng điều khiển quản trị OneEntry.

Làm thế nào để thiết lập ngôn ngữ mặc định?

Bạn không thể thiết lập locale mặc định qua SDK. Locale mặc định được cấu hình trong bảng điều khiển quản trị OneEntry:

Lưu ý: Chỉ có một locale có thể là mặc định tại một thời điểm.

Tôi có nên hiển thị các locales không hoạt động cho người dùng không?

Không! Luôn lọc theo isActive:

Tại sao? Các locales không hoạt động có thể:

Đang trong quá trình phát triển (nội dung chưa sẵn sàng)
Tạm thời bị vô hiệu hóa
Không có bản dịch cho tất cả nội dung

Làm thế nào để xử lý các bản dịch bị thiếu?

Sử dụng logic dự phòng

Tôi có thể lưu trữ các locales không?

Có! Các locales hiếm khi thay đổi, vì vậy việc lưu trữ được khuyến nghị.

Tôi có thể sử dụng Locales với Next.js i18n không?

Có! Tích hợp các locales của OneEntry với Next.js.

Làm thế nào để nhóm các locales theo ngôn ngữ?

Nhóm các biến thể của cùng một ngôn ngữ

Nếu tôi cần dịch các phần tử giao diện (không phải nội dung CMS) thì sao?

Mô-đun Locales của OneEntry chỉ dành cho các locales nội dung CMS. Đối với dịch giao diện:

Tùy chọn 1: Sử dụng thư viện i18n (react-i18next, next-i18next)

Tùy chọn 2: Lưu trữ các bản dịch giao diện trong OneEntry

Tạo một loại trang "bản dịch" và lấy các chuỗi bản dịch

💡 Lưu ý quan trọng

Locales là chỉ đọc

Mô-đun Locales là chỉ đọc:

✅ Lấy locales
✅ Lọc theo trạng thái hoạt động
✅ Tìm locale mặc định
❌ Không thể tạo locales
❌ Không thể cập nhật locales
❌ Không thể xóa locales

Để sửa đổi: Sử dụng bảng điều khiển quản trị OneEntry.

Luôn lọc các locales đang hoạt động

Chỉ hiển thị các locales đang hoạt động cho người dùng

Tại sao? Các locales không hoạt động có thể không có bản dịch đầy đủ.

Lưu trữ được khuyến nghị

Các locales hiếm khi thay đổi - thực hiện lưu trữ

Đồng bộ với các locales nội dung

Đảm bảo ngôn ngữ giao diện khớp với nội dung có sẵn

🎓 Thực hành tốt nhất

Luôn lọc các locales đang hoạt động - Chỉ hiển thị các ngôn ngữ đã kích hoạt
Lưu trữ các locales - Chúng hiếm khi thay đổi, lưu trữ để cải thiện hiệu suất
Sử dụng locale mặc định làm dự phòng - Xử lý các bản dịch bị thiếu
Lưu sở thích của người dùng - Nhớ lựa chọn ngôn ngữ
Xác thực mã locale - Kiểm tra xem locale có tồn tại trước khi sử dụng
Phát hiện ngôn ngữ trình duyệt - Tự động chọn ngôn ngữ của người dùng
Nhóm theo ngôn ngữ - Hiển thị các biến thể ngôn ngữ một cách hợp lý

Thông tin thêm về giao diện người dùng của mô-đun https://doc.oneentry.cloud/docs/category/languages

Định nghĩa của mô-đun Locales

Mô-đun 'Locales' cho phép hỗ trợ đa ngôn ngữ trong OneEntry.

Nhờ vào sự hỗ trợ của nhiều ngôn ngữ trong Nền tảng OneEntry, bạn có thể tùy chỉnh linh hoạt giao diện của bảng điều khiển và quản lý ngôn ngữ trong dự án của mình một cách thuận tiện. Trong phần này, bạn có thể tìm hiểu về các nguyên tắc làm việc với ngôn ngữ.


const { Locales } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

🔗 Tài liệu liên quan

Mô-đun Trang - Lấy nội dung trang đã địa phương hóa
Mô-đun Sản phẩm - Quản lý sản phẩm đa ngôn ngữ
Mô-đun GeneralTypes - Phân loại loại thực thể
Mô-đun Admins - Người dùng quản trị quản lý locales

Giới thiệu

🎯 Mô-đun này làm gì?​

📖 Giải thích đơn giản​

✨ Khái niệm chính​

Locale là gì?​

Cấu trúc Locale​

Tại sao sử dụng mô-đun Locales?​

Các trường hợp sử dụng phổ biến​

📋 Những điều bạn cần biết​

Locales được cấu hình trong bảng điều khiển quản trị​

Locales đang hoạt động và không hoạt động​

Locale mặc định​

Mã Locale và Mã ngắn​

📊 Bảng tham khảo nhanh​

❓ Câu hỏi thường gặp (FAQ)​

Làm thế nào để thêm ngôn ngữ mới vào dự án của tôi?​

Làm thế nào để thiết lập ngôn ngữ mặc định?​

Tôi có nên hiển thị các locales không hoạt động cho người dùng không?​

Làm thế nào để xử lý các bản dịch bị thiếu?​

Tôi có thể lưu trữ các locales không?​

Tôi có thể sử dụng Locales với Next.js i18n không?​

Làm thế nào để nhóm các locales theo ngôn ngữ?​

Nếu tôi cần dịch các phần tử giao diện (không phải nội dung CMS) thì sao?​

💡 Lưu ý quan trọng​

Locales là chỉ đọc​

Luôn lọc các locales đang hoạt động​

Lưu trữ được khuyến nghị​

Đồng bộ với các locales nội dung​

🎓 Thực hành tốt nhất​

Định nghĩa của mô-đun Locales​

🔗 Tài liệu liên quan​