Переводим плагины и темы в WordPress

L10n  /  42 комментария

В этом посту я покажу вам простой и полностью рабочий способ создания перевода для своей WordPress-темы или плагина. Также вы сможете переводить темы и плагины других разработчиков.

Исходный код мы переводить не будем! Вообще, это непрофессионально и так делают те, кто только начинает осваивать WordPress.

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

Пошаговое руководство по переводу

1. Интернационализация. Подготовка к переводу

Перед тем, как создавать перевод, убедитесь, что всё, что нужно переводить в вашем плагине или в теме заключено в специальные функции перевода, вот эти функции:

Кроме того, часть этих функций даже есть уже со встроенной очисткой данных:

Итак, допустим в коде у нас есть текст «Hello World!» и нам нужно перевести его в «Привет, мир!», тогда:

echo __( 'Hello World!', 'truemisha' );

Второй аргумент функции, «truemisha» — это название перевода, может быть произвольным (главное, чтобы он совпадал с аналогичным параметром при подключении файлов перевода), также обычно совпадает с названием директории темы или плагина. Этот параметр не обязателен, если его не указывать, то для перевода будут задействованы стандартные языковые файлы, те, которые используются для перевода самого движка, админки. Понятное дело, что в стандартных языковых файлах может и не быть перевода тех строк, которые будут в нашей теме или в плагине.

Такой же пример, но с использованием функции _e():

_e( 'Hello World!', 'truemisha' );

Итак, если нам надо вывести переведенную строку, мы используем функцию _e(), а если нужно записать строку в переменную или задействовать в качестве аргумента какой-либо функции, то используем __().

Кроме того, если выводимый код нуждается в очистке, то наша строчка кода снова видоизменяется:

<h1><?php esc_html_e( 'Hello World!', 'truemisha' ); ?></h1>

Итак, подготавливаем свою тему или плагин к переводу и переходим к следующему шагу.

2. Настройка Poedit. Локализация

Нам понадобится программа Poedit, бесплатная версия вполне подойдет.

Открываем программу и переходим в Файл > Создать (File > New), после чего нам будет предложено выбрать язык перевода.

Переходим в Каталог > Свойства (Transations > Properties), и у нас откроется три вкладки с настройками. Сначала заполняем первую вкладку. Каких-либо особых требований к ее заполнению нет, главное, чтобы кодировка была UTF-8. Вот как получилось у меня:

Свойства перевода в Poedit

Далее – вкладка «Ключевые слова исходных файлов». Указываем тут все используемые при интернационализации функции. Затем нажимаем ОК.

Ключевые слова исходных файлов, Poedit

Вот чуть более подробный их список:

__
_e
_n:1,2
_n_noop:1,2
_x:1,2c
_ex:1,2c
_nx:4c,1,2
esc_attr__
esc_attr_e
esc_attr_x:1,2c
esc_html__
esc_html_e
esc_html_x:1,2c

Думаю сейчас не помешает совсем немного объяснений.

  • Функция __() принимает только один параметр для перевода, вторым является идентификатор перевода. Все функции перевода, которые имеют только два таких параметра, указываются в Poedit лишь в виде названия.
  • Функция множественного числа _n() имеет на конце :1,2, что означает, что первый и второй параметр функции должны быть переведены.
  • _x() имеет на конце :1,2c, что означает, что первый параметр функции должен быть переведён, а второй параметр является контекстом перевода.
  • Функция _nx() является комбинацией функций _n() и _x() у неё на конце аж :4c,1,2, что значит, что четвёртный параметр функции является контектом, а первый и второй должны быть переведены.

Далее – вкладка «Папка с исходными файлами». Новая версия Poedit вообще не позволяет делать в ней никаких изменений пока мы не сохраним файл. Ну окей.

  1. Закрываем эти настройки нажатием кнопки ОК.
  2. Переходим в Файл > Сохранить.
  3. Переходим в папку с нашей темой или плагином.
  4. В ней создаём папку languages.
  5. Сохраняем в неё, но главное указать правильное название файла! Для плагинов это {название перевода}-{название языка}, например для русского перевода: truemisha-ru_RU.po и truemisha-ru_RU.mo. Для тем же просто ru_RU.po и ru_RU.mo

    Окей, про {название перевода} я уже писал ранее в этом посту, но откуда брать {название языка}? Всё просто — откройте файл wp-config.php и посмотрите значение константы WPLANG

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

Почти готово – сохраняем. Затем нажимаем кнопку «Обновить» либо Каталог > Обновить из исходного кода. Та-дам, в окне программы должны появиться все строки, доступные для перевода.

Переводим, сохраняем.

3. Подключаем языковые файлы в плагине или теме

Если мы переводим тему, открываем её файл functions.php и добавляем туда следующий код:

add_action('after_setup_theme', 'true_load_theme_textdomain');
 
function true_load_theme_textdomain(){
	load_theme_textdomain( 'truemisha', get_template_directory() . '/languages' );
}

Первый аргумент функции load_theme_textdomain() — это название перевода, оно же используется в функциях __() и _e(), второй аргумент — путь к директории с языковыми файлами. Функция get_template_directory() используется для получения пути к директории текущей темы.

Если мы переводим плагин, то открываем главный исполняемый файл плагина и вставляем туда:

add_action( 'plugins_loaded', 'true_load_plugin_textdomain' );
 
function true_load_plugin_textdomain() {
	load_plugin_textdomain( 'truemisha', false, dirname( plugin_basename( __FILE__ ) ) . '/languages/' ); 
}

Как видите, для плагинов мы используем другую функцию — load_plugin_textdomain(). Её единственное отличие — это второй аргумент, который не используется в новых версиях WordPress и всегда должен быть равен false. А для получения пути к директории плагина, воспользуемся plugin_basename().

Хотите разобраться с локализацией на реальных примерах? Тогда вот вам два видеоурока, один – про локализацию темы WordPress, другой – про локализацию плагина.

Как настроить множественное число для русского языка

Допустим, мы выводим количество товаров в своей теме интернет-магазина. Как сделать так, чтобы в зависимости от количества товаров, выводилась соответствующая форма слова, например: 1 товар, 2 товара, 5 товаров?

На самом деле в свежих версиях Poedit уже практически всё сделано за нас. Во вкладке свойств перевода при выборе языка уже будет вставлено соответствующее выражение для обработки форм множественного числа.

Настройка множественного числа в русском языке в Poedit

Хотя у нас есть возможность его изменить.

По умолчанию для русского языка это:

nplurals=3; plural=(n%10==1 &;&; n%100!=11) ? 0 : ((n%10>=2 &;&; n%10<;=4 &;&; (n%100<;10 || n%100>=20)) ? 1 : 2);

Это выражение позволяет использовать три формы множественного числа (именно столько используется в русском языке.

Вот выражение для двух форм (английский язык например) :

nplurals=2; plural=n != 1;

Для четырех форм (словенский язык) :

nplurals=4; plural=n%100==1 ? 0 : n%100==2 ? 1 : n%100==3 || n%100==4 ? 2 : 3;

Теперь в этом же окошке переходим во вкладку «Ключевые слова исходных файлов» и дописываем туда функцию _n() следующим образом: _n:1,2. Вот что получится:

Функция _n в настройках языкогового файла в Poedit.

Возможно вы ещё захотите использовать функцию _nx().

Непосредственно в файлах темы или плагина функция используется в комбинации с PHP-функцяими sprintf() или printf(). Например:

$products = 4;
$text = sprintf( _n( '1 product', '%s product', $products, 'truemisha' ), $products );
echo $text;

Окей, теперь сохраняем и обновляем файл перевода. Как видите, для задания форм слова у нас сейчас имеется три поля, указываем в них: 1 товар, %s товара и %s товаров соответственно.

множественное число в Poedit

Как изменять язык темы в зависимости от параметра в URL?

Вставляем этот код в functions.php текущей темы. Затем, если в URL дописать что-то типа ?lang=ru_RU, то язык темы изменится для страницы, на которой вы находитесь.

add_filter( 'locale', 'true_localize_theme' );
 
function true_localize_theme( $locale ) {
	if ( isset( $_GET[ 'lang' ] ) ) {
		return esc_attr( $_GET[ 'lang' ] );
	}
	return $locale;
}

Частые ошибки. Как правильно и как неправильно.

Правило 1. Не используйте переменные в функциях перевода WordPress

Неправильно:

$result = __( $string, 'truemisha' );
$result = __( "You have $number bananas", 'truemisha' );
$result = __( 'You have 5 bananas', $domain );
$result = __( 'You have 5 bananas', PLUGIN_DOMAIN );

Правильно:

$result = __( 'You have 5 bananas', 'truemisha' );

Правило 2. Переводите фразы, а не строки

Неправильно:

$result = __( 'You have ', 'truemisha' ) . $number . __( ' bananas', 'truemisha' );

Правильно:

$result = sprintf( __( 'You have %d bananas', 'truemisha' ), $number );

Так как вы никогда не скажете «У тебя 1 бананов», то даже правильнее будет использовать функцию _n(), например:

$result = sprintf( _n( 'You have %d banana.', 'You have %d bananas.', $number, 'truemisha' ), $number );

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

Зачем давать переводчику возможность изменять разметку нашей темы? Теги HTML должны быть отделены от переводимых строк везде, где это возможно.

Неправильно:

$result = sprintf( __( '<h3>You have %d bananas</h3>', 'truemisha' ), $number );

Правильно:

$result = '<h3>' . sprintf( __( 'You have %d bananas', 'truemisha' ), $number ) . '</h3>';

Плагины перевода

Конечно же, не обязательно всё делать вручную (хотя я почти всегда делаю), существуют плагины, позволяющие автоматически из админки генерировать .po- и .mo-файлы, один из таких плагинов — Codestyling Localization.

Скачать и установить его на сайт вы можете через меню Плагины > Добавить новый.

Миша

Впервые познакомился с WordPress в 2009 году. Организатор и спикер на конференциях WordCamp. Преподаватель в школе Нетология.

Пишите, если нужна помощь с сайтом или разработка с нуля.

Комментарии — 42

Чтобы оставить комментарий, пожалуйста, зарегистрируйтесь или войдите.

Миша Рудрастых и WordPress

Полезности из мира WordPress и жизни студии.

Мой телеграм-канал