Перевод веб-страниц Debian

Чтобы максимально облегчить работу переводчиков, страницы генерируются способом, немного отличным от того, к которому большинство из вас привыкли. Веб-страницы на самом деле генерируются из исходного кода, размеченного с использованием языка wml. Для каждого языка существует отдельный каталог.

Если вы планируете начать перевод веб-сайта Debian на новый язык, прочтите, пожалуйста, раздел о запуске нового перевода.

Перевод отдельных страниц

Чтобы отделить содержимое конкретной страницы от элементов, повторяющихся на нескольких страницах, мы используем WML. Это означает, что нужно редактировать исходные файлы WML, а не файлы HTML. Чтобы получить исходные тексты, используйте Git. Вы должны извлечь, по крайней мере, два каталога: webwml/english/ и webwml/<язык>/.

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

Заголовки переводов

Переводчикам настоятельно рекомендуется добавлять к заголовку файла после последней строки #use дополнительную строку с информацией о коммите оригинального файла, чтобы обновлять перевод было проще. Эта строка выглядит примерно так: #use wml::debian::translation-check translation="<хэш_коммита_git>" Заметьте, что если вы создаёте файл с помощью инструмента copypage.pl (его использование настоятельно рекомендуется), то хэш коммита git будет вставлен автоматически. Использование copypage.pl объясняется ниже.

Некоторые команды перевода также используют эту строку, чтобы отметить официального переводчика каждой веб-страницы. В этом случае вы будете автоматически получать почту при внесении изменений в английский оригинал страниц, которые вы сопровождаете, когда нужно будет обновить перевод. Чтобы этот механизм работал, просто добавьте ваше имя в конце строки #use, чтобы она выглядела следующим образом: #use wml::debian::translation-check translation="хэш_коммита_git" maintainer="ваше имя". Скрипт copypage.pl выполнит это автоматически, если вы установите переменную окружения DWWW_MAINT или вызовите его с ключом -m.

Заголовок веб-страницы может быть легко создан с помощью скрипта copypage.pl в корневом каталоге webwml. Этот скрипт копирует страницу в нужное место, при необходимости создаёт каталоги и файлы Makefile и автоматически добавляет требуемый заголовок. Вы будете извещены в следующих случаях: если копируемая страница уже существует в репозитории, если она была удалена из репозитория (из-за того, что страница была слишком устаревшей), если кто-то уже зафиксировал перевод в репозитории и ваша локальная копия репозитория неактуальна.

Для того, чтобы начать использовать copypage.pl, вы должны сначала настроить файл language.conf в корневом каталоге webwml, который будет использоваться для определения языка перевода. В этом файле требуется указать не более двух строк: в первой строке указывается язык (например, russian), во второй вы можете указать имя переводчика. Также вы можете использовать переменные окружения DWWW_LANG для указания языка и DWWW_MAINT для указания вашего имени, чтобы оно было добавлено в заголовок создаваемых wml-файлов, как имя сопровождающего данного перевода. Либо имеется третья возможность: вы можете указать язык и (опционально) сопровождающего в командной строке с помощью -l russian -m "Donald Duck" и вообще не использовать файл language.conf. У этого сценария доступны и другие функции. Для получения справки выполните его без каких-либо аргументов.

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

Сборка и публикация страницы

Так как мы используем согласование содержания, файлы HTML называются не файл.html, а файл.<яз>.html, где <яз> — двухбуквенный код языка в соответствии с ISO 639 (например, fr для французского языка).

Вы можете собрать HTML из WML, выполнив команду make файл.<яз>.html. Если эта команда работает, проверьте правильность синтаксиса командой weblint файл.<яз>.html.

ВНИМАНИЕ: Веб-страницы регулярно и автоматически собираются заново на сервере www-master, используя исходный код wml из git. Этот процесс, в основном, не вызывает ошибок. Однако, если вы добавите некорректный файл на верхнем уровне вашего перевода (например, файл верхнего уровня index.wml), он заблокирует процесс сборки и не позволит обновить другие части сайта. Пожалуйста, обратите особое внимание на эти файлы.

Как только страница достаточно проработана, вы можете зафиксировать её в Git. Если у вас есть права сделать это непосредственно, то добавьте коммиты в git-репозиторий webwml; если нет, то отправьте их кому-нибудь из тех, кто имеет доступ к репозиторию с правами на запись.

Как начать новый перевод

Если вы хотите начать перевод веб-страниц Debian на новый язык, отправьте сообщение об этом (на английском) на [email protected].

Для начала, клонируйте дерево исходного кода как это описано на нашей вводной странице о Git.

После того, как вы получите исходный код, создайте новый каталог для вашего перевода, рядом с english/ и другими каталогами переводов. Имя каталога перевода должно быть английским названием языка и полностью в нижнем регистре (например "german", а не "Deutsch").

Скопируйте файлы Make.lang и .wmlrc из каталога english/ в каталог нового перевода. Они необходимы для сборки вашего перевода из файлов WML. После того, как вы скопируете их в новый каталог языка, необходимо изменить следующие параметры:

  1. В файле Make.lang следует изменить переменную LANGUAGE.
  2. В файле .wmlrc следует изменить переменные CUR_LANG, CUR_ISO_LANG и CHARSET. Добавьте переменную CUR_LOCALE, если она нужна для сортировки.
  3. Некоторые языки могут требовать дополнительной обработки используемой кодировки. Она может быть реализована с помощью параметров команды wml --prolog и --epilog. Используйте в этом случае переменные WMLPROLOG и WMLEPILOG в файле Make.lang.
  4. В файле webwml/Makefile верхнего уровня следует изменить переменную LANGUAGES, чтобы на www.debian.org ваш язык собирался вместе с остальными. Мы предпочли бы, чтобы вы оставили это изменение нашим веб-мастерам, потому что при следующем извлечении копии из системы управления версиями вы не сможете узнать, что ваши файлы некорректны, в то время как это может заблокировать сборку всей остальной части нашего веб-сайта.

После этих изменений добавьте к файлу Makefile в новом каталоге: 

include $(subst webwml/язык,webwml/english,$(CURDIR))/Makefile

(замените язык названием каталога вашего языка).

Теперь создайте в каталоге вашего языка подкаталог po и скопируйте тот же файл Makefile в этот подкаталог (cp ../Makefile .).

В каталоге po/, запустите make init-po, чтобы cгенерировать начальный набор файлов *.po.

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

Начните переводить файл po/templates.xy.po (где xy — двухбуквенный код вашего языка). Каждому msgid "сообщение" изначально соответствует msgstr "", куда (между двойными кавычками) вам следует ввести перевод строки сообщение.

Вам не обязательно переводить все строки во всех файлах .po, только используемые в уже переведённых страницах. Чтобы узнать, нужно ли переводить строку, см. комментарии в файле .po над оператором msgid. Если указанный там файл находится в english/template/debian, скорее всего, вам следует перевести сообщение. В противном случае вы можете отложить перевод этого файла до тех пор, пока не переведёте раздел сайта, где он используется.

Переход на использование файлов из каталога po/ облегчает работу переводчиков, позволяя им (почти) никогда не редактировать непосредственно файлы из каталога english/template/debian. Если вы обнаружите какую-то ошибку в самом каталоге template, постарайтесь решить проблему глобально (не стесняясь попросить кого-нибудь об этом), не фиксируйте переводы в templates, что (обычно) создаёт большую проблему.

Если вы не уверены в том, правильно ли вы что-то сделали, то перед фиксацией изменений задайте об этом вопрос в списке рассылки debian-www.

Обратите внимание: если вы считаете, что должны сделать какие-либо другие изменения, пошлите письмо на debian-www, в котором напишите, что вы изменили и почему, чтобы проблема могла быть исправлена в дальнейшем.

После того, как скелет шаблона сделан, вы можете начать переводить титульный лист и другие файлы *.wml. Список файлов, которые должны быть переведены в первую очередь, можно найти в советах по переводу веб-страниц. Переводите отдельные *.wml страницы так, как описано в начале этой страницы.

Актуализация устаревших переводов

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

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

Например, если удалённый файл назывался "deleted.wml", то вы можете выполнить следующую команду:

   git log --all --full-history -- <путь/к/файлу/deleted.wml>

Вы найдёте коммит, в котором нужный вам файл был удалён, а также хэш этого коммита. Для отображения подробной информации об изменениях в данном коммите, вы можете использовать команду git show:

  git show <СТРОКА_С_ХЭШЕМ_КОММИТА> -- <путь/к/файлу/deleted.wml>

Если этот коммит только удалял файл, то вы сможете восстановить его в рабочее пространство с помощью git checkout:

  git checkout <СТРОКА_С_ХЭШЕМ_КОММИТА>^ -- <путь/к/файлу/deleted.wml>

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

Дополнительная информация

Описанного выше должно быть достаточно, чтобы позволить вам начать перевод. Впоследствии, вы возможно захотите обратиться к другим документам, которые содержат более подробные объяснения и дополнительную полезную информацию:

Мы надеемся, что вы оцените работу, которую мы выполнили, сделав перевод страниц как можно проще. Как уже было отмечено, если у вас есть какие-либо вопросы, вы можете задать их в списке рассылки debian-www.