Tích hợp đa ngôn ngữ & Nguồn sự thật

PolyCMS cung cấp kiến ​​trúc dịch mạnh mẽ, có sẵn trên toàn cầu, tự động phát hiện và hợp nhất các tệp bản địa hóa từ Lõi, Mô-đun và Chủ đề.

Để đảm bảo hiệu suất mà không ảnh hưởng đến tính dễ sử dụng của quản trị viên, hệ thống sử dụng kiến ​​trúc Đường dẫn biên dịch. Với tư cách là nhà phát triển, điều quan trọng là phải hiểu khái niệm Nguồn sự thật để ngăn ngừa mất dữ liệu hoặc lỗi dịch thầm.

1. Kiến trúc đường ống biên dịch

PolyCMS tách bộ lưu trữ dịch thành hai định dạng:

Tệp .json (Nguồn sự thật): Đây là các tệp từ điển mà con người có thể đọc được và quản trị viên có thể chỉnh sửa.

Các tệp .php (Bộ đệm được biên dịch): Đây là các mảng PHP hiệu suất cao do hệ thống tạo ra.

Cách hoạt động trong Runtime

Khi một trang tải (Phần cuối hoặc Phần cuối) và một chuỗi cần dịch, lõi LanguageHelper chỉ đọc từ các tệp bộ đệm .php đã biên dịch. Nó không quét hoặc phân tích các tệp .json trong thời gian chạy để đảm bảo tốc độ hiển thị tối đa.

Cách thức hoạt động trong quá trình chỉnh sửa

Khi quản trị viên chỉnh sửa ngôn ngữ thông qua Giao diện người dùng quản trị PolyCMS (Cài đặt > Ngôn ngữ), hệ thống sẽ đọc và ghi vào tệp .json. Sau khi lưu, hệ thống sẽ tự động kích hoạt trình biên dịch để tạo lại bộ đệm .php.

2. Quy trình làm việc của nhà phát triển: Thêm bản dịch

Khi phát triển Mô-đun hoặc Chủ đề, bạn thường sẽ cần thêm các chuỗi có thể dịch mới.

Vị trí tệp

Bản dịch phải được đặt trong thư mục lang/ ở thư mục gốc của tiện ích mở rộng của bạn:

Mô-đun: mô-đun/Nhà cung cấp/Tên mô-đun/lang/{locale}.json

Chủ đề: themes/theme-slug/lang/{locale}.json

Nguyên tắc vàng

TUYỆT VỜI: Tệp {locale}.json là Nguồn sự thật tuyệt đối. Bạn phải không bao giờ chỉnh sửa thủ công tệp {locale}.php vì trình biên dịch hệ thống sẽ ghi đè lên nó.

Quy trình dịch thuật từng bước

Thêm vào JSON: Mở lang/en.json hoặc lang/vi.json của mô-đun hoặc chủ đề của bạn và thêm các cặp khóa-giá trị mới của bạn.

{
    "My Custom Setting": "Cài đặt tùy chỉnh của tôi",
    "Show Blog Header": "Hiển thị Header Blog"
}

Biên dịch sang PHP: Vì hệ thống chỉ đọc từ .php nên các khóa JSON mới của bạn sẽ không có hiệu lực cho đến khi chúng được biên dịch. Bạn phải kích hoạt trình biên dịch theo cách thủ công trong môi trường phát triển của mình.

Sử dụng Artisan Tinker:

php artisan tinker --execute="app(\App\Services\LanguageService::class)->compileToPhp('vi');"

Ngoài ra, bạn có thể truy cập bảng Quản trị PolyCMS: Cài đặt > Ngôn ngữ và nhấp vào nút Biên dịch.

Xác minh: Tải lại cứng (Ctrl + F5) trình duyệt của bạn. Các bản dịch mới bây giờ sẽ xuất hiện trong giao diện người dùng.

3. Cảnh báo định dạng & Lỗi im lặng

Nếu bạn chạy lệnh biên dịch nhưng bản dịch của bạn vẫn không xuất hiện thì hầu như luôn là do tệp JSON không hợp lệ.

Nếu json_decode() không phân tích được tệp .json của bạn, LanguageService sẽ âm thầm bỏ qua nó để tránh làm ứng dụng bị lỗi.

Các lỗi định dạng JSON phổ biến cần tránh:

UTF-8 BOM: Đảm bảo trình soạn thảo mã của bạn (hoặc các lệnh đầu cuối như Set-Content của PowerShell) không đưa vào Dấu thứ tự Byte (BOM). Tệp phải thuần UTF-8.

Dấu phẩy ở cuối: JSON không cho phép dấu phẩy ở cuối mục cuối cùng.

Dấu ngoặc kép không thoát: Đảm bảo mọi dấu ngoặc kép bên trong chuỗi của bạn đều được thoát đúng cách (ví dụ: \").

4. Sử dụng bản dịch trong Code

Sau khi biên dịch, bạn có thể sử dụng các chuỗi dịch một cách liền mạch trên các lớp khác nhau của mô-đun hoặc chủ đề.

Trong mẫu Blade

Luôn bọc văn bản được mã hóa cứng trong trình dịch gốc __() của Laravel hoặc trình trợ giúp PolyCMS _l():

<button>{{ __('Show Blog Header') }}</button>

Trong PHP (Bộ điều khiển, Nhà cung cấp dịch vụ)

Sử dụng trình trợ giúp _l() cho các chuỗi quản trị, nhãn menu hoặc cài đặt:

$menuRegistry->addChild('content', [
    'key' => 'blog_enhancer_tools',
    'label' => _l('SEO Tools'), // Translates automatically based on Admin's language
    'url' => '/admin/blog-enhancer'
]);

Trong thành phần Vue

Nhập và sử dụng thành phần kết hợp useTranslation toàn cục:

import { useTranslation } from '@/admin/composables/useTranslation';

const { t } = useTranslation();

// In your Vue template:
// <h2>{{ t('SEO Tools') }}</h2>