Функция translate_with_gettext_context() в WordPress

Функция translate_with_gettext_context() в WordPress предназначена для получения перевода текста с учетом контекста. Эта функция особенно полезна, когда один и тот же текст может иметь разные переводы в зависимости от контекста его использования. Однако, как и в случае с translate(), не рекомендуется использовать её напрямую. Вместо этого рекомендуется использовать функции-обертки, такие как _x().

translate_with_gettext_context( string $text, string $context, string $domain = 'default' ): string

Параметры

• $text (string, обязательный): Текст, который нужно перевести.
• $context (string, обязательный): Контекст, который помогает переводчикам понять, как должен быть переведен текст.
• $domain (string, необязательный): Текстовая область (домен), уникальный идентификатор для получения переведенных строк. По умолчанию используется 'default'.

Возвращаемое значение

• string: Возвращает переведенный текст, если перевод найден. Если перевод не найден или текстовая область не загружена, возвращается оригинальный текст.

Описание

Функция translate_with_gettext_context() работает аналогично функции translate(), но она позволяет передавать дополнительный контекст для переводчиков. Это может быть полезно, если одно и то же слово или фраза имеют разные значения в зависимости от их использования. Например, слово «lead» может означать «вести» или «свинец», в зависимости от контекста.

Рекомендации

Так же, как и в случае с функцией translate(), рекомендуется использовать функции-обертки, такие как _x(), для работы с переводами. Это обеспечит лучшую совместимость и более удобный интерфейс для разработчиков.

Пример 1: Простой перевод с контекстом

В этом примере мы используем функцию translate_with_gettext_context() для получения перевода текста с учетом контекста.

$text = 'Lead';
$context = 'metal'; // Указываем контекст, что это свинец
$domain = 'my-textdomain';

$translated_text = translate_with_gettext_context($text, $context, $domain);
echo $translated_text;

В этом случае, если перевод для слова «Lead» в контексте «metal» существует, он будет выведен. Если перевод отсутствует, будет выведен оригинальный текст.

Пример 2: Использование в теме

В этом примере мы покажем, как использовать перевод с контекстом в рамках темы:

add_action('wp_footer', function() {
    $text = 'Lead';
    $context = 'to guide';
    $domain = 'my-textdomain';

    // Получаем перевод с учетом контекста
    $translated_text = translate_with_gettext_context($text, $context, $domain);
    
    echo '<footer>' . esc_html($translated_text) . '</footer>';
});

В этом примере текст «Lead» будет переведен с учетом контекста «to guide» и выведен в нижнем колонтитуле сайта.

Пример 3: Использование с пользовательскими текстами

Если у вас есть пользовательский текст, который нужно перевести с учетом контекста, вы можете сделать следующее:

function my_custom_message() {
    $text = 'Lead';
    $context = 'to guide'; // Указываем контекст
    $domain = 'my-textdomain';

    // Переводим текст с учетом контекста
    $translated_text = translate_with_gettext_context($text, $context, $domain);

    return $translated_text;
}

// Выводим сообщение
echo my_custom_message();

В этом примере функция my_custom_message() возвращает переведенное сообщение с учетом контекста. Если перевод отсутствует, вернется оригинальный текст.

Заключение

Функция translate_with_gettext_context() является мощным инструментом для получения переводов текста с учетом контекста, что позволяет обеспечить более точные переводы в различных ситуациях. Хотя использование этой функции напрямую не рекомендуется, знание её работы поможет вам лучше понимать систему перевода в WordPress. Используя функции-обертки, такие как _x(), вы сможете более эффективно управлять переводами и улучшить пользовательский опыт на вашем сайте.