Переводы (локализация)

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

Что переводить?

Прежде чем переходить к переводу, давайте определимся что нам нужно перевести, потому что это влияет на то, как нужно переводить.

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

Для такого перевода нужно использовать сайт translate.wordpress.org. Что нужно сделать:

1. Авторизоваться.
2. Выбрать нужный язык перевода
3. Найти плагин/тему которую нужно перевести.
4. И прям на сайте переводить.

5. После того, как ваш перевод будет проверен, в админке вашего сайта на WordPress вы уведите обновления перевода для плагина/темы.

   Заметка: обновление появится не раньше, чем 95% всего перевода будет готово. Чтобы ускорить проверку, можете написать на форум в раздел «переводы» или в русскоязычный slack на канал #translations.

6. Обновляем. Перевод сделан!

Заметка: Не все плагины из каталога поддерживают перевод через translate.wordpress.org. В таких случаях переводить нужно как обычно (читайте следующий пункт).

Перевод темы/плагина НЕ из каталога WordPress

В этом случае, нужно:

1. Открыть папку плагина и найти в ней файлы перевода. Это файл .po, .pot, .mo. Обычно они лежать в папках languages или lang.
2. Затем переходите к «Этап 2» из этой статьи. Т.е. вам нужно будет создать .mo файл перевода. Для создания такого файла, используйте программу Poedit и .pot (если есть в плагине) или .po файл (закидывайте этот файл в Poedit и там создаете перевод на свой язык, сохраняете его с правильным названием). Или для создания .mo файла можно использовать плагин «Loco Translate», он даже удобнее (подробности в этой статье не описаны).

Перевод своей темы/плагина

Как это делается и работает описано ниже в «Этап 1» и «Этап 2».

Если вы планируете размещать ваш плагин/тему в каталоге WordPress. То настоятельно рекомендуется делать перевод через translate.wordpress.org. Подробнее об этом читайте в руководстве (англ.) (подробности в этой статье не описаны).

Как работает перевод в WordPress (теория)

Начать надо с самого главного - это файлы перевода. Их бывает три: .mo .po .pot. PHP работает только с .mo файлом, .po и .pot - для людей и программ перевода.

• .pot файл (Portable Object Template) — содержит оригинальные строки перевода (без перевода). Это шаблон перевода. POT файл является основой для создания .po файла (для создания перевода на любой язык). POT файл не является обязательным файлом, перевод можно делать и без него - это просто шаблон. Как создать .pot файл читайте ниже.

• .po файл (Portable Object) — содержит оригинальные строки перевода и сам перевод этих строк. Его можно изменять в любом текстовом редакторе или в программе (например Poedit, с ней мы и будет работать ниже). Из .po файла автоматически создается .mo файл.

• .mo файл (Machine Object) — скомпилированный вариант PO файла. Cодержит бинарные данные, которые парсит WordPress и создает из них данные для перевода отдельных строк. Используется для перевода тем/плагинов и импортируется в GNU gettext.

В WordPress для перевода используется только файл .mo. Во время генерации страницы этот файл подключается — из него создается PHP объект с переводами строк и помещается в память. Далее, при использовании функций перевода в коде, из этого объекта берется перевод запрашиваемой строки.

Вот так просто это работает.

Таким образом, чтобы переводить строки в теме/плагине нам нужно:

1. Создать файл .mo и разместить его в папку темы/плагина. Или в глобальную папку переводов.

2. Подключить этот файл в теме/плагине с помощью одной из функций: load_theme_textdomain(), load_plugin_textdomain(). (Если размещается в глобальной папке подключать необязательно, WP сам это сделает).

3. Использовать специальные функции перевода: __(), _x(), _n() и другие.

Важно понимать, что при подключении .mo файла ему задается идентификатор (параметр $domain) и такой идентификатор (домен) указывается для функций перевода строк. Домен связывает файл .mo с функциями перевода. Т.е. при переводе, в функции мы указываем из какого MO файла нужно получить перевод указанной строки. Пример:

// подключаем MO файл перевода и указываем ему ID — mydomain:
load_theme_textdomain( 'mydomain', get_template_directory() . '/languages' );

// переводим — опять указываем ID — mydomain:
_e( 'Comment:', 'mydomain' );

Этап 1: Создадим свой плагин и переведем его

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

1. В папке плагинов WordPress создадим папку my-translation-demo: /plugins/my-translation-demo.
2. В этой папке создадим папку lang: /my-translation-demo/lang.
3. Создадим файл my-translation-demo.php: /my-translation-demo/my-translation-demo.php.
4. Добавим следующий код в созданный php файл:

<?php

/**
 * Plugin Name: Demo WordPress translation
 * Description: Test plugin for learning how to create translations in WordPress
 * Author:      Kama
 * Version:     0.1
 * Text Domain: myl10n
 * Domain Path: /lang
 */

// строки для перевода заголовков плагина, чтобы они попали в .po файл.
__( 'Demo WordPress translation', 'myl10n' );
__( 'Test plugin for learning how to create translations in WordPress', 'myl10n' );

// подключение файла перевода
// здесь .mo файл должен лежать в папке /lang, которая находится в папке текущего файла
// файл должен назваиться "$domain-локаль": myl10n-ru_RU.mo
add_action( 'plugins_loaded', function(){
	load_plugin_textdomain( 'myl10n', false, dirname( plugin_basename(__FILE__) ) . '/lang' );
} );

// страница админки
add_action( 'admin_menu', function(){

	add_options_page( __('Demo translation','myl10n'), __('Demo translation','myl10n'), 'manage_options', 'myl10n_plugin', function(){

		_nx_noop( '%s noop star','%s noop stars','Контекст _nx_noop','myl10n' );
		_n_noop( '%s noop star','%s noop stars','myl10n' );

		?>
		<div class="wrap">
			<h2><?php echo get_admin_page_title() ?></h2>
		</div>

		<h3><?= __( 'Different variants of translation in WordPress.','myl10n') ?></h3>
		<p class="description"><?= __( 'WordPress translation functions.','myl10n') ?></p>

		<p>_e() — <?php _e( 'Some translation text.','myl10n' ); ?></p>

		<p>_ex() — <?php _ex( 'Some translation text.','Фраза контекста _ex','myl10n' ); ?></p>

		<p>_x() — <?php echo _x( 'Some translation text.','Контенкст echo _x','myl10n' ); ?></p>

		<p>_n(1) — <?php printf( _n( '%s star','%s stars', 1, 'myl10n' ), 1 ); ?></p>
		<p>_n(3) — <?php printf( _n( '%s star','%s stars', 3, 'myl10n' ), 3 ); ?></p>
		<p>_n(10) — <?php printf( _n( '%s star','%s stars', 10, 'myl10n' ), 10 ); ?></p>

		<p>_nx(1) — <?php printf( _nx( '%s star','%s stars', 1, 'Фраза контекста для множественного числа _nx','myl10n' ), 1 ); ?></p>
		<p>_nx(3) — <?php printf( _nx( '%s star','%s stars', 3, 'Фраза контекста для множественного числа _nx','myl10n' ), 3 ); ?></p>
		<p>_nx(10) — <?php printf( _nx( '%s star','%s stars', 10, 'Фраза контекста для множественного числа _nx','myl10n' ), 10 ); ?></p>

		<p>esc_attr__() — <?php echo esc_attr__('string 1','myl10n') ?></p>
		<p>esc_attr_e() — <?php esc_attr_e('string 2','myl10n') ?></p>
		<p>esc_html__() — <?php echo esc_html__('string 3','myl10n') ?></p>
		<p>esc_html_e() — <?php esc_html_e('string 4','myl10n') ?></p>

		<?php

	} );

} );

Плагин готов!

Зайдем в админку, активируем плагин, перейдем на страницу плагина.

В плагине используются все функции перевода, которые есть в WordPress. А также подключается еще не существующий .mo файл перевода myl10n-ru_RU.mo. После создания .mo файла плагин будет переведен (его мы создадим ниже).

 * Text Domain: myl10n
 * Domain Path: /lang

// строки для перевода заголовков плагина, чтобы они попали в .po файл.
__( 'Demo WordPress translation', 'myl10n' );
__( 'Test plugin for learning how to create translations in WordPress', 'myl10n' );

Этап 2: Перевод. Создание PO MO файлов (под нужную локаль)

Чтобы создать MO файл, нам нужно иметь готовый PO файл, поэтому вся задача сводиться к созданию PO файла.

Вариантов создать PO файл несколько. Мы рассмотрим работу с программой «Poedit».

Создать PO файл можно через Poedit, но мы создадим его вручную - так быстрее и проще. Poedit будет нужен для самого перевода всех строк.

1) Создайте файл PO

Для этого просто создайте текстовый файл с расширением .po в папке lang нашего плагина. Файл должен иметь название ДОМЕН_ПЕРЕВОДА-ЛОКАЛЬ.po, у нас это myl10n-ru_RU.po. (Кодировка файла должна быть UTF-8).

2) Настройте перевод

Откройте файл и скопируем в него следующий текст:

msgid ""
msgstr ""
"Project-Id-Version: my-plugin-name\n"
"Last-Translator: Myname <myemail@gmail.com>\n"
"Language-Team: My Super Team\n"
"Language: ru\n"
"Content-Type: text/plain; charset=UTF-8\n"
"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"
"X-Poedit-SourceCharset: UTF-8\n"
"X-Poedit-KeywordsList: __;_e;_x:1,2c;_ex:1,2c;_n:1,2;_nx:1,2,4c;_n_noop:1,2;_nx_noop:1,2,3c;esc_attr__;esc_attr_e;esc_html__;esc_html_e\n"
"X-Poedit-Basepath: ..\n"
"X-Poedit-SearchPath-0: .\n"
"X-Poedit-SearchPathExcluded-0: node_modules\n"
#"X-Poedit-SearchPathExcluded-0: js\n"
#"X-Poedit-SearchPathExcluded-1: css\n"

Пояснения по параметрам:

• Project-Id-Version — название и версия проекта.
• Last-Translator — имя и email переводчика.
• Language-Team — название команды переводчиков.
• Language — язык на который переводит файл.
• Plural-Forms — форма множественного числа.
• X-Poedit-KeywordsList — названия и параметры функций, строки из которых будут взяты для перевода. (тут указаны все возможные функции WordPress).
• X-Poedit-Basepath — основная папка. Файлы в ней и в её подпапках будут просматриваться на наличие строк перевода. .. две точки тут означает, что основная папка находится на уровень выше папки текущего файла. Так как .po файл у нас лежит в /lang папке, то папка на уровень выше - это корневая папка плагина.
• X-Poedit-SearchPath-0 — папки (относительно основной), в которых нужно просматривать файлы. . точка тут означает, что нужно просматривать все файлы.
• X-Poedit-SearchPathExcluded-0 — тут можно указать папку (относительно основной), где не нужно просматривать файлы.

Все эти параметры можно изменить из программы Poedit, в любой момент. Для этого зайдите в Каталог > Свойства в Poedit.

3) Загрузите файл в Poedit

Для начала нужно скачать Poedit и установить его. Бесплатная версия позволяет делать все что нам нужно.

Откройте наш, пока еще пустой, файл .po в установленной программе Poedit.

4) Переводим

Выберите «Извлечь из исходного кода».

В появившемся окне меняем настройки перевода (не обязательно) и жмем OK.

Ждем пока программа просканирует код и соберет из него все строки перевода.

Переводим, жмем «Сохранить»

5) Готово!

Все, MO файл готов! При нажатии на «Сохранить» он автоматически создастся рядом с .po файлом (с таким же называнием но с расширением .mo).

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

Обновление перевода (при изменении кода)

Тут все предельно просто:

1. Открываем Poedit.
2. Закидываем в него любой PO файл из проекта и жмем «Обновить из кода» (кнопка на панели).
3. Переводим новые строки и жмем «Сохранить» (кнопка на панели).
4. Перевод обновлен! Можно закрыть Poedit.

Создание POT файла

.pot файл — это шаблон перевода. Это копия .po файла, только там не переведена ни одна строка. Т.е. все строки перевода получены из файлов проекта, но еще ничего не переведено.

Из вышесказанного следует, - чтобы создать POT файл нужно пройти всю процедуру по созданию .po файла, но в конце ничего не переводить, а зайти в "Файл > Сохранить как" и сохранить файл с расширением .pot.

Создание .pot из .po

Если в проекте уже есть .po файл, то .pot можно создать из него. Скопируйте .po файл и поменяйте ему расширение на .pot.

Это грубый метод, но такой файл с переведенными строками, тоже можно использовать как шаблон для создания перевода на любой язык (по крайней мере так работает Poedit).

Для надежности, созданный .pot можно обновить через Poedit. Откройте его в Poedit, нажмите «Обновить из кода» и сохраните.

Зачем нужен POT файл?

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

Например, если PO и MO файлы перевода размещаются в глобальную папку переводов, то мы не можем закинуть PO файл в программу и нажать «Обновить из кода», потому что в PO файле путь до файлов плагина будет неправильный (или его там вообще не будет) и строки перевода обновиться не смогут. В этом случае и нужен POT файл, из которого можно создать перевод для любого языка.

POT файл всегда должен лежать в папке плагина. ВАЖНО: при изменении кода в нём всегда нужно обновлять строки перевода, так мы всегда будем иметь все актуальные строки для перевода в шаблоне для переводов.

Функций перевода

Подключение .mo файла перевода

Как подключить MO файл в плагине, уже есть в коде плагина выше. А тут я сделаю акцент на функциях WordPress для подключения этого файла. Функции:

load_plugin_textdomain( $domain, false, $plugin_rel_path )

Подключает MO файл из плагина. Обертка для load_textdomain(). Сначала ищет MO файл в общей папке переводов плагинов: /wp-content/language/plugins. Файл должен называться ДОМЕН_ПЕРЕВОДА-ЛОКАЛЬ.mo.

load_muplugin_textdomain( $domain, $plugin_rel_path )

Подключает MO файл из MU плагина. Обертка для load_textdomain(). Сначала ищет MO файл в общей папке переводов плагинов: /wp-content/language/plugins. Файл должен называться ДОМЕН_ПЕРЕВОДА-ЛОКАЛЬ.mo.

load_theme_textdomain( $domain, $path )

Подключает MO файл из темы. Обертка для load_textdomain(). Сначала ищет MO файл в общей папке переводов тем: /wp-content/language/themes. Файл должен называться ЛОКАЛЬ.mo (когда файл внутри темы) и ПАПКА_ТЕМЫ-ЛОКАЛ.mo (когда файл в общей папке).

load_child_theme_textdomain( $domain, $path )

Подключает MO файл из дочерней темы. Обертка для load_theme_textdomain().

load_textdomain( $domain, $mofile )

Подключает MO файл из любого места (нужно указать полный путь до MO файла, вместе с названием файла).

Рассмотрим примеры подключения MO файлов.

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

// файл перевода плагина.
// файл должен называться: ДОМЕН-ЛОКАЛЬ.mo, например: myl10n-ru_RU.mo
add_action( 'plugins_loaded', function(){
	load_plugin_textdomain( 'my-plugin', false, dirname( plugin_basename( __FILE__ ) ) . '/languages' ) );
} );

// файл перевода MU плагина.
// файл должен называться: ДОМЕН-ЛОКАЛЬ.mo, например: myl10n-ru_RU.mo
load_muplugin_textdomain( 'my-plugin', dirname( plugin_basename( __FILE__ ) ) . '/languages' ) );

// файл перевода темы.
// файл должен иметь название текущей локали, например: ru_RU.mo
add_action( 'after_setup_theme', function(){
	load_theme_textdomain( 'my_theme', get_template_directory() . '/languages' );
});

// любой файл перевода
// Подключаем файл .mo (название файла: ru_RU.mo или другое, зависит от локали)
add_action( 'plugins_loaded', function(){
	$mo_file_path = dirname( __FILE__ ) . '/lang/'. get_locale() . '.mo';
	load_textdomain( 'mytranslate', $mo_file_path );
}

Не обязательно подключать функции на хуки, но в примерах я все же сделал как рекомендуется.

Функции локализации

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

__( $text, $domain )

Переводит указанный текст и возвращает его для обработки.

_e( $text, $domain )

Переводит указанный текст и выводит его на экран.

_x( $text, $context, $domain )

Переводит указанный текст с учетом указанного контекста и возвращает его для обработки.

_ex( $text, $context, $domain )

Переводит указанный текст с учетом указанного контекста и выводит его на экран.

_n( $single, $plural, $number, $domain )

Получает строку перевода единственного или множественного числа, ту которая соответствует указанному числу (1 комментарий, 2 комментария).

_nx( $single, $plural, $number, $context, $domain )

Получает строку перевода единственного или множественного числа с учетом указанного контекста.

_n_noop( $singular, $plural, $domain )

Функция пустышка. Аналог _n(). Используется когда нужно определить строки перевода для множественных числе, но использовать их где-то позднее в коде. Результат который возвразает функцию нужно обрабатывать функцией translate_nooped_plural(). Результат этой функции, например, удобно использовать в параметрах, когда мы заранее не знаем какое будет число и нужно сделать перевод позднее.

_nx_noop( $singular, $plural, $context, $domain )

Тоже что _n_noop(), только с контекстом.

esc_attr__( $text, $domain )

Перевод для значений атрибутов HTML тегов. Сокращение для esc_attr( __() ).

esc_attr_e( $text, $domain )

Тоже что esc_attr__(), только сразу выводит результат на экран.

esc_html__( $text, $domain )

Перевод текста в котором могут быть HTML теги. Сокращение для esc_html( __() ).

esc_html_e( $text, $domain )

Тоже что esc_html__(), только сразу выводит результат на экран.

Частые ошибки при использовании функций локализации

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

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

// Да
_e( 'Hello World!', 'mydomain');

// Нет
_e( $string, 'mydomain' );
_e( 'Hello World!', $domain );
_e( 'Hello World!', DOMAIN );

#2 Не используйте HTML в строках перевода (если это возможно)

Например, если указать <div> в строке перевода и переводчик ошибется, то HTML разметка может «сломаться». Или если указать ссылку <a>, переводчик на её место может поставить свою, или просто неправильно её написать. Или любой HTML тег можно не закрыть и мы поймаем очень неприятный баг верстки.

В 90% случаев HTML теги можно и нужно выносить за пределы строки перевода, рассмотрим несколько примеров:

// Да
echo '<h1>'. __( 'Hello World!', 'mydomain' ) .'</h1>';

// Нет
_e( '<h1>Hello World!</h1>', 'mydomain' );

// Да
echo str_replace( '<a>', '<a href="http://example.com/portfolio">', __( 'See <a>my portfolio</a>', 'mydomain' ) );

// Нет
_e( 'See <a href="http://example.com/portfolio">my portfolio</a>', 'mydomain' );

#3 Не делите фразу на отдельные слова

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

// Да
echo sprintf( __( 'I am %d today', 'mydomain' ), $years );

// Нет
echo __( 'I am ', 'mydomain' ) . $years . __( ' today', 'mydomain' );

#4 Не оставляйте пробелы в конце/начале строки

При переводе пробелы на концах часто НЕ заметны и их можно пропустить, в итоге такой перевод не будет работать. Поэтому, лучше писать нужные пробелы в коде.

// Да
_e( 'Book name:', 'mydomain' ) . ' ' . $book_name;
// Да
_e( 'Book name:', 'mydomain' ) ." $book_name";

// Нет
_e( 'Book name: ', 'mydomain' ) . $book_name;

Перевод множественного числа

В плагине выше, уже есть пример как переводить строки где используются числа. Тут я сделаю на этом акцент.

Для перевода строк с числами, когда нужно получить разные переводы в зависимости от числа, в WordPress используется функция _n( $single, $plural, $number, $domain ) или _nx() (с контекстом). Она вернет разный вариант строки в зависимости от указанного числа. Например:

printf( _n( '%s star','%s stars', 1, 'myl10n' ), 1 );   //> 1 звезда

printf( _n( '%s star','%s stars', 3, 'myl10n' ), 3 );   //> 3 звезды

printf( _n( '%s star','%s stars', 10, 'myl10n' ), 10 ); //> 10 звезд

Однако, чтобы все это правильно работало нужно:

1. В настройках .po файла правильно указать форму множественного числа. Мы её указали в параметре Plural-Forms:

   "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"

   

   Смотрите также: Варианты Plural-Forms для разных языков.

2. В настройках .po файла правильно указать шаблоны поиска функций:

   • _n:1,2 - для функции _n(). 1 и 2 - это параметры функции для множ. и единс. числа.
   • _nx:1,2,4c - для функции _nx(). Тут 4с - значит что 4 параметр функции это строка контекста.

   

3. При переводе правильно перевести строки. Для русского языка нужно указать три варианта для перевода одной строки.

   

В заключение

Размещение файла перевода в глобальной папке

В WordPress есть общая папка для файлов перевода: /wp-content/languages. В ней лежат файлы перевода самого WordPress, а также могут лежать файлы переводов тем и плагинов (это работает в WordPress по умолчанию).

Все функции подключения MO файлов (кроме load_textdomain()), сначала проверяют наличие файла перевода в общей папке, и только потом ищут его в папке плагина или темы. Это чем-то похоже на иерархию файлов шаблона, только тут иерархия файлов перевода...

Общая папка переводов для:

• плагинов /wp-content/languages/plugins/ДОМЕН_ПЕРЕВОДА-ЛОКАЛЬ.mo.
• тем /wp-content/languages/themes/ДОМЕН_ПЕРЕВОДА-ЛОКАЛЬ.mo.

В такие общие папки, например, загружается и обновляется перевод плагина, который находится в каталоге плагинов WordPress. Вы наверное видели переведенные плагины, в которых нет файлов перевода (это как раз эта тема). Как я писал в начале статьи плагины из каталога можно переводить через сайт translate.wordpress.org.

Термины связанные с переводом

Некоторые термины, которые нужно знать. Это самые основные (сокращением этих терминов в WordPress названы некоторые функции и хуки):

• Интернационализация (internationalization - i18n) — процесс изменения программного обеспечения, чтобы оно не было привязано к одному языку. Т.е. это весь комплекс функций и классов ядра WordPress позволяющий переводить сайт на разные языки.

• Локализация (localization - l10n) — процесс добавления соответствующих ресурсов в ваше программное обеспечение для поддержки определенного языка/локали. Т.е. это сам процесс перевода на разные языки.

• Локаль (locale) — это связка языка и диалекта в регионе. Обычно под локалью понимается просто язык, допустим, русский. Но английский например может быть English (U.S.) или English (UK) - язык один, локали разные... Локаль определяется как КОД_ЯЗЫКА_КОД_СТРАНЫ (ru_RU) или код языка в стандарте ISO 639-3 (rus).

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

Loco Translate - отличный плагин для создания перевода (.mo файла). Этот плагин полностью заменяет программу Poedit. Он позволяет создавать переводы для чего угодно тем, плагинов или отдельных MU плагинов. Плагин можно активировать, перевести что нужно и деактивировать чтобы не «мешался».