---
description: 'Как работать с переводом PO в проекте документации FreeBSD'
next: books/fdp-primer/weblate
params:
  path: /books/fdp-primer/po-translations/
prev: books/fdp-primer/translations
showBookMenu: 'true'
tags: ["po", "translations", "tutorial", "quick start"]
title: 'Глава 9. Переводы PO'
weight: 9
---

[[po-translations]]
= Переводы PO
:doctype: book
:toc: macro
:toclevels: 1
:icons: font
:sectnums:
:sectnumlevels: 6
:sectnumoffset: 9
:partnums:
:source-highlighter: rouge
:experimental:
:images-path: books/fdp-primer/

ifdef::env-beastie[]
ifdef::backend-html5[]
:imagesdir: ../../../../images/{images-path}
endif::[]
ifndef::book[]
include::shared/authors.adoc[]
include::shared/mirrors.adoc[]
include::shared/releases.adoc[]
include::shared/attributes/attributes-{{% lang %}}.adoc[]
include::shared/{{% lang %}}/teams.adoc[]
include::shared/{{% lang %}}/mailing-lists.adoc[]
include::shared/{{% lang %}}/urls.adoc[]
toc::[]
endif::[]
ifdef::backend-pdf,backend-epub3[]
include::../../../../../shared/asciidoctor.adoc[]
endif::[]
endif::[]

ifndef::env-beastie[]
toc::[]
include::../../../../../shared/asciidoctor.adoc[]
endif::[]

[[po-translations-introduction]]
== Введение

Система http://www.gnu.org/software/gettext/[GNU gettext] предоставляет переводчикам удобный способ создания и поддержки переводов документов. Переводимые строки извлекаются из исходного документа в файл PO (Portable Object). Переводы строк добавляются с помощью отдельного редактора. Эти строки могут использоваться напрямую или собираться в полную переведённую версию исходного документа.

[[po-translations-quick-start]]
== Быстрый старт

Предполагается, что процедура, описанная в crossref:overview[overview-quick-start,Быстрый старт], уже выполнена. Опция `TRANSLATOR` необходима и уже включена по умолчанию в порте package:textproc/docproj[].

Этот пример демонстрирует создание испанского перевода краткой статьи extref:{leap-seconds}[Високосные секунды].

[[po-translations-quick-start-install-po-editor]]

[.procedure]
====
.Процедура: Установка PO-редактора
. Редактор PO необходим для редактирования файлов переводов. В этом примере используется package:editors/poedit[].
+
[source, shell]
....
# pkg install poedit
....
====

[[po-translations-quick-start-initial-setup]]
[.procedure]
====
.Процедура: Начальная настройка

Когда создаётся новый перевод, структура каталогов должна быть создана или скопирована из оригинальной английской версии:

. Создайте каталог для нового перевода. Исходный текст статьи на английском находится в [.filename]#~/doc/documentation/content/en/articles/leap-seconds/#. Испанский перевод будет расположен в [.filename]#~/doc/documentation/content/es/articles/leap-seconds/#. Путь идентичен, за исключением названия языкового каталога. Исходный текст статьи на английском находится в [.filename]#~/doc/en/articles/leap-seconds/#. Испанский перевод будет расположен в [.filename]#~/doc/es/articles/leap-seconds/#. Путь идентичен, за исключением названия языкового каталога.
+
[source, shell]
....
% mkdir ~/doc/documentation/content/es/articles/leap-seconds
....

. Скопируйте [.filename]#_index.po# из исходного документа в каталог перевода:
+
[source, shell]
....
% cp ~/doc/documentation/content/en/articles/leap-seconds/_index.po \
  ~/doc/documentation/content/es/articles/leap-seconds/
....

Предположим, что документ или язык также переводится через Weblate. В таком случае рекомендуется взять файл `.po` оттуда и загрузить переведённый документ обратно в платформу, чтобы централизовать усилия по переводу через Weblate и избежать повторной работы.

См. как загрузить файлы `.po` в главе crossref:weblate[weblate-translating-offline,Перевод офлайн в Weblate].
====

[[po-translations-quick-start-translation]]
[.procedure]
====
.Процедура: Перевод

Используйте PO-редактор для ввода переводов в PO-файл. Доступно несколько различных редакторов. Здесь показан [.filename]#poedit# из пакета:editors/poedit[].

[source, shell]
....
% poedit documentation/content/es/articles/leap-seconds/_index.po
....
====

[[po-translations-quick-generating-a-translated-document]]
[.procedure]
====
.Процедура: Создание переведенного документа
. Сгенерируйте переведенный документ:
+
[source, shell]
....
% cd ~/doc
% ./tools/translate.sh documentation es articles/leap-seconds
....
+
Имя сгенерированного документа соответствует имени оригинала на английском языке, обычно `[.filename]#_index.adoc#`.
+
. Проверьте сгенерированный файл, преобразовав его в HTML и просмотрев в веб-браузере:
+
[source, shell]
....
% cd ~/doc/documentation
% make
....
====

[[po-translations-creating]]
== Создание новых переводов

Первым шагом в создании нового переведённого документа является поиск или создание каталога для его размещения. FreeBSD размещает переведённые документы в подкаталоге с названием, соответствующим языку и региону, в формате [.filename]#lang#. Здесь _lang_ — это двухбуквенный код в нижнем регистре.

[[po-translations-language-names]]
.Названия языков
[cols="1,1,1", frame="none", options="header"]
|===
| Язык
| Регион
| Имя каталога с переводами

|Английский
|Соединённые Штаты
|[.filename]#en#

|Бенгальский
|Бангладеш
|[.filename]#bn-bd#

|Датский
|Дания
|[.filename]#da#

|Немецкий
|Германия
|[.filename]#de#

|Греческий
|Греция
|[.filename]#el#

|Испанский
|Испания
|[.filename]#es#

|Французский
|Франция
|[.filename]#fr#

|Венгерский
|Венгрия
|[.filename]#hu#

|Итальянский
|Италия
|[.filename]#it#

|Японский
|Япония
|[.filename]#ja#

|Корейский
|Корея
|[.filename]#ko#

|Монгольский
|Монголия
|[.filename]#mn#

|Голландский
|Нидерланды
|[.filename]#nl#

|Польский
|Польша
|[.filename]#pl#

|Португальский
|Бразилия
|[.filename]#pt-br#

|Русский
|Россия
|[.filename]#ru#

|Турецкий
|Турция
|[.filename]#tr#

|Китайский
|Китай
|[.filename]#zh-cn#

|Китайский
|Тайвань
|[.filename]#zh-tw#
|===

Переводы находятся в подкаталогах основного каталога документации, который в данном случае предполагается как [.filename]#~/doc/documentation/#, как показано в crossref:overview[overview-quick-start, Быстрый старт]. Например, немецкие переводы расположены в [.filename]#~/doc/documentation/content/de/#, а французские — в [.filename]#~/doc/documentation/content/fr/#.

Каждый языковой каталог содержит отдельные подкаталоги с названиями по типу документов, обычно [.filename]#articles/# и [.filename]#books/#.

Объединение этих имён каталогов даёт полный путь к статье или книге. Например, французский перевод статьи NanoBSD находится в [.filename]#~/doc/documentation/content/fr/articles/nanobsd/#, а монгольский перевод Руководства — в [.filename]#~/doc/documentation/content/mn/books/handbook/#.

При переводе документа на новый язык необходимо создать новый каталог языка. Если каталог языка уже существует, достаточно создать подкаталог в каталоге [.filename]#articles/# или [.filename]#books/#.

[[po-translations-creating-example]]
.Создание испанского перевода Руководства портировщика
[example]
====
Создайте новый перевод на испанский язык extref:{porters-handbook}[Руководства портировщика]. Оригинал находится в книге [.filename]#~/doc/documentation/content/en/books/porters-handbook/#.

[.procedure]
======

. Каталог для книг на испанском языке [.filename]#~/doc/documentation/content/es/books/# уже существует, поэтому требуется только создать подкаталог для Руководства портировщика:
+
[source, shell]
....
% cd ~/doc/documentation/content/es/books
% mkdir porters-handbook
....

. Скопируйте содержимое из переводимой книги:
+
[source, shell]
....
% cd porters-handbook
% cp -R ~/doc/documentation/content/en/books/porters-handbook/* .
....
+
Теперь структура документа готова для начала перевода с помощью команды `po4a`.
======
====

[[po-translations-translating]]
== Перевод

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

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

Редактор PO используется для редактирования файла. В этих примерах показан package:editors/poedit[], так как он прост и имеет минимальные требования. Другие редакторы PO предоставляют функции, облегчающие процесс перевода. В Коллекции портов доступно несколько таких редакторов, включая package:devel/gtranslator[].

Важно сохранить PO-файл. Он содержит всю работу, проделанную переводчиками.

[IMPORTANT]
====
Перевод документов онлайн оказывается наиболее простым способом перевода документации в FreeBSD, так как позволяет нескольким пользователям совместно работать над одним файлом, эффективно распределяя нагрузку. Для получения дополнительной информации обратитесь к следующей главе: crossref:weblate[weblate-introduction,Переводы в Weblate].
====

[[po-translations-tips]]
== Советы переводчикам

[[po-translations-tips-xmltags]]
=== Сохранение AsciiDoc макросов

Сохраните макросы AsciiDoc, которые указаны на английском языке.

.Сохранение AsciiDoc макросов
[example]
====
Оригинал на английском:

[.programlisting]
....
msgid ""
"This example shows the creation of a Spanish translation of the short "
"extref:{leap-seconds}[Leap Seconds] article."
....

Испанский перевод:

[.programlisting]
....
msgid ""
"Este ejemplo muestra la creación de un artículo con poco contenido como el artículo "
"extref:{leap-seconds}[Leap Seconds]."
....

====

[[po-translations-tips-spaces]]
=== Сохранение пробелов

Сохраняйте существующие пробелы в начале и конце строк, которые нужно перевести. В переведённой версии эти пробелы также должны присутствовать.

[[po-translations-tips-verbatim]]
=== Дословные теги

Содержимое некоторых тегов должно быть скопировано дословно, без перевода:

* `man:man[1]`
* `package:package[]`
* `link`
* `image`
* `include`
* `Admonitions`
* `id's`
* `Heading tags`
* `source`

[[po-translations-building]]
== Сборка переведенного документа

Переведённую версию оригинального документа можно создать в любое время. При этом все непереведённые части документа будут включены в итоговый документ на английском языке. Большинство PO-редакторов имеют индикатор, показывающий, какая часть перевода завершена. Это позволяет переводчику легко увидеть, когда переведено достаточно строк, чтобы сборка итогового документа имела смысл.

Глава о Weblate есть полный пример того, как crossref:weblate[weblate-building,Собрать переведённый документ].

[[po-translations-submitting]]
== Отправка новой переведённой версии

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

Файлы различий, созданные в этих примерах, можно прикрепить к https://bugs.freebsd.org/bugzilla/enter_bug.cgi?product=Documentation[отчёту об ошибке в документации] или https://reviews.freebsd.org/[обзору кода].

[[po-translations-submitting-spanish]]
.Перевод статьи NanoBSD на испанский язык
[example]
====
[.procedure]
======

. Создайте diff новых файлов из базового каталога [.filename]#~/doc/# так, чтобы полный путь отображался вместе с именами файлов. Это помогает коммиттерам определить целевой языковой каталог.
+
[source, shell]
....
% cd ~/doc
% git diff documentation/content/es/articles/nanobsd/ > /tmp/es_nanobsd.diff
....
======

Глава о Weblate содержит полный пример того, как crossref:weblate[weblate-submitting-translations, отправить новый перевод].

====