Как переводить плагины и темы в WordPress
Опубликовано: 01.09.2018
В этом посту я покажу вам простой и полностью рабочий способ создания перевода для своей WordPress-темы или плагина. Также вы сможете переводить темы и плагины других разработчиков.
Исходный код мы переводить не будем! Вообще, это непрофессионально и так делают те, кто только начинает осваивать WordPress.
Подготовка. Функции __() и _e()
Перед тем, как создавать перевод, убедитесь, что всё, что нужно переводить в вашем плагине или в теме заключено в функции __() и _e() . Перейдя по ссылкам, вы сможете ознакомиться с документацией функций, а сейчас мы посмотрим на примеры.
Перевод тем и плагинов WordPress
Вообще для перевода в WordPress существует гораздо больше функций, самые часто встречающиеся перечислены у меня в Кодексе в категории «Локализация», но пока что мы начнем с самых простых.
Итак, допустим в коде у нас есть текст «Hello World!» и нам нужно перевести его в «Привет, мир!», тогда:
Простой способ переводов тем и плагинов. Плагин Loco Translate
| echo __ ( 'Hello World!' ,'truemisha' ) ; |
Второй аргумент функции, «truemisha» — это название перевода, может быть произвольным (главное, чтобы он совпадал с аналогичным параметром при подключении файлов перевода), также обычно совпадает с названием директории темы или плагина. Этот параметр не обязателен, если его не указывать, то для перевода будут задействованы стандартные языковые файлы, те, которые используются для перевода самого движка, админки. Понятное дело, что в стандартных языковых файлах может и не быть перевода тех строк, которые будут в нашей теме или в плагине.
Такой же пример, но с использованием функции _e() :
| _e ( 'Hello World!' ,'truemisha' ) ; |
Итак, если нам надо вывести переведенную строку, мы используем функцию _e() , а если нужно записать строку в переменную или задействовать в качестве аргумента какой-либо функции, то используем __() .
Подготавливаем свою тему или плагин к переводу и переходим к следующему шагу.
Создание POT-файла. Использование программы Poedit
Нам понадобится программа Poedit , бесплатная версия вполне подойдет.
Открываем ее и переходим Файл > Создать. Указываем язык перевода, в нашем случае будет русский. Переходим Каталог > Свойства, после чего у нас открывается три вкладки. Вкладка «Свойства перевода». Каких-либо особых требований к ее заполнению нет, главное, чтобы кодировка была UTF-8. Вот как получилось у меня: Вкладка «Папки с исходными файлами». Не обращая внимания на уведомление, нажимаем кнопку «Новый элемент»
и добавляем точку ., что означает искать во всех php-файлах, которые будут находиться в той же директории, что и наш файл перевода.
Вкладка «Ключевые слова исходных файлов». Указываем здесь функции __() и _e() . Затем нажимаем ОК.
Если вы работаете над переводом готовой темы или плагина, я рекомендую в ключевые слова добавить как минимум следующие выражения (на самом деле их больше, но по моим наблюдениям эти чаще всего используются):
| 1 2 3 4 5 6 7 | __ _e _n:1,2 esc_attr__ esc_attr_e esc_html__ esc_html_e |
Описание каждой из этих функций вы найдете в Кодексе WordPress на моем сайте.
В 3-й строке листинга у функции _n() есть дополнение в виде :1,2, это означает, что первый параметр функции — форма единственного числа, второй параметр — форма множественного числа. Подробнее про множественного число читайте далее в этой статье.
Осталось всё это дело сохранить. Файл > Сохранить, там где тип файла указываем все файлы, расширение ставим .pot. Сохраняем прямо в директорию своего плагина или темы. Заходим в папку, куда вы только что сохранили файл перевода и удаляем из нее ненужный пока что файл с расширением .mo. В Poedit нажимаем кнопку «Обновить» либо Каталог > Обновить из исходного кода. Та-дам, в окне программы должны появиться все строки, доступные для перевода. Переводим, сохраняем.Подключаем языковые файлы в плагине или теме
Рассмотрим также пошагово:
Создаем в вашей теме или плагине папку languages (на самом деле вы можете назвать ее как угодно). Открываем наш pot-файл, затем Файл > Сохранить как, выбираем созданную папку, указываем расширение .po. Что касается названия языкового файла, то оно должно быть следующего вида: Для плагинов: {название перевода}-{название языка}, например для русского перевода: truemisha-ru_RU.po и truemisha-ru_RU.mo. Для тем же просто ru_RU.po и ru_RU.moОкей, про {название перевода} я уже писал ранее в этом посту, но откуда брать {название языка}? Всё просто — откройте файл wp-config.php и посмотрите значение константы WPLANG.
Если мы переводим тему, открываем файл 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() .
Как настроить множественное число для русского языка
Допустим, мы выводим количество товаров в своей теме интернет-магазина. Как сделать так, чтобы в зависимости от количества товаров, выводилась соответствующая форма слова, например: 1 товар, 2 товара, 5 товаров?
Кстати говоря, если у вас трудности с множественным числом в Poedit, можете попробовать эту php-функцию .
Итак, для начала нам надо донастроить наш .pot-файл, открываем его в 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 ; |
Также вы можете указать «Использовать правила по умолчанию для этого языка» (не во всех версиях Poedit).
Теперь в этом же окошке переходим во вкладку «Ключевые слова исходных файлов» и дописываем туда функцию _n() следующим образом: _n:1,2. Вот что получится:
В вашем плагине или теме уже используется функция _n() ? Если нет, тогда вот вам пример кода:
| $products = '4' ; $text = sprintf ( _n ( '1 product' , '%s product' , $products , 'truemisha' ) , $products ) ; echo $text ; |
Окей, теперь сохраняем и обновляем .pot-файл. Как видите, для задания форм слова у нас сейчас имеется три поля, указываем в них: 1 товар, %s товара и %s товаров соответственно.
Отлично, всё, что осталось сделать, это сохранить перевод в форматах .po и .mo в папку languages (читайте об этом подробнее выше в посту).
Напоследок хочу добавить: если вы всё сделали правильно, но перевод не заработал, убедитесь, что вы используете русскоязычную версию WordPress (если переводите на русский конечно), в файле wp-config.php должна быть строка:
| define ( 'WPLANG' , 'ru_RU' ) ; |
Как изменять язык темы в зависимости от параметра в 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.
Скачать и установить его на сайт вы можете через меню Плагины > Добавить новый.