Переводим плагины и темы в WordPress (в том числе и свои собственные)

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

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

Подготовка. Функции __() и _e()

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

Вообще для перевода в WordPress существует гораздо больше функций, самые часто встречающиеся перечислены у меня в Кодексе в категории «Локализация», но пока что мы начнем с самых простых.

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

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

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

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

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

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

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

Создание POT-файла. Использование программы Poedit

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

  1. Открываем ее и переходим Файл > Создать.
  2. Указываем язык перевода, в нашем случае будет русский.
  3. Переходим Каталог > Свойства, после чего у нас открывается три вкладки.
  4. Вкладка «Свойства перевода». Каких-либо особых требований к ее заполнению нет, главное, чтобы кодировка была UTF-8. Вот как получилось у меня:
    Свойства перевода в Poedit
  5. Вкладка «Папки с исходными файлами». Не обращая внимания на уведомление, нажимаем кнопку «Новый элемент» Новый элемент, Poedit и добавляем точку ., что означает искать во всех php-файлах, которые будут находиться в той же директории, что и наш файл перевода.
    Вкладка папки с исходными файлами, Poedit
  6. Вкладка «Ключевые слова исходных файлов». Указываем здесь функции __() и _e(). Затем нажимаем ОК.
    Ключевые слова исходных файлов, Poedit

    Если вы работаете над переводом готовой темы или плагина, я рекомендую в ключевые слова добавить как минимум следующие выражения (на самом деле их больше, но по моим наблюдениям эти чаще всего используются):

    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, это означает, что первый параметр функции — форма единственного числа, второй параметр — форма множественного числа. Подробнее про множественного число читайте далее в этой статье.

  7. Осталось всё это дело сохранить. Файл > Сохранить, там где тип файла указываем все файлы, расширение ставим .pot. Сохраняем прямо в директорию своего плагина или темы.
  8. Заходим в папку, куда вы только что сохранили файл перевода и удаляем из нее ненужный пока что файл с расширением .mo.
  9. В Poedit нажимаем кнопку «Обновить» либо Каталог > Обновить из исходного кода. Та-дам, в окне программы должны появиться все строки, доступные для перевода.
  10. Переводим, сохраняем.

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

Рассмотрим также пошагово:

  1. Создаем в вашей теме или плагине папку languages (на самом деле вы можете назвать ее как угодно).
  2. Открываем наш pot-файл, затем Файл > Сохранить как, выбираем созданную папку, указываем расширение .po. Что касается названия языкового файла, то оно должно быть следующего вида:
    • Для плагинов: {название перевода}-{название языка}, например для русского перевода: 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().

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

Допустим, мы выводим количество товаров в своей теме интернет-магазина. Как сделать так, чтобы в зависимости от количества товаров, выводилась соответствующая форма слова, например: 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).

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

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

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

В вашем плагине или теме уже используется функция _n()? Если нет, тогда вот вам пример кода:

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

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

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

Отлично, всё, что осталось сделать, это сохранить перевод в форматах .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.

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

Подпишитесь, чтобы раз в неделю получать свежие статьи с блога по email.

По теме

Комментарии 34

  • Вадим27 ноября 2014 в 20:11 #

    Добрый день! Подскажите, пожалуйста, что делать, если разработчики моей темы и плагинов не используют plurals. На мои стенания вежливо отвечают, что это потребует больших изменений кода. :)
    Могу ли я, не прибегая к хардкодингу, самостоятельно добавить формы множественного числа? Хуки, плагины...

    • Миша28 ноября 2014 в 07:11 #

      Добрый день!
      Скиньте им ссылку на эту статью и скажите, что вы знаете, что больших изменений кода это не потребует (они просто не хотят заморачиваться) и заплатите им вдвое меньше, если они это не сделают :)

      Не знаю, зависит от того, насколько хорошо вы разбираетесь в PHP.

  • Рустам5 марта 2015 в 19:03 #

    Здравствуйте как понять название версия проекта это надо указывать доменое имя что ли

    • Миша6 марта 2015 в 11:03 #

      Здравствуйте!
      Там можно что угодно указать, это ни на что не повлияет. Например «Сайт на WordPress», версия 1.0.

  • Алексей23 марта 2015 в 00:03 #

    Здравствуйте, помогите, если сможете.
    Года 2 назад удачно перевел шаблон. Использовал в настройках это (причем на тот момент везде рекомендовалось использовать именно так)

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

    В шаблоне было так

    <h3 id="comments-title"><?php
            	printf( _n( 'One comment to %2$s', '%1$s comments to %2$s', get_comments_number(), 'themater' ),
            	number_format_i18n( get_comments_number() ), '<em>' . get_the_title() . '</em>' );
            	?></h3>

    С легкостью перевел так

    msgid "One comment to %2$s"
    msgid_plural "%1$s comments to %2$s"
    msgstr[0] "%1$s комментарий к записи \"%2$s\""
    msgstr[1] "%1$s комментария к записи \"%2$s\""
    msgstr[2] "%1$s комментариев к записи \"%2$s\""
    msgstr[3] "%1$s комментарий к записи \"%2$s\""

    т.е использовалось именно числительное, включая 0, т.е нет комментариев. А сейчас в шаблоне попалось

    <h3 class="comments-title"><?php comments_number(__('No Comments', 'themejunkie'), __('One Comment', 'themejunkie'), __('% Comments', 'themejunkie')); ?></h3>

    PoEdit выставил такие настройки

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

    3 дня уже сижу и не могу заставить работать правильный перевод

    • Миша23 марта 2015 в 07:03 #

      Добрый день!
      Тот код, который вы использовали в самом начале — неверен. В русском языке только 3 формы множественного числа.

      Попробуйте использовать стандартный PoEdit-овский код, а затем проверьте заново все переведённые строки.

  • Дмитрий23 марта 2015 в 20:03 #

    Благодарю.
    Полезненько.

  • Игорь23 апреля 2015 в 08:04 #

    А всем ли плагинам можно прикрутить перевод? Было уже 3 плагина, которые ни в какую не хотят воспринимать перевод. Побаловал всеми известными способами, в том числе описанный вами, но результата никакого.

    • Миша24 апреля 2015 в 08:04 #

      А Poedit видит вообще строки для перевода?

      • Игорь28 апреля 2015 в 22:04 #

        Конечно видит, а как по другому? 2 плагина правда сканировал и создавал файл локализации сам, а 3-й был уже в плагине. А перевод никак не работает.

        • Миша29 апреля 2015 в 09:04 #

          Если PoEdit видит, то возможно где-то в подключении ошибка.

          • Игорь3 мая 2015 в 21:05 #

            Вот это да.... я именно так и думал. Перепробовал кучу способов, по аналогам с разных плагинов и всё в пустую.

  • Дмитрий14 августа 2015 в 06:08 #

    Помогите с переводом плагина UserPro.
    Не получается перевести меню плагина,а именно не получается перевести код,типа:
    $userpro_fields['user_pass'] = array(
    '_builtin' => 1,
    'type' => 'password',
    'label' => 'Password',
    'help' => 'Your password must be 8 characters long at least.'
    );
    перевожу фразы 'Password' и 'Your password must be 8 characters long at least.' но в самом плагине ничего не меняется.Что может быть!?Аналогичных словосочетаний в папке с плагином больше нет!

    • Дмитрий11 сентября 2015 в 15:09 #

      Привет!Для начала,удалите данный плагин,потом необходимо зайти в phpmyadmin и удалить все параметры UserPro.Затем,просто скачайте данный плагин с сайта

      http://obzor-tyt.ru/userpro-2-37-ru-russificirovannyj-premium-plagin-wordpress-profilej-polzovatelya/

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

  • Роман22 декабря 2015 в 21:12 #

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

    • Миша23 декабря 2015 в 02:12 #

      Добрый день!
      Вы мне абсолютно никакой информации не дали, чтобы я смог вам помочь.

  • Алексей27 января 2016 в 11:01 #

    Миша, помогите сориентироваться. Вот сколько не пытался создать pot файл - не получается. Вроде бы всё делаю по инструкции, но всё время получаю сообщение, что poedit не нашёл никаких файлов в просканированных папках.
    Верно ли я понимаю, что в указанной мной папке программа должна сканировать файлы php на наличие в них текста для перевода, и при нахождении таковых, вытаскивать их в отдельный файл? И если моё понимание верно, то, что может быть причиной такой ошибки?
    Pot файл пытаюсь сделать для форума simple-press. В ключевые слова исходных файлов, прописываю среди прочего и __sp() (именно такой вид имеют в simplepress фрагменты текста)

  • Алексей29 января 2016 в 20:01 #

    Есть папка в папке wp-content - sp-resources. Она создаётся после установки плагина форума simplepress. В ней содержатся файлы форума. Среди прочего, например и папка \forum-themes\default\templates, где содержатся файлы, отвечающие за внешний вид форума и текстовые элементы. В этой папке содержатся php файлы. Я скачиваю папку sp-resources со всем содержимым на рабочий стол, после чего запускаю poedit, выполняю описанные Вами выше действия и пытаюсь сохранить pot файл в папке \sp-resources\forum-themes\default\templates\..
    Далее программа думает несколько секунд, а потом выдаёт сообщения: Poedit не нашёл никаких файлов в просканированных папках. Элементы каталога, возможно, неверны.

  • Алексей30 января 2016 в 09:01 #

    Ну, если я что-нибудь в чём-нибудь понимаю, то да. Есть. Вот пример строки из одного файла в данной папке:
    sp_ListTopicName('', __sp('Browse the thread %NAME%'));

    Это __sp('Browse the thread %NAME% ведь то, что нужно?

    • Миша31 января 2016 в 10:01 #

      Похоже, что __sp() это функция уже вашего плагина. А вы указали её в настройках PoEdit ?

  • Алексей2 февраля 2016 в 12:02 #

    Да. Указал. Вообще проблему с переводом данного плагина уже решил, добыв .po файл от последней версии и переведя его. Но хотелось бы всё таки понять источник сложностей в данном вопросе. А то в своё время пришлось вручную искать недостающие строки в исходных файлах и добавлять в .po файл. Удовольствие то ещё.

  • Евгений3 февраля 2016 в 08:02 #

    Приветствую.
    Отличная статья. Узнал для себя массу интересного, хотя данной программой Poedit пользовался и раньше для переводов шаблонов wordpress. Правда, у меня на днях возникла одна проблема. Есть шаблон, разработчик предусмотрел, что понадобится его локализация и через админку можно ее включить. Внешняя сторона шаблона переводится за секунды. С одной стороны, чего еще желать. Но! Использую я или не использую Poedit, сама админская часть не желает переводится - вот скриншот: админка.jpg

    Разумеется, методом научного тыка я раскопал где именно прячутся эти файлы, но, переводить руками без Poedit довольно проблематично и бессмысленно, так как после обновления WP, все эти переводы слетят к чертям. Так вот, как можно было бы решить данную проблему? Что скажите?

    • Миша3 февраля 2016 в 09:02 #

      Привет!
      В плагинах очень часто бывает, что для админки отдельное значение textdomain.

      • Евгений3 февраля 2016 в 12:02 #

        Михаил, а можно несколько по подробнее? Если не сложно, конечно.

        • Миша5 февраля 2016 в 11:02 #

          А можете прислать кусочек кода из такого непереведённого файла? Чтобы была строка и функция, в которой она находится.

          • Евгений5 февраля 2016 в 12:02 #

            Приветствую, Михаил.
            Ну вот, например, после того как исправил в .php Modul 1на Модуль 1 - на сайте он разумеется поменялся. Но до поры до времени, после обновления WP - слетит же все..

             /**
                     * modules list
                     */
                    td_api_module::add('td_module_1',
                        array(
                            'file' => td_global::$get_template_directory . '/includes/modules/td_module_1.php',
                            'text' => 'Module 1',
                            'img' => td_global::$get_template_directory_uri . '/images/panel/modules/td_module_1.png',
                            'used_on_blocks' => array('td_block_3'),
                            'excerpt_title' => 12,
                            'excerpt_content' => '',
                            'enabled_on_more_articles_box' => true,
                            'enabled_on_loops' => true,
                            'uses_columns' => true,
                            'category_label' => true,
                            'class' => 'td_module_wrap td-animation-stack'
  • Вася5 февраля 2016 в 13:02 #

    Миш, а не подскажешь, как безболезненно заменить перевод ядра, что бы он не потерялся при обновлении. Например, фразу:

    "Подсказка: Пароль должен состоять как минимум из двенадцати символов. "

    (На самом деле дефолтная длинна не ограничивается вообще и к тому же может меняться плагинами, но вот фраза вылазит).

    • Миша8 февраля 2016 в 09:02 #

      Перевод ядра. Слушай, я с этим не сталкивался, но думаю что как-то должно быть можно. Ну или на худой конец через jQuery :)

Оставить комментарий / вопрос

phpjsHTMLCSSSQLПросто код
  Для того, чтобы оставить комментарий, пожалуйста, зарегистрируйтесь или авторизуйтесь на сайте.
Получайте новости блога по email или следите за мной в социальных сетях.
  • Миша: Да, точно)

  • Владимир: и на третьей строке не хватает скобки ) закрывающей if :)

  • Миша: Добрый вечер! Рекомендую получить ID пользователя через функцию get_current_user_id().

  • Дмитрий: Миша, подскажите пожалуйста, я использую такой редирект, но он не срабатывает: add_action( 'template_redirect', funct...

  • Миша: Ну как не определена - это аргумент функции. Или я просто вас не до конца понимаю.