Giao diện
Cài đặt và sử dụng — Localization
Tổng quan
Plugin @digiforce-nc/plugin-localization quản lý đa ngôn ngữ (i18n) cho toàn bộ giao diện DigiForce. Plugin thu thập chuỗi văn bản (source strings) từ hệ thống và các plugin, lưu vào database, cho phép admin dịch sang nhiều ngôn ngữ, rồi đồng bộ bản dịch vào locale cache để giao diện hiển thị đúng ngôn ngữ.
Bước 1: Kích hoạt plugin
Vào Settings → Plugin Manager, tìm plugin-localization và bật lên.
Khi kích hoạt, plugin tạo:
- Hai bảng database:
localizationTexts(chuỗi gốc) vàlocalizationTranslations(bản dịch) - Trang quản lý trong Settings → Localization
- Resource API:
localizationTextsvàlocalization
Bước 2: Đồng bộ chuỗi văn bản (Sync)
Trước khi dịch, cần thu thập chuỗi văn bản từ hệ thống vào database.
Nguồn đồng bộ (Sources)
Plugin đăng ký 2 nguồn mặc định:
| Nguồn | Mô tả | Dữ liệu thu thập |
|---|---|---|
System & Plugins (local) | Chuỗi giao diện từ core và các plugin | Label, button text, menu items, thông báo... |
Collections & Fields (db) | Tên collection, tên field có đánh dấu translation: true | Title của collection, label của field |
Thao tác đồng bộ
Vào Settings → Localization, chọn nguồn cần đồng bộ và nhấn Sync:
Mẹo
Sau khi cài thêm plugin mới hoặc tạo collection/field mới, nhớ chạy Sync lại để thu thập chuỗi mới.
Bước 3: Dịch nội dung
Sau khi đồng bộ, danh sách chuỗi hiển thị trong bảng quản lý. Admin có thể:
Lọc và tìm kiếm
| Bộ lọc | Mô tả |
|---|---|
| Module | Lọc theo plugin hoặc namespace (VD: client, users, collections) |
| Keyword | Tìm kiếm trong chuỗi gốc hoặc bản dịch |
| Has translation | Lọc chuỗi đã có bản dịch hoặc chưa có |
| Locale | Ngôn ngữ đích (từ header X-Locale) |
Dịch chuỗi
Nhấn vào ô Translation của chuỗi cần dịch, nhập bản dịch và lưu. Bản dịch lưu vào bảng localizationTranslations với cặp (textId, locale) duy nhất.
Xử lý chuỗi thiếu bản dịch (Missing keys)
Plugin đăng ký MissingKeyHandler trên client. Khi giao diện hiển thị một chuỗi chưa có trong database:
- Client tự động gửi chuỗi thiếu về server qua action
localizationTexts:missing - Server thêm chuỗi mới vào
localizationTextsvà tạo bản dịch mặc định - Lần sau admin sẽ thấy chuỗi này trong danh sách để dịch
Lưu ý
Action missing yêu cầu user có quyền ui.* (snippet ui.localization). User thường không có quyền này — chỉ admin/root mới trigger được.
Bước 4: Xuất bản bản dịch (Publish)
Sau khi dịch xong, nhấn Publish để áp dụng:
Action publish gọi app.localeManager.reload() để làm mới toàn bộ locale cache. Sau khi publish, refresh trang để thấy bản dịch mới.
Kiến trúc chi tiết
Luồng dữ liệu 4 tầng
Database Schema
Bảng localizationTexts
| Trường | Kiểu | Mô tả |
|---|---|---|
id | snowflakeId (PK) | ID duy nhất |
module | string | Namespace của chuỗi (VD: resources.client, resources.users) |
text | text | Nội dung chuỗi gốc |
batch | string | Batch đồng bộ (dùng cho quản lý nội bộ) |
translations | hasMany | Quan hệ 1:N đến localizationTranslations |
Bảng localizationTranslations
| Trường | Kiểu | Mô tả |
|---|---|---|
id | bigInt (PK) | ID tự tăng |
locale | string | Mã ngôn ngữ (VD: vi-VN, en-US, ja-JP) |
translation | text | Nội dung bản dịch |
textId | FK | Khoá ngoại đến localizationTexts |
Index unique trên (locale, textId) đảm bảo mỗi chuỗi chỉ có một bản dịch cho mỗi ngôn ngữ.
API Endpoints
| Endpoint | Mô tả |
|---|---|
localizationTexts:list | Danh sách chuỗi (có phân trang, lọc, tìm kiếm) |
localizationTexts:missing | Gửi chuỗi thiếu từ client |
localization:sync | Đồng bộ chuỗi từ nguồn đã chọn |
localization:publish | Xuất bản bản dịch (reload locale cache) |
localization:getSources | Danh sách nguồn đồng bộ có sẵn |
Cơ chế cache
Plugin sử dụng in-memory cache (@digiforce-nc/cache) với prefix localization:
| Cache key | Dữ liệu | Cập nhật khi |
|---|---|---|
texts | Danh sách tất cả source texts | Sync, missing key |
translations:{locale} | Bản dịch cho locale cụ thể | Publish |
Khi thêm chuỗi mới, cache texts tự động cập nhật. Bản dịch chỉ cập nhật khi Publish.
Hỗ trợ cluster
Plugin hỗ trợ chạy trên nhiều instance (cluster mode). Khi thêm chuỗi mới trên instance A, message updateCacheTexts được gửi đến tất cả instance khác qua sendSyncMessage để đồng bộ cache.
Lưu ý quan trọng
- Sync không tự động — admin cần chạy thủ công khi có plugin mới hoặc collection/field mới
- Publish bắt buộc — bản dịch chỉ có hiệu lực sau khi Publish (reload locale cache)
- Plugin thu thập chuỗi từ field có
translation: truetrong collection definition - Module prefix
resources.được tự động thêm vào tất cả source text - Chuỗi trùng lặp (cùng
text+ cùngmodule) sẽ được bỏ qua khi sync - ACL snippet
pm.localization.localizationkiểm soát quyền quản lý bản dịch