Языковые переводы для CodeIgniter 4

Этот пакет предоставляет команды для работы с переводами в CodeIgniter 4, упрощая процесс поиска и обновления языковых ключей. Важно: команда не выполняет автоматический перевод фраз, а лишь помогает организовать и обновить ключи.

В CodeIgniter 4 есть встроенная команда для Генерации переводов. Здесь усовершенствованная версия.

Установка

Обычный процесс разработки

В процессе разработки с использованием переводов в CodeIgniter 4 вы выполняете следующие шаги:

1. Используете функцию lang() в коде, например:

echo lang('Users.list.title');
echo lang('Users.list.title', ['About'], 'ru');

2. Создаёте файл app/Language/<locale>/Users.php для каждой доступной локали и прописываете переводы в массив.

Этот подход работает хорошо, если вы сразу добавляете переводы. Однако, если переводы откладываются, могут возникнуть проблемы:

• Пропуск ключей для перевода.
• Дублирование существующих ключей.
• Опечатки в ключах или фразах.
• Неполное обновление файлов перевода.

Пример использования

Рассмотрим пример на основе следующих данных:

// Локаль по умолчанию в app/Config/App.php
$defaultLocale = 'ru';

// Доступные локали в app/Config/App.php
$supportedLocales = ['en', 'ru', 'de'];

// Файл app/Controllers/Translation/Lang.php
$message  = lang('Text.info.success');
$message2 = lang('Text.paragraph');
$message3 = lang('Text.expired', ['2025-01-01']);
$message4 = lang('Text.created', ['date' => 'yesterday'], 'de');

// Изначальный массив с переводом app/Language/ru/Text.php
return [
    'created' => 'Создано {date}',
    'expired' => 'Завершено {0}',
    'info'    => [
        'success' => 'Успешно!',
    ],
    'paragraph' => 'Привет, Мир!',
];

lang:finder Поиск новых и обновление старых переводов.

Вы можете автоматически генерировать и обновлять файлы перевода вашего приложения. Команда будет искать использование функции lang(), объединять текущие ключи перевода в выбранной директории Language, определяя локаль defaultLocale из Config\App.

После операции вам необходимо перевести языковые ключи самостоятельно. Команда умеет распознавать ключи File.array.nested.text, создавая многомерные массивы внутри файла с переводом.

При сканировании директория Language, в которой хранятся файлы перевода, будет пропущена. Рассчитано, что они не имеют внутри себя lang()

Ранее сохраненные ключи как и сортировка не изменяются. Новые ключи добавляются в конец массива.

В случае базовой установки CodeIgniter 4 вы можете запустить:

php spark lang:finder

это аналогично команде:

php spark lang:finder --locale ru --dir ./app/ --lang-dir ./app/Language/

В результате выполнится поиск языковых ключей в директории APPPATH (./app/), создастся или обновится массив в файлах перевода в APPPATH/Language/ (./app/Language/).

Так как файл ./app/Language/ru/Text.php уже содержит массив со всеми переводами, то значения останутся без изменений.

Указав другие данные (локаль или папку для сохранения), создаётся новый файл <lang-dir>/<locale>/Text.php с массивом:

<?php

return [
    'info' => [
        'success' => 'Text.info.success',
    ],
    'paragraph' => 'Text.paragraph',
    'expired' => 'Text.expired...{0}',
    'created' => 'Text.created...{date}',
];

Добавив новые переводы в исходный код:

$obj       = new \stdClass();
$obj->desc = 'Описание страницы';
$message4  = lang('Text.meta.desc', $obj->desc ?? ['Неясное описания']);

вы обновите файл:

<?php

return [
    'info' => [
        'success' => 'Text.info.success',
    ],
    'paragraph' => 'Text.paragraph',
    'expired' => 'Text.expired...{0}',
    'created' => 'Text.created...{date}',
    'meta' => [
        'desc' => 'Text.meta.desc...{?}',
    ],
];

Параметры запуска

--locale Укажите доступную локаль для сохранения.

--dir Директория для сканирования кода отсносительно ROOTPATH. По умолчанию APPPATH.

--lang-dir Директория, в которую сохранятся файлы перевода. По умолчанию APPPATH/Language/.

--show-new Показать в консоли новые ключи перевода без их записи.

--verbose Подробный вывод процесса команды.

--help Описание команды

Полный пример команды:

php spark lang:finder --locale de --dir ./app/Modules/ --lang-dir ./app/Modules/Language --verbose --show-new

Заполнители

Для понимания следующего прочтите документацию Замена параметров

Подсказка в конце фразы - заполнители, динамические данные которые можно подставить из кода. Поддерживаются типы:

• {число} - числовой индекс
• {строка} - строковой ключ
• {?} - неопределенный тип

Видя, их количество и тип, по возможности, вам необходимо в нужном месте перевода подставить заполнитель. {?} лишь намекает, что некоторый параметр передан, но это не строка или число, скорее объект или сложное выражение.

В большинстве случаев стоит проверить какие данные передаются.

При большом количестве ключей, вы можете ошибиться и передать для перевода разные заполнители: в одном месте как числовой индекс {1}, в другом как строковой ключ {name}. Посмотрев на сгенерированный массив вы можете обнаружить такое несоответствие и исправить его.

Возможности

• Сканирование всех .php файлов в указанной директории.
• Указание директорий для поиска и сохранения.
• Существующие переводы остаются без изменений.
• Новые ключи для перевода добавляются в конец, если перевод уже существует.
• Создание многомерных массивов, если ключ содержит точки.
• Автоматическое добавление заполнителей для фраз {int} - числовой индекс, {string} - строковой ключ, {?} - неопределенный тип.
• Поддержка Unicode
• Работа только с поддерживаемыми локалями

Особенности и ограничения

• Для поиска требуется библиотека nikic/php-parser. Обычно она нужка только для разработки, но здесь это прямая зависимость.
• После выполнения возможно понадобится форматирование, например, php-cs-fixer
• Файлы переводов полностью перезаписываются. Если вы используете форматирование или комментарии, они могут быть потеряны. Следует проверять на соответствие вашему стилю.
• Если перевод File.text...{0} или Ваше имя {name} имеет подсказку типа, то при новом заполнителе он не обновится. Если вы еще не переводили файл, перед повторным запуском команды можете его удалить.

Помощь

Если вы нашли ошибки или есть предложения по улучшению, можете отправить PR или открыть Проблему.