apply_filters() — вызывается там, где применяется фильтр. Запускает добавленные к фильтру PHP функции.
add_filter() — добавляет/прикрепляет PHP функции к указанному фильтру. Используется до того, как фильтр будет применен/вызван/запущен с помощью apply_filters(). Нужно это для того, чтобы, во время срабатывания фильтра, PHP функция уже была подключена к фильтру и обработала переданное значение (отфильтровала его).

$myvar = apply_filters( $tag, $value, $var1, $var2, … );

add_filter( $tag, $function_to_add, $priority, $accepted_args );

Для работы события также используются две функции:

do_action() — это и есть событие. Запускает/вызывает добавленные к событию функции. Вызывается там, где должно сработать событие.
add_action() — добавляет/прикрепляет функции к событию, которое вызывается с помощью do_action(). Функция должна прикрепляться к событию до того, как событие произойдет. Нужно это, чтобы во время срабатывания события PHP функции уже были прикреплены к событию.

do_action( $tag, $arg_a, $arg_b, … );

add_action( ‘my_hook’, ‘do_my_hook’, 10, 2 );

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

// Пример ——————————
// Простое удаление
add_filter(‘my_filter’, ‘function_name’);    // так добавлен
remove_filter(‘my_filter’, ‘function_name’); // так нужно удалять
// Пример ——————————
// Удаление с приоритетом
add_filter(‘my_filter’, ‘function_name’, 99);    // так добавлен
remove_filter(‘my_filter’, ‘function_name’, 99); // так нужно удалять — приоритет должен совпадать…
// Пример ——————————
// Удаление статического метода класса
add_filter(‘my_filter’, array(‘My_Class’, ‘method_name’), 15 );   // так добавлен
remove_filter(‘my_filter’, array(‘My_Class’, ‘method_name’), 15); // так нужно удалять — приоритет должен совпадать…
// Пример ——————————
// Удаление не статического метода класса, который добавлен с использованием $this
class A{
function __construct(){
add_action(‘my_action’, array( & $this, ‘method_name’), 15 );   // так добавлен
}
function method_name(){ echo ‘Привет!’; }
}
$class = new A; // экземпляр
// для удаления нужно найти переменную в которую был сохранен экземпляр класса при создании, сейчас это $class
remove_action(‘my_action’, array( $class, ‘method_name’), 15 );   // так нужно удалять
// Пример ——————————
// Удалить хук добавленный лямбда-функцией (замыканием) невозможно!
add_action(‘my_action’, function(){ echo ‘Привет!’; } );   // так добавлен
// никак не удалить, даже так:
remove_action(‘my_action’, function(){ echo ‘Привет!’; });

Все функции хуков

Функция	Описание
add_action	Регистрирует хук-событие. При регистрации указывается PHP функция, которая сработает в момент события, которое вызывается с помощью do_action().
did_action	Получает число, сколько раз было выполнено данное событие (хук).
do_action	Создает событие (зацепку для произвольной функции). Чтобы функция сработала в момент события её нужно подключить к этому событию с помощью функции add_action().
do_action_ref_array	Создает хук (действие) для зацепки функции. Аргументы передаются из массива.
has_action	Проверяет была ли зарегистрирована функция для хука (действия).
remove_action	Удаляет функцию прикрепленную к указанному хуку (событию).
add_filter	Прикрепляет указанную PHP функцию к указанному хукe-фильтру. Так, во время срабатывания фильтра значение будет обработано указанной PHP функцией.
apply_filters	Применяет прикрепленную к указанному фильтру PHP функцию. Прикрепляется функция с помощью add_filter().
apply_filters_ref_array	Выполняет функции прикрепленные к указанному хуку (фильтру). Параметры передаются в массиве.
current_filter	Получает название текущего действия или фильтра.
doing_filter	Проверяет обрабатывается ли указанный хук (фильтр или событие), в текущий момент.
has_filter	Проверяет была указана дли для фильтра какая-нибудь функция, т.е. имеется ли указанный хук.
remove_all_filters	Удаляет все хуки у указанного фильтра.
remove_filter	Удаляет указанную функцию прикрепленную к указанному фильтру.

Специальные функции интернационализации

Функция	Описание
__()	Переводит указанный текст, используя файл перевода и возвращает его для обработки.
_e()	Переводит указанный текст, используя файл перевода и выводит его на экран.
_n()	Выбирает строку, которая будет использована для перевода единственного или множественного числа переданного в функцию (1 комментарий, 2 комментария). Функция локализации.
_x()	Переводит указанный текст, на основе указанного контекста. Использует файл перевода.
_ex()	Функция _ex() является полным аналогом функции _x(), с единственным исключением, что _x() — возвращает результат, а _ex() выводит его на экран.
date_i18n()	Получает локализованную дату (переведенную на текущий язык) из переданного штампа времени unix. Локализация PHP функции date().
esc_attr__()	Переводит с использованием функции esc_attr().
esc_attr_e()	Выводит переведенный текст, прежде очищенный функцией esc_attr().
esc_html__()	Переводит строку заменяя в ней спецсимволы на HTML сущности. Возвращает текст, которой можно отображать в HTML как HTML код.
esc_html_e()	Переводит строку и заменяет в ней спецсимволы на HTML сущности. Выводит на экран текст, которой можно отображать в HTML как HTML код.
get_locale()	Устанавливает глобальную переменную $locale и получает текущую локаль (индекс языка сайта). По умолчанию ‘en_US’.
get_user_locale()	Получает локаль (язык перевода) текущего или указанного пользователя.
is_locale_switched()	Проверяет была ли переключена локаль (язык перевода), была ли использована функция switch_to_locale().
load_child_theme_textdomain()	Загружает файл перевода дочерней темы (.mo) в память, для дальнейшей работы с ним.
load_plugin_textdomain()	Загружает строку для перевода плагина.
load_textdomain()	Подключает домен и .mo файл в данные локализации.
load_theme_textdomain()	Загружает файл перевода темы (.mo) в память, для дальнейшей работы с ним.
switch_to_locale()	Позволяет программно переключить язык сайта.
translate()	Получает перевод указанного текста.
unload_textdomain()	Выгружает (удаляет, отменяет) подключенный файл перевода.

Установка заголовков перевода

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

Text Domain используется для обозначения текста, принадлежащего плагину, это уникальный идентификатор, который обеспечивает возможностью различать все загруженные переводы и должен совпадать со slug плагина. Например, если главный файл плагина называется step-by-step-development-plugin.php и он содержится в папке step-by-step-development-plugin, то Text Domain должен быть step-by-step-development-plugin.

Domain Path это папка, в которой WordPress будет искать файлы перевода .mo. По умолчанию, WordPress ищет файлы переводов в корневой папке плагина. Однако размещение файла перевода в корневой папке может дезорганизовать структуру плагина.
Если вы хотите хранить файлы перевода в другой папке, например: /languages, необходимо сообщить об этом WordPress, используя заголовок Domain Path.

Отредактируем основный файл плагина step-by-step-development-plugin.php

/*
Plugin Name: Step By Step Development Plugin

…

Author URI: https://www.linkedin.com/in/solomashenkoroman/
Text Domain: step-by-step-development-plugin
Domain Path: /languages/
License: A «Slug» license name e.g. GPL2

…

Имя текстового домена также используется для формирования имени MO-файла перевода плагина.

Загружаем строку для перевода плагина load_plugin_textdomain, на этапе выполнения действия plugins_loaded.

<?php load_plugin_textdomain( $domain, $deprecated, $plugin_rel_path ) ?>
Если путь не указан, то им будет корневая директория плагинов.

.mo файл должен называться: $domain-локаль, где локаль это код языка или страны. Например, немецкая локаль — de_DE, русская — ru_RU. Если $domain (ключ файла переводов) my-plugin, то русские .mo и .po файлы должны назваться: my-plugin-ru_RU.mo и my-plugin-ru_RU.po.

Вызывать функцию нужно через хук plugins_loaded.

Генерация POT-файла для плагина или темы

Для этого предназначена утилита xgettext, как часть функциональности gettext. Сначала необходимо установить пакет gettext (если вы хотите пользоваться функциями интернационализации). Если ваш плагин зарегистрирован в официальном репозитории, для генерации файла используйте инструмент Admin->Generate POT file в админ-панели репозитория.

Можно скачать пустой шаблон POT файла https://github.com/fxbenard/Blank-WordPress-Pot в папку languages плагина.

Вместе с шаблоном POT файла идет файлик How-to-use-a-pot-file.txt в нем описано что нужно сделать чтобы создать файл перевода:

Открыть программу Poedit
Теперь нам нужно создать POT файл на основе пустого шаблона POT, который мы скачали: Файл->Создать из POT файла
Выбираем шаблон POT файла
Создадим POT файл для русской локализации ru_RU: step-by-step-development-plugin-ru_RU.po, английской: step-by-step-development-plugin-en_US.po

Теперь в Poedit откроем файл step-by-step-development-plugin-ru_RU.po или step-by-step-development-plugin-en_US.po. Обновим содержание, добавляем перевод и сохраняем.

Формат английского языка

Categories : Word Press, www

Discussions

admin 11 декабря, 2017

— в основном файле плагина wp-my-homework.php добавил 2 заголовка: Text Domain и Domain Path

/*
Plugin Name: WP My Home Work Plugin

…

Author URI: https://www.linkedin.com/in/rostyslav-naryzhniak-839513150/
Text Domain: wp-my-homework
Domain Path: /languages/
License: A “Slug” license name e.g. GPL2

…

— подключил класс includes\common\HomeWorkLocalization который будет отвечать за загрузку файлов перевода
namespace includes\common;

class HomeWorkLocalization
{
private static $instance = null;
private function __construct() {
add_action(‘plugins_loaded’, array(&$this, ‘localization’));
}
public static function getInstance() {

if ( null == self::$instance ) {
self::$instance = new self;
}

return self::$instance;

}

public function localization(){
/**
* load_plugin_textdomain( $domain, $deprecated, $plugin_rel_path )
* $domain — Уникальный идентификатор для получения строки перевода. (константа STEPBYSTEP_PlUGIN_TEXTDOMAIN
* заданая в файле config-path.php)
* $deprecated — Отмененный аргумент, работает до версии 2.7. Путь подобный ABSPATH, до .mo файла.
* $plugin_rel_path — Путь (с закрывающим слэшем) до каталога .mo файлов относительно WP_PLUGIN_DIR.
* Этот аргумент следует использовать вместо $abs_rel_path.
* (константа STEPBYSTEP_PlUGIN_DIR_LOCALIZATION заданая в файле config-path.php)
*/
load_plugin_textdomain(STEPBYSTEP_PlUGIN_TEXTDOMAIN, false, STEPBYSTEP_PlUGIN_DIR_LOCALIZATION);
}
}

Вызвал класс includes\common\HomeWorkLocalization в загрузчике классов includes\common\HomeWorkAutoLoad в методе all()

/**
* Метод будет срабатывать везде
*/
public function all(){
HomeWorkLocalization::getInstance();
HomeWorkExampleAction::newInstance();
}

— скачал пустой шаблон POT файла https://github.com/fxbenard/Blank-WordPress-Pot в папку languages плагина

— сгенерировал файл POT для русской локализации ru_RU (Poedit), обновил сайт и сохранил перевод

#6. Hooks, Filters, InterNation

Latest Posts