PHP: полный мануал с примерами, функциями и ООП

PHP 4+ · gettext

gettext(string $message): string

Найти перевод одного сообщения в текущем домене.

Gettext ищет перевод сообщения в каталоге. domain — имя набора переводов, например learning, а не интернет-домен сайта. message — исходная строка-ключ; результат — обычная PHP строка, которую можно сохранить, форматировать и безопасно вывести. Если перевода нет, обычно возвращается исходный текст, поэтому отсутствие исключения ещё не подтверждает исправность настройки.

Сначала отдельный вызов: берём английский ключ Cart и получаем его перевод из активного каталога. Функция сама не выводит текст: echo ниже выполняет отдельное действие.

Примеры с require "gettext-lab.php" используют приложенный учебный каталог: Cart → «Корзина», Checkout → «Оформление заказа», три русские формы слова «товар». Он входит в скачиваемый пример. Нужны расширение gettext и доступная русская locale. Здесь каталог разворачивается из включённой MO-заготовки; в проекте его собирают из PO командой msgfmt, как показано в начале главы. Запуск отдельным CLI-процессом изолирует изменения locale и домена.

<?php
declare(strict_types=1);

require __DIR__ . '/gettext-lab.php';
$title = gettext('Cart');
echo $title, "\n";
echo gettext('There is no translation yet'), "\n";

Корзина
There is no translation yet

Когда в сообщении меняется имя покупателя, в каталоге оставляют постоянный шаблон. Gettext находит его, sprintf вставляет данные, htmlspecialchars экранирует готовую строку для HTML. При каждом этапе остаётся своя ответственность.

<?php
declare(strict_types=1);

require __DIR__ . '/gettext-lab.php';
$customerName = 'Ира <VIP>';
$message = sprintf(gettext('Hello, %s!'), $customerName);
echo htmlspecialchars($message, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8'), "\n";

Здравствуйте, Ира <VIP>!

Текст переводят перед выводом; числа, даты и валюты форматируют отдельными инструментами. Для перестановки нескольких аргументов в переводе полезны позиционные шаблоны sprintf, например %2$s: %1$d. Инструмент xgettext извлекает строковые литералы из исходников, но не знает все значения произвольных выражений. Пустой msgid зарезервирован каталогом под метаданные: не используйте его как перевод пустой кнопки. В PHP 8.5.11 длина message ограничена 4096 байтами; превышение вызывает ValueError. Большой текст страницы лучше разбить на осмысленные сообщения.

Рядом по задаче: _; dgettext; ngettext; textdomain.

• PHP: gettext

PHP 4+ · gettext

_(string $message): string

Короткое имя gettext для перевода надписей.

Gettext ищет перевод сообщения в каталоге. domain — имя набора переводов, например learning, а не интернет-домен сайта. message — исходная строка-ключ; результат — обычная PHP строка, которую можно сохранить, форматировать и безопасно вывести. Если перевода нет, обычно возвращается исходный текст, поэтому отсутствие исключения ещё не подтверждает исправность настройки.

Сокращение _ является алиасом gettext с теми же аргументом, результатом и ограничениями. Это реальная функция расширения, а не специальный оператор PHP. Её короткое имя удобно при большом количестве небольших надписей в шаблоне.

Примеры с require "gettext-lab.php" используют приложенный учебный каталог: Cart → «Корзина», Checkout → «Оформление заказа», три русские формы слова «товар». Он входит в скачиваемый пример. Нужны расширение gettext и доступная русская locale. Здесь каталог разворачивается из включённой MO-заготовки; в проекте его собирают из PO командой msgfmt, как показано в начале главы. Запуск отдельным CLI-процессом изолирует изменения locale и домена.

<?php
declare(strict_types=1);

require __DIR__ . '/gettext-lab.php';
echo _('Checkout'), "\n";
var_dump(_('Cart') === gettext('Cart'));

Оформление заказа
bool(true)

<?php
declare(strict_types=1);

require __DIR__ . '/gettext-lab.php';
$labels = ['cart' => _('Cart'), 'submit' => _('Checkout')];
echo $labels['cart'], ' / ', $labels['submit'], "\n";

Корзина / Оформление заказа

В чужом проекте сначала выясните, какая система локализации там принята. Функции CMS вроде WordPress __() имеют собственный контракт и домены; это не другой вариант встроенного _ без дополнительных условий. Нельзя заново объявить функцию _, если расширение уже объявило её. Проверка function_exists полезна при диагностике, но молчаливый fallback не должен скрывать отсутствующий на production перевод.

Рядом по задаче: gettext; ngettext; dgettext.

• PHP: _

PHP 4+ · gettext

dgettext(string $domain, string $message): string

Перевести сообщение из явно указанного домена.

Gettext ищет перевод сообщения в каталоге. domain — имя набора переводов, например learning, а не интернет-домен сайта. message — исходная строка-ключ; результат — обычная PHP строка, которую можно сохранить, форматировать и безопасно вывести. Если перевода нет, обычно возвращается исходный текст, поэтому отсутствие исключения ещё не подтверждает исправность настройки.

Приложение и модуль оплаты могут иметь разные каталоги. dgettext выбирает домен только для этого сообщения: после вызова глобальный текущий домен не изменяется. Поэтому библиотеке удобнее явно указывать собственный набор, чем переключать textdomain вокруг каждого вызова.

Примеры с require "gettext-lab.php" используют приложенный учебный каталог: Cart → «Корзина», Checkout → «Оформление заказа», три русские формы слова «товар». Он входит в скачиваемый пример. Нужны расширение gettext и доступная русская locale. Здесь каталог разворачивается из включённой MO-заготовки; в проекте его собирают из PO командой msgfmt, как показано в начале главы. Запуск отдельным CLI-процессом изолирует изменения locale и домена.

<?php
declare(strict_types=1);

require __DIR__ . '/gettext-lab.php';
echo gettext('Cart'), "\n";
echo dgettext('checkout', 'Cart'), "\n";
echo gettext('Cart'), "\n";

Корзина
Корзина оплаты
Корзина

<?php
declare(strict_types=1);

require __DIR__ . '/gettext-lab.php';
$mainTitle = dgettext('learning', 'Cart');
$paymentTitle = dgettext('checkout', 'Checkout');
echo $mainTitle, ' → ', $paymentTitle, "\n";

Корзина → Оформление заказа

Пустое имя домена начиная с PHP 8.4 вызывает ValueError. В реализации PHP 8.5.11 domain ограничен 1024 байтами, message — 4096. Не берите имя каталога напрямую из параметра запроса: приложение знает допустимые модули. Отсутствующий каталог может просто дать исходный текст; отдельно проверяйте развёртывание файлов и язык.

Рядом по задаче: gettext; dngettext; bindtextdomain; dcgettext.

• PHP: dgettext

PHP 4+ · gettext

ngettext(string $singular, string $plural, int $count): string

Выбрать языковую форму сообщения по количеству.

Gettext ищет перевод сообщения в каталоге. domain — имя набора переводов, например learning, а не интернет-домен сайта. message — исходная строка-ключ; результат — обычная PHP строка, которую можно сохранить, форматировать и безопасно вывести. Если перевода нет, обычно возвращается исходный текст, поэтому отсутствие исключения ещё не подтверждает исправность настройки.

Для подписи «1 товар / 2 товара / 5 товаров» недостаточно условия count===1. Язык перевода определяет число форм и правила их выбора. ngettext получает исходные единственное и множественное сообщения и количество; из MO выбирается нужная форма. Само число в строку функция не подставляет.

Примеры с require "gettext-lab.php" используют приложенный учебный каталог: Cart → «Корзина», Checkout → «Оформление заказа», три русские формы слова «товар». Он входит в скачиваемый пример. Нужны расширение gettext и доступная русская locale. Здесь каталог разворачивается из включённой MO-заготовки; в проекте его собирают из PO командой msgfmt, как показано в начале главы. Запуск отдельным CLI-процессом изолирует изменения locale и домена.

<?php
declare(strict_types=1);

require __DIR__ . '/gettext-lab.php';
$count = 2;
$pattern = ngettext('%d item', '%d items', $count);
echo $pattern, "\n";
echo sprintf($pattern, $count), "\n";

%d товара
2 товара

<?php
declare(strict_types=1);

require __DIR__ . '/gettext-lab.php';
foreach ([0, 1, 2, 5, 11, 21, 22] as $count) {
    echo sprintf(ngettext('%d item', '%d items', $count), $count), "\n";
}

0 товаров
1 товар
2 товара
5 товаров
11 товаров
21 товар
22 товара

<?php
declare(strict_types=1);

setlocale(LC_ALL, 'C');
putenv('LC_ALL=C');
putenv('LANGUAGE=');
textdomain('lesson-no-catalog');
foreach ([0, 1, 2] as $count) {
    echo sprintf(ngettext('%d item', '%d items', $count), $count), "\n";
}

0 items
1 item
2 items

count — int; для количества товаров используйте проверенное неотрицательное целое. Дробные величины, например «1,5 метра», требуют отдельной языковой модели, а не приведения к int. Каждая из двух исходных строк ограничена 4096 байтами в PHP 8.5.11. Не переводите только слово отдельно от предложения, если грамматика требует менять другие части фразы. Каталог должен содержать все формы и корректный Plural-Forms; переводчик отвечает за грамматику, программа — за корректные данные.

Рядом по задаче: gettext; dngettext; dcngettext.

• PHP: ngettext

PHP 4+ · gettext

dngettext(string $domain, string $singular, string $plural, int $count): string

Выбрать множественную форму в заданном домене.

Gettext ищет перевод сообщения в каталоге. domain — имя набора переводов, например learning, а не интернет-домен сайта. message — исходная строка-ключ; результат — обычная PHP строка, которую можно сохранить, форматировать и безопасно вывести. Если перевода нет, обычно возвращается исходный текст, поэтому отсутствие исключения ещё не подтверждает исправность настройки.

dngettext совмещает две потребности: выбрать каталог модуля и грамматическую форму по количеству. Текущий textdomain менять не нужно. В интерфейсе магазина и платёжном модуле могут быть свои переводы, но логика вызова остаётся одинаковой.

Примеры с require "gettext-lab.php" используют приложенный учебный каталог: Cart → «Корзина», Checkout → «Оформление заказа», три русские формы слова «товар». Он входит в скачиваемый пример. Нужны расширение gettext и доступная русская locale. Здесь каталог разворачивается из включённой MO-заготовки; в проекте его собирают из PO командой msgfmt, как показано в начале главы. Запуск отдельным CLI-процессом изолирует изменения locale и домена.

<?php
declare(strict_types=1);

require __DIR__ . '/gettext-lab.php';
$count = 5;
echo sprintf(dngettext('checkout', '%d item', '%d items', $count), $count), "\n";
echo textdomain(), "\n";

5 товаров
learning

<?php
declare(strict_types=1);

require __DIR__ . '/gettext-lab.php';
$cartCounts = ['current' => 1, 'saved' => 22];
foreach ($cartCounts as $cart => $count) {
    $label = sprintf(dngettext('learning', '%d item', '%d items', $count), $count);
    echo $cart, ': ', $label, "\n";
}

current: 1 товар
saved: 22 товара

Ограничения домена такие же, как у dgettext, а формы и количество — как у ngettext. С PHP 8.4 пустой domain вызывает ValueError. Если библиотека переключает глобальный домен и забывает вернуть его после ошибки, ломаются чужие надписи; явный параметр domain устраняет именно эту зависимость, но не глобальное состояние locale.

Рядом по задаче: ngettext; dgettext; dcngettext.

• PHP: dngettext

PHP 4+ · gettext

textdomain(?string $domain = null): string

Задать или узнать текущий набор переводов.

Gettext ищет перевод сообщения в каталоге. domain — имя набора переводов, например learning, а не интернет-домен сайта. message — исходная строка-ключ; результат — обычная PHP строка, которую можно сохранить, форматировать и безопасно вывести. Если перевода нет, обычно возвращается исходный текст, поэтому отсутствие исключения ещё не подтверждает исправность настройки.

textdomain задаёт набор, в котором gettext и ngettext будут искать сообщения без явного domain. Имя learning означает файл learning.mo внутри директории выбранного языка. Настройка возвращает текущее имя, а не содержимое каталога и не признак наличия перевода.

Примеры с require "gettext-lab.php" используют приложенный учебный каталог: Cart → «Корзина», Checkout → «Оформление заказа», три русские формы слова «товар». Он входит в скачиваемый пример. Нужны расширение gettext и доступная русская locale. Здесь каталог разворачивается из включённой MO-заготовки; в проекте его собирают из PO командой msgfmt, как показано в начале главы. Запуск отдельным CLI-процессом изолирует изменения locale и домена.

<?php
declare(strict_types=1);

require __DIR__ . '/gettext-lab.php';
echo textdomain(), "\n";
echo textdomain('checkout'), "\n";
echo gettext('Cart'), "\n";

learning
checkout
Корзина оплаты

<?php
declare(strict_types=1);

require __DIR__ . '/gettext-lab.php';
$previous = textdomain();
try {
    textdomain('checkout');
    echo gettext('Cart'), "\n";
    throw new RuntimeException('Учебная ошибка');
} catch (RuntimeException $error) {
    echo "Обработка ошибки\n";
} finally {
    textdomain($previous);
}
echo gettext('Cart'), "\n";

Корзина оплаты
Обработка ошибки
Корзина

<?php
declare(strict_types=1);

try { textdomain(''); }
catch (ValueError $error) { echo "Нужно непустое имя домена\n"; }

Нужно непустое имя домена

PHP 8.5.11 также отвергает имя "0" и имена длиннее 1024 байт. Настройка относится к процессу, а не к отдельному потоку или объекту. В многопоточном SAPI, coroutine-сервисе либо долгоживущем worker нельзя считать её личным полем текущего запроса. Инициализация один раз на обычный независимый процесс и явные домены уменьшают скрытые зависимости. Название установленного домена само по себе не доказывает, что MO загружен.

Рядом по задаче: gettext; dgettext; bindtextdomain.

• PHP: textdomain

PHP 4+ · gettext

bindtextdomain(string $domain, ?string $directory = null): string|false

Связать домен с директорией переводов или узнать путь.

Gettext ищет перевод сообщения в каталоге. domain — имя набора переводов, например learning, а не интернет-домен сайта. message — исходная строка-ключ; результат — обычная PHP строка, которую можно сохранить, форматировать и безопасно вывести. Если перевода нет, обычно возвращается исходный текст, поэтому отсутствие исключения ещё не подтверждает исправность настройки.

bindtextdomain отвечает на вопрос «где лежат наборы переводов?». Ей передают корень locale, а не путь прямо к MO и не каталог LC_MESSAGES. Затем libintl сама выбирает язык и ищет файл. Директория должна существовать и быть доступна серверному процессу.

<?php
declare(strict_types=1);

$directory = __DIR__ . '/locale';
if (!mkdir($directory, 0700)) throw new RuntimeException('Не создана директория');
$bound = bindtextdomain('learning', $directory);
var_dump($bound !== false);
var_dump(bindtextdomain('learning') === $bound);

bool(true)
bool(true)

<?php
declare(strict_types=1);

require __DIR__ . '/gettext-lab.php';
$root = bindtextdomain('learning');
var_dump($root !== false && is_dir($root));
echo dgettext('learning', 'Cart'), "\n";

bool(true)
Корзина

<?php
declare(strict_types=1);

$path = __DIR__ . '/not-created-locale';
var_dump(bindtextdomain('learning', $path));

bool(false)

Второй аргумент null читает существующую привязку с PHP 8.0.3, а с 8.4 его можно опустить. Пустая строка задаёт текущую рабочую директорию; для веб-приложения она может отличаться от директории скрипта, поэтому надёжнее абсолютный путь от __DIR__. В PHP 8.5.11 строка "0" тоже попадает в ветку текущей директории — не используйте её как путь. Возвращается полный путь или false при неудаче. Непустое имя домена длиной до 1024 байт обязательно в современной версии. Привязка хранится для процесса, не отдельно для потоков; несколько компонентов должны иметь разные имена наборов.

Рядом по задаче: textdomain; bind_textdomain_codeset; dgettext.

• PHP: bindtextdomain

PHP 4+ · gettext

bind_textdomain_codeset(string $domain, ?string $codeset = null): string|false

Задать кодировку возвращаемых переводов для домена.

Gettext ищет перевод сообщения в каталоге. domain — имя набора переводов, например learning, а не интернет-домен сайта. message — исходная строка-ключ; результат — обычная PHP строка, которую можно сохранить, форматировать и безопасно вывести. Если перевода нет, обычно возвращается исходный текст, поэтому отсутствие исключения ещё не подтверждает исправность настройки.

Кодировка файла каталога и кодировка возвращаемой PHP строки — разные настройки. bind_textdomain_codeset просит библиотеку выдавать переводы заданного домена в указанной кодировке. Для современного HTML/JSON обычно удобно единообразно использовать UTF-8 на всех этапах.

Примеры с require "gettext-lab.php" используют приложенный учебный каталог: Cart → «Корзина», Checkout → «Оформление заказа», три русские формы слова «товар». Он входит в скачиваемый пример. Нужны расширение gettext и доступная русская locale. Здесь каталог разворачивается из включённой MO-заготовки; в проекте его собирают из PO командой msgfmt, как показано в начале главы. Запуск отдельным CLI-процессом изолирует изменения locale и домена.

<?php
declare(strict_types=1);

require __DIR__ . '/gettext-lab.php';
echo bind_textdomain_codeset('learning', 'UTF-8'), "\n";
echo bind_textdomain_codeset('learning'), "\n";
echo gettext('Cart'), "\n";

UTF-8
UTF-8
Корзина

<?php
declare(strict_types=1);

require __DIR__ . '/gettext-lab.php';
bind_textdomain_codeset('learning', 'UTF-8');
$payload = ['title' => dgettext('learning', 'Cart')];
echo json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR), "\n";

{"title":"Корзина"}

Возврат string — имя установленной кодировки, false — отсутствие явной настройки или неудача. Нельзя считать false доказательством «сейчас ASCII»: библиотека может выбирать кодировку по locale. Поддержка конвертации зависит от сборки libintl/iconv; кодировку из пользовательского запроса не подставляют. При неверной декларации исходных байтов в PO нужно исправить сам каталог, а не наслаивать преобразования на уже повреждённую строку. Пустой domain запрещён с PHP 8.4; в PHP 8.5.11 имя домена ограничено 1024 байтами. Функция управляет привязкой домена внутри процесса.

Рядом по задаче: bindtextdomain; gettext; dgettext.

• PHP: bind_textdomain_codeset

PHP 4+ · gettext

dcgettext(string $domain, string $message, int $category): string

Перевести одно сообщение с явными доменом и категорией locale.

Gettext ищет перевод сообщения в каталоге. domain — имя набора переводов, например learning, а не интернет-домен сайта. message — исходная строка-ключ; результат — обычная PHP строка, которую можно сохранить, форматировать и безопасно вывести. Если перевода нет, обычно возвращается исходный текст, поэтому отсутствие исключения ещё не подтверждает исправность настройки.

dcgettext добавляет к явному домену категорию locale. Для обычных сообщений это LC_MESSAGES; редкий специальный каталог может быть связан с другой категорией. Это не категория товаров и не рубрика сайта, а системная группа настроек локали. Большинству приложений достаточно dgettext.

<?php
declare(strict_types=1);

setlocale(LC_ALL, 'C');
putenv('LC_ALL=C');
putenv('LANGUAGE=');
echo dcgettext('lesson-no-catalog', 'Invoice', LC_TIME), "\n";

Invoice

<?php
declare(strict_types=1);

// Нужно: gettext, установленная ru_RU.UTF-8 и locale/ru/LC_MESSAGES/learning.mo.
if (!defined('LC_MESSAGES')) throw new RuntimeException('Категория LC_MESSAGES недоступна');
if (setlocale(LC_MESSAGES, 'ru_RU.UTF-8') === false) throw new RuntimeException('Locale не установлена');
putenv('LANGUAGE=ru');
if (bindtextdomain('learning', __DIR__ . '/locale') === false) throw new RuntimeException('Нет каталога');
bind_textdomain_codeset('learning', 'UTF-8');
echo dcgettext('learning', 'Cart', LC_MESSAGES), "\n";

Корзина

<?php
declare(strict_types=1);

try { dcgettext('learning', 'Cart', LC_ALL); }
catch (ValueError $error) { echo "Нужна отдельная категория\n"; }

Нужна отдельная категория

Для category используют поддерживаемую отдельную LC_* константу платформы. Она определяет категорию поиска; текущий textdomain остаётся прежним. Ограничения domain/message такие же, как у dgettext. Межплатформенность важна: даже наличие функции dcgettext не гарантирует наличие LC_MESSAGES. Если специальные категории не требуются, dgettext оставляет эти детали библиотеке.

Рядом по задаче: dgettext; dcngettext; gettext.

• PHP: dcgettext

PHP 4.2+ · gettext

dcngettext(string $domain, string $singular, string $plural, int $count, int $category): string

Выбрать форму сообщения, явно задав домен и категорию.

Gettext ищет перевод сообщения в каталоге. domain — имя набора переводов, например learning, а не интернет-домен сайта. message — исходная строка-ключ; результат — обычная PHP строка, которую можно сохранить, форматировать и безопасно вывести. Если перевода нет, обычно возвращается исходный текст, поэтому отсутствие исключения ещё не подтверждает исправность настройки.

dcngettext объединяет явный домен, категорию locale и выбор множественной формы. Это специализированный вариант dngettext, когда приложению действительно нужно управлять категорией поиска. Выбранная форма по-прежнему возвращается шаблоном, а значения подставляет sprintf.

<?php
declare(strict_types=1);

setlocale(LC_ALL, 'C');
putenv('LC_ALL=C');
putenv('LANGUAGE=');
foreach ([1, 3] as $count) {
    $pattern = dcngettext('lesson-no-catalog', '%d invoice', '%d invoices', $count, LC_TIME);
    echo sprintf($pattern, $count), "\n";
}

1 invoice
3 invoices

<?php
declare(strict_types=1);

// Нужны русский MO и доступная системная locale, как в начале главы.
if (!defined('LC_MESSAGES')) throw new RuntimeException('Нет LC_MESSAGES');
if (setlocale(LC_MESSAGES, 'ru_RU.UTF-8') === false) throw new RuntimeException('Нет locale');
putenv('LANGUAGE=ru');
if (bindtextdomain('learning', __DIR__ . '/locale') === false) throw new RuntimeException('Нет каталога');
bind_textdomain_codeset('learning', 'UTF-8');
$count = 22;
echo sprintf(dcngettext('learning', '%d item', '%d items', $count, LC_MESSAGES), $count), "\n";

22 товара

Пустой домен в PHP 8.4+ запрещён. LC_ALL не принимается как отдельная категория и вызывает ValueError. Для negative/fractional счётчиков не пытайтесь угадывать грамматику через принудительное приведение: сначала определите смысл количества. Если категория вам не нужна, у dngettext меньше параметров и меньше платформенных зависимостей. Выбор формы и язык не устраняют необходимость экранировать результат при выводе в HTML.

Рядом по задаче: dngettext; ngettext; dcgettext.

• PHP: dcngettext