Giới thiệu
Lấy các ngôn ngữ được cấu hình trong dự án của bạn để cung cấp nội dung đa ngôn ngữ và phát hiện địa phương.
Thông tin thêm về giao diện người dùng của mô-đun https://doc.oneentry.cloud/docs/category/languages
🎯 Mô-đun này làm gì?
Mô-đun Locales cho phép bạn lấy các ngôn ngữ đang hoạt động được cấu hình trong dự án OneEntry của bạn - để bạn có thể 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ữ.
Thay vì mã hóa cứng các 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 thích ứng với các địa phương mà bạn đã kích hoạt (tiếng Anh, tiếng Nga, tiếng Ả Rập, tiếng Tây Ban Nha, v.v.). Các ngôn ngữ được cấu hình trong bảng điều khiển quản trị OneEntry; SDK chỉ có thể lấy chúng.
🚀 Bắt đầu nhanh
Khởi tạo mô-đun từ defineOneEntry:
const { Locales } = defineOneEntry( "your-project-url", { "token": "your-app-token" });
Lấy các địa phương đang hoạt động và đọc các trường của chúng:
// Returns only active locales (isActive: true).
const locales = await Locales.getLocales();
console.log(`${locales.length} active languages`);
locales.forEach((locale) => {
console.log(locale.code, locale.name, locale.shortCode);
});
✨ Khái niệm chính
Địa phương là gì?
Một địa phương 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 địa phương - định dạng kết hợp:
language_REGION(ví dụ:en_US,ru_RU,ar_SA)
Ví dụ:
| Mã địa phương | 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 Xê Út | Tiếng Ả Rập (Ả Rập Xê Út) |
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 địa phương
Mỗi địa phương được trả về bởi getLocales() (ILocalEntity) có:
{
id: 146, // unique ID
shortCode: 'en', // short code
code: 'en_US', // full code
name: 'English (USA)', // name
nativeName: 'English (USA)', // native name
isActive: true, // is active (always true here)
image: null, // image
position: 1, // position
}
Mã địa phương so với Mã ngắn
Mỗi địa phương 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 địa phương đầy đủ |
shortCode | language | en, ru | Nhận diện chỉ ngôn ngữ |
📋 Những điều bạn cần biết
Các địa phương được cấu hình trong bảng điều khiển quản trị (chỉ đọc)
Bạn không thể tạo, cập nhật hoặc xóa các địa phương qua SDK - chúng được cấu hình trong bảng điều khiển quản trị OneEntry:
OneEntry Admin Panel → Settings → Languages → Add Language → Select Locale
SDK chỉ dùng để lấy thông tin địa phương.
SDK chỉ trả về các địa phương đang hoạt động
getLocales() chỉ trả về các đối tượng phân vùng ngôn ngữ đang hoạt động (isActive: true). Các địa phương không hoạt động được cấu hình trong bảng điều khiển quản trị sẽ không được trả về, vì vậy không cần phải lọc chúng trên phía khách hàng. Mỗi địa phương được trả về vẫn mang cờ isActive (luôn là true ở đây), cùng với code, shortCode, name, nativeName, image, và position.
Không có trường địa phương mặc định trong phản hồi — hãy chọn và lưu một ngôn ngữ dự phòng trong ứng dụng của bạn.
📊 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 địa phương đang 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 để tôi thêm ngôn ngữ mới vào dự án của mình?
Bạn không thể thêm các địa phương qua SDK. Các địa phương được cấu hình trong bảng điều khiển quản trị OneEntry.
getLocales() có trả về các ngôn ngữ không hoạt động không?
Không. SDK chỉ trả về các địa phương đang hoạt động (isActive: true). Các ngôn ngữ bị vô hiệu hóa trong bảng điều khiển quản trị không được bao gồm trong phản hồi.
Tôi có thể lưu trữ các địa phương không?
Có. Các địa phương hiếm khi thay đổi, vì vậy việc lưu trữ kết quả là được khuyến nghị để cải thiện hiệu suất.
Làm thế nào để tôi xử lý các bản dịch bị thiếu?
Chọn một ngôn ngữ dự phòng trong ứng dụng của bạn và quay lại nó khi nội dung bị thiếu cho địa phương yêu cầu — getLocales() không bao gồm trường địa phương mặc định.
🎓 Thực hành tốt nhất
- Dựa vào danh sách đang hoạt động - SDK đã trả về chỉ các địa phương đã được kích hoạt, vì vậy không cần lọc ở phía khách hàng.
- Lưu trữ các địa phương - Chúng hiếm khi thay đổi; lưu trữ kết quả để cải thiện hiệu suất.
- Chọn ngôn ngữ dự phòng của riêng bạn - Không có trường địa phương mặc định; xử lý các bản dịch bị thiếu trong ứng dụng của bạn.
- Khớp
codevớishortCode- Sử dụngcode(en_US) để nhận diện đầy đủ vàshortCode(en) cho logic chỉ ngôn ngữ.
🔗 Tài liệu liên quan
- Mô-đun Pages - Lấy nội dung trang được địa phương hóa
- Mô-đun Products - 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ý các địa phương