@digiforce-nc/plugin-localization

Plugin quản lý đa ngôn ngữ — lưu trữ source strings và bản dịch, đồng bộ từ locale cache và database, cung cấp UI quản lý translation.

Plugin này làm gì?

Hãy hình dung một phòng biên dịch: mỗi chuỗi văn bản (source string) trong hệ thống được gửi vào phòng biên dịch, tại đây có sẵn bản dịch cho từng ngôn ngữ. Khi hệ thống cần hiển thị giao diện, nó hỏi phòng biên dịch "câu này tiếng Việt nói sao?" và nhận lại bản dịch tương ứng.

Ba nhiệm vụ chính

#	Nhiệm vụ	Chi tiết
1	Thu thập source strings	Tự động phát hiện chuỗi mới từ module/collection, lưu vào DB
2	Quản lý bản dịch	CRUD translations cho từng ngôn ngữ, phát hiện bản dịch thiếu
3	Đồng bộ cache	Sync translations từ DB vào locale cache để i18n hoạt động realtime

Kiến trúc

Tổng quan 4 tầng

Tầng	Vai trò	Thành phần
Client UI	Quản lý bản dịch, xem missing keys	Localization settings, `MissingKeyHandler`
Server API	Thu thập string, sync, trả translations	`SourceManager`, resources
Database	Lưu trữ source texts & translations	2 bảng: `localizationTexts`, `localizationTranslations`
Cache	Locale data in-memory	Đồng bộ từ DB, phục vụ i18n nhanh

API endpoints

Endpoint	Mô tả
`localization:sync`	Đồng bộ translations từ DB vào locale cache
`localizationTexts:list`	Danh sách source texts
`localizationTexts:missing`	Danh sách text chưa có bản dịch cho ngôn ngữ chỉ định

Luồng đồng bộ

Bước	Hành động	Kết quả
Phát hiện text mới	`SourceManager.addNewTexts()`	Ghi record vào `localizationTexts`
Admin dịch	Sửa translation qua UI	Ghi vào `localizationTranslations`
Sync cache	Gọi `localization:sync`	Cache cập nhật, i18n dùng bản dịch mới

Database — 2 bảng

Bảng	Chứa gì	Ví dụ
`localizationTexts`	Source string gốc	`{ module: 'users', text: 'Sign in' }`
`localizationTranslations`	Bản dịch theo ngôn ngữ	`{ textId: 1, locale: 'vi-VN', translation: 'Đăng nhập' }`

Thành phần client

Thành phần	Mô tả
Localization settings	Trang quản lý translations trong Settings
`MissingKeyHandler`	Hiển thị & đánh dấu các key chưa có bản dịch

Dependencies

Package	Vai trò
`@digiforce-nc/cache`	Locale cache (peer)
`@digiforce-nc/database`	Database ORM (peer)
`@digiforce-nc/plugin-ui-schema-storage`	Đọc UI schema để thu thập source strings
`@digiforce-nc/client`	Client framework (peer)