Многоязычная интеграция и источник истины

PolyCMS предлагает надежную, глобально доступную архитектуру перевода, которая автоматически обнаруживает и объединяет файлы локализации из ядра, модулей и тем.

Чтобы обеспечить производительность без ущерба для простоты использования для администраторов, в системе используется архитектура Конвейера компиляции. Разработчику очень важно понимать концепцию Источника истины, чтобы предотвратить потерю данных или сбои молчаливого перевода.

1. Архитектура конвейера компиляции

PolyCMS разделяет хранилище переводов на два формата:

Файлы .json (Источник истины): Это удобочитаемые файлы словарей, редактируемые администратором.

Файлы .php (скомпилированный кеш): Это высокопроизводительные PHP-массивы, генерируемые системой.

Как это работает во время выполнения

Когда загружается страница (Backend или Frontend) и строка требует перевода, основной LanguageHelper читает только из скомпилированных файлов кэша .php. Он не сканирует и не анализирует файлы .json во время выполнения, чтобы гарантировать максимальную скорость рендеринга.

Как это работает во время редактирования

Когда администратор редактирует язык через пользовательский интерфейс администратора PolyCMS (Настройки > Языки), система читает и записывает файлы .json. После сохранения система автоматически запускает компилятор для регенерации кэша .php.

2. Рабочий процесс разработчика: добавление переводов

При разработке модуля или темы вам часто потребуется добавлять новые переводимые строки.

Расположение файла

Переводы должны быть помещены в каталог lang/ в корне вашего расширения:

Модуль: modules/Vendor/ModuleName/lang/{locale}.json

Тема: themes/theme-slug/lang/{locale}.json

Золотое правило

КРИТИЧЕСКОЕ: файл {locale}.json является абсолютным источником истины. Вы никогда не должны редактировать файл {locale}.php вручную, так как системный компилятор перезапишет его.

Пошаговый процесс перевода

Добавить в JSON. Откройте файл lang/en.json или lang/vi.json вашего модуля или темы и добавьте новые пары ключ-значение.

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

Компиляция в PHP: Поскольку система читает только из .php, ваши новые ключи JSON не вступят в силу, пока они не будут скомпилированы. Вам необходимо вручную запустить компилятор в вашей среде разработки.

Использование Artisan Tinker:

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

Кроме того, вы можете перейти в панель администратора PolyCMS: «Настройки» > «Языки» и нажать кнопку Компилировать.

Проверка: принудительно перезагрузите браузер (Ctrl + F5). Новые переводы теперь должны появиться в пользовательском интерфейсе.

3. Форматирование предупреждений и скрытых сбоев

Если вы запустили команду компиляции, но ваши переводы по-прежнему не отображаются, это почти всегда связано с недействительным файлом JSON.

Если json_decode() не сможет проанализировать ваш файл .json, LanguageService молча пропустит его, чтобы предотвратить сбой приложения.

Распространенные ошибки форматирования JSON, которых следует избегать:

Спецификация UTF-8: Убедитесь, что ваш редактор кода (или команды терминала, такие как Set-Content PowerShell) не вводят метку порядка байтов (BOM). Файл должен быть в чистом формате UTF-8.

Завершающие запятые. JSON не допускает использования запятых после последнего элемента.

Неэкранированные кавычки. Убедитесь, что все двойные кавычки внутри строки экранированы правильно (например, \").

4. Использование переводов в коде

После компиляции вы можете беспрепятственно использовать строки перевода на разных уровнях вашего модуля или темы.

В шаблонах Blade

Всегда заключайте жестко запрограммированный текст в собственный переводчик Laravel __() или вспомогательный инструмент PolyCMS _l():

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

В PHP (контроллеры, поставщики услуг)

Используйте помощник _l() для административных строк, меток меню или настроек:

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

В компонентах Vue

Импортируйте и используйте глобальный составной объект useTranslation:

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

const { t } = useTranslation();

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