﻿АННОТАЦИЯ

Это перевод с английского содержимого файла "CONTRIBUTING.md"
В переводе были исправлены некоторые обнаруженные в оригинале ошибки.

Переводчик: Aleksandr Felda <afelda@rambler.ru>
Дата: 14.03.2026

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

СОГЛАШЕНИЯ

Текст документа набран таким шрифтом.

Команды, которые вводятся в терминале с клавиатуры (т.е. команды оболочки Bash), 
набраны таким шрифтом в обратных одиночных скобках, например, 

	`cd man-l10n-clone`

При вводе команды обратные скобки должны быть удалены.

ПЕРЕВОД

1 ОБ УЧАСТИИ В ПРОЕКТЕ MANPAGES-L10N

Как описано в файле README.md, проект manpages-l10n предоставляет инфраструктуру
для перевода страниц руководства. Здесь же мы описываем собственно рабочий процесс 
получения оригинальных (на английском языке) страниц руководства, их перевода и, 
наконец, загрузки переводов в проект manpages-l10n.

Примечание переводчика. Все нижеописываемые действия предполагают (если не указано другое), что вы работаете в терминале, используете оболочку Bash и находитесь в каталоге вашего клона проекта manpages-l10n. Например, если ваш домашний каталог /home/user, а каталог вашего клона /home/user/man-l10n-clone, то, находясь в терминале в вашем домашнем каталоге, вы должны выполнить команду:

	`cd man-l10n-clone`

и таким образом перейти в каталог вашего клона «man-l10n-clone».

2 БЫСТРЫЙ СТАРТ - ТИПОВОЙ РАБОЧИЙ ПРОЦЕСС ПЕРЕВОДА

Предположим, вы хотите перевести или обновить файл echo.1.po.
Примечание переводчика. Здесь предполагается, что файл echo.1.po существует
и расположен в каталоге «...po/ru/man1». 

Во-первых, убедитесь, что ваш клон проекта обновлен. Для этого выполните 
команду:

	`git pull`

Затем обновите файл из шаблона .pot и обновите компедиум. Для этого выполните
следующие команды:

Переходим в подкаталог po:

	`cd po`

Выполняем, в этом подкаталоге, команду:

	`./update-po.sh man1/echo.1.po nn`

Примечание переводчика. Здесь nn - код языка. Для русского языка nn = ru. Поэтому 
команда будет иметь вид:

	`./update-po.sh man1/echo.1.po ru`  

После этого укажите свои авторские права. Например, в редакторе "poedit" откройте файл echo.1.po; затем в меню перейдите в "Перевод" > "Свойства" и в открывшемся подменю заполните поля:
 
"Название и версия проекта", "Команда переводчиков"; после этого перейдите "Правка" > "Настройка" и в открывшемся подменю, заполните поля: "Имя", Электронная почта"). Как только закончите перевод, добавьте файл в репозиторий и компедиум, например, для русской команды переводчиков, выполните команды:

	`git pull`

	и

	`./use-for-compendium.sh ru/man1/echo.1.po`

Затем зафиксируйте обновление. В этом примере предполагается, что код вашего 
языка "ru". Пожалуйста, всегда указывайте код вашего языка:

Подготавливаем файл для фиксации:

	`git add ru/man1/echo.1.po` 

Фиксируем файл:

	`git commit -a -m "[ru] Update translation of echo.1" `

Загружаем файл в проект manpages-l10n (вам потребуется ваш идентификатор и пароль):

	`git push`

Рабочий процесс завершен.

3 РАБОЧИЙ ПРОЦЕСС ПОСЛЕ ОБНОВЛЕНИЯ

Во время обновления в компедиуме появляется множество слегка измененных строк, например, новые даты или обновленные номера версий. Рекомендуется выполнить
следующее:

Убедитесь, что ваш клон идентичен проекту manpages-l10n:

	 `git pull`

Внесите изменения в компедиум вашего языка. Например, если вы находитесь в 
каталоге po, то для русского языка, выполните:

	`cd ru/common`

Теперь откройте и отредактируйте файлы min-100-occurences.po, 
min-020-occurences.po, min-010-occurences.po.

Обновите все строки, такие как переводы, даты, обновленные версии и т.д.

Затем зафиксируйте их:

	`git pull`

	`git commit -a -m "[nn] Unfuzzy/translate compendium" `

Следующий шаг займет несколько минут, но сэкономит вам массу времени:

Переходим в каталог po и выполняем:

	`./update-translations.sh`

	`git pull`

	`git commit -a -m "[ru] Update translations from compendium" `

Теперь вы можете проверить, какие еще обновления вам понадобятся, вернувшись
к типовому рабочему процессу, описанному выше.

4 ЧТО ТАКОЕ КОМПЕНДИУМ?

В переводе некоторые строки используются повторно. Например, заголовки разделов 
("СМОТРИТЕ ТАКЖЕ"), даты или обычные строки типа "Это свободное программное 
обеспечение: вы можете свободно изменять и распространять его, но без "КАКИХ-ЛИБО
ГАРАНТИЙ, в той мере, в какой это разрешено законом".

Компедиум позаботится о том, чтобы вы перевели эти строки только один раз.
Когда вы обновляете страницу с помощью ./update-po.sh или создаете новый файл po
для перевода, тогда скрипты просматривают компедиум. Если скрипты найдут какие-то строки, то они автоматически добавят их в ваш перевод.

Например, когда я создаю немецкий перевод для страницы руководства в разделе 2 
или 3, иногда 60-70% строк используются повторно, т.е. уже присутствуют в 
компедиуме.

Это значительно экономит время и позволяет избежать незначительных ошибок и 
несоответствий в переводе.

Поэтому рекомендуется добавить перевод (как только он будет готов или если он был
подвергнут изменениям) в компедиум, используя скрипт ./use-for-compendium.sh. 
Кроме того, если вы исправляете перевод, то вам тоже следует запустить этот скрипт.

Файлы компедиума расположены в каталоге common/, где вы также можете
редактировать их напрямую (это файлы .po). Чем больше число в названии
файла, тем чаще встречается строка. Поэтому время от времени, например, после 
обновления, было бы разумно сначала отредактировать их, а затем запустить скрипт

	`./update-translations.sh`

Выполнение этого скрипта занимает несколько минут, но избавляет вас от рутинной
работы, например, со строками обновленной версии или датами.

5 ПОЛУЧЕНИЕ ОРИГИНАЛЬНЫХ СТРАНИЦ РУКОВОДСТВА

Мы поддерживаем несколько дистрибутивов. Чтобы получить оригинальные страницы 
руководства (т.е. страницы руководства на английском языке), мы ведем списки пакетов для 
каждого дистрибутива в каталоге: 

	`upstream/*название_дистрибутива*/packages.txt` 

Обычно мы загружаем все перечисленные пакеты один или два раза в месяц и распаковываем страницы руководства с помощью скрипта:

	`./upstream/update-distribution-manpages.sh` 

Этот скрипт также объединяет ссылки, чтобы они не отображались позже в виде файлов, которые можно перевести.

Примечание: Иногда необходимо сохранить номер версии пакета в файлах 
packages.txt. В таких случаях убедитесь, что пакет с таким номером версии 
действительно существует в репозиториях дистрибутива. Если он не существует, то 
ничего не будет загружено, и страницы руководства этого пакета исчезнут из каталога upstream и из соответствующих шаблонов перевода. 

В настоящее время это относится к некоторым пакетам systems* 
и sane-backends в Opensuse (как в Tumbleweed, так и в Leap) и openssl в Arch linux. 

Улучшения в скрипте приветствуются!

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

	upstream/*название_дистрибутива*/untranslated.txt. 

Они содержат только те страницы руководства, для которых уже существует шаблон, 
то есть для которых доступны файлы po на других языках. Поэтому список неполный. 

Если вы хотите перевести определенную страницу руководства, то запустите скрипт: 

	`./create-new-translation.sh man_pages_name language_code translators_list`

из каталога */po. Если это удается, то соответствующая оригинальная страница 
руководства существует, по крайней мере, в одном из вышестоящих каталогов, тогда 
будет создан файл .po и соответствующий шаблон pot. 

Если вы запустите скрипт с опциями man_pages_name, language_code и translators_list, 
то будет создан файла перевода .po с ОБЯЗАТЕЛЬНЫМ заголовком (подробнее смотрите 
ниже в разделе «8 ИСПОЛЬЗУЙТЕ ОБЯЗАТЕЛЬНЫЕ ЗАГОЛОВКИ ФАЙЛОВ».

Пример: 
	`./create-new-translation.sh head.1 ru translators_list`

Как создать файл "translators_list" смотрите в файле "pattern_translators_list". 

Примечание. 
Файл ".po" с обязательным заголовком будет создан ТОЛЬКО в подкаталоге вашего 
языка и в его соответствующем подкаталоге manN, например, для немецкого языка, 
это будет подкаталог "/po/de/manN". Этим скриптом также будет создан файл 
".pot" в подкаталоге "/templates/manN". Этот файл НЕ БУДЕТ иметь 
обязательного заголовка.

Если не удается создать страницу, то обратитесь к сопровождающему manpages-l10n, 
который подскажет, где можно найти оригинальную страницу руководства (название пакета).

6 СОЗДАНИЕ ШАБЛОНОВ

После обновления содержимого каталога "upstream/*название_дистрибута*/man*" мы 
создаем шаблоны. Скрипт templates/update-all-templates.py обновляет существующие 
файлы \*.pot на основе новых страниц руководства. Вы можете запустить скрипт 
`templates/generate-one-template.sh` для создания нового или обновления 
существующего шаблона.

7 ОБНОВЛЕНИЕ ПЕРЕВОДОВ

Запустите команду `./update-translations.sh`, чтобы обновить существующие файлы
\*.po (как ./update-translations.sh из каталога кода вашего языка) на основе 
ранее измененных шаблонов. Позже вы можете запустить `./update-po.sh`
для обновления отдельного файла po или `./update-translations.sh` для повторного 
обновления всех существующих файлов po на основе текущих шаблонов и файлов 
компедиума (смотрите ниже, как использовать компедиум).

8 ИСПОЛЬЗУЙТЕ ОБЯЗАТЕЛЬНЫЕ ЗАГОЛОВКИ ФАЙЛОВ

Заголовок файла po должен выглядеть похожем на это:

# German translation of manpages
# This file is distributed under the same license as the manpages-l10n package.
# Copyright © of this file:
# Mario Blättermann <mario.blaettermann@gmail.com>, 2015.

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

Примечание. Обязательный заголовок можно создать также автоматически с помощью
скрипта `create-new-translation.sh` (смотрите выше в разделе "5 ПОЛУЧЕНИЕ 
ОРИГИНАЛЬНЫХ СТРАНИЦ РУКОВОДСТВА".  

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

Скрипту `./generate-manpage.sh` заголовок нужен для создания дополнения (раздела 
ПЕРЕВОД). Скрипт `create-authors-file.sh` также считывает из заголовка имена 
переводчиков и выдает "мусор", если в нем есть какие-то иные дополнительные строки.

Единственное исключение: строки комментариев, начинающиеся с # FIXME, будут 
игнорироваться скриптами. Но, возможно, полезнее размещать такие FIXME 
непосредственно над соответствующими сообщениями Gettext.

ПРИМЕЧАНИЕ: В редакторе Lokalize в версии 23.08.1 генерирует строки заголовка 
следующего вида:

# Mario Blättermann <mario.blaettermann@gmail.com>, 2023.

Это привело бы к появлению странных записей в дополнении к странице руководства 
и в файле AUTHORS.md. Вам нужно исправить эту строку вручную. Это невозможно 
исправить в настройках Lokalize. 

Это - программная ошибка: https://bugs.kde.org/show_bug.cgi?id=475166

9 РАБОЧИЙ ПРОЦЕСС GIT ДЛЯ СОЗДАННЫХ ФАЙЛОВ PO

После перевода и просмотра файла po (при условии, что вы использовали копию
этого файла и не применяли свои изменения непосредственно в вашем локальном клоне 
Git), вам следует выполнить следующие действия:

    • Выполните команду `git pull`, чтобы получить последние изменения от других 
	участников и переводчиков.

    • Подтвердите свой файл po с помощью `msgfmt -vc`.

    • Поместите свой файл po в нужное место в иерархии каталогов Git (пока не 
	фиксируйте его).

    • Запустите команду `git status` и/или `git diff`, чтобы посмотреть, что нужно 
	изменить.

    • Запустите скрипт `./update-po.sh`, чтобы выполнить обновление вашего файла po
	в соответствии с шаблоном и данными из компедиума. Теперь вам следует еще раз 
	просмотреть файл po. Если что-то не так, то исправьте ошибки.

    • Добавьте свой файл po в промежуточную область для фиксации. Например:

		`git add de/man1/chown.1.po` 

    • Зафиксируйте свой файл po. Команда должна выглядеть следующим образом:

		`git commit -a -m "[ru] Update chown.1.po" `

    • Чтобы было проще различать разные языки, добавьте в качестве комментария к 
	сообщению о фиксации [код вашего языка]. Примечание переводчика. Выше 	
	приведён код русского языка (ru). 

    •  Запустите команду git push. Обычно после ввода вашего логина и пароля все 
	должно быть в порядке. Но в некоторых случаях другой участник за это время 
	может внести некоторые изменения. Тогда Git отказывает в фиксации. 
	Тогда сначала снова запустите git pull. В этом случае удаленный сервер 
	переходит в ваше локальное хранилище и открывает редактор, в котором вы 
	можете изменить сообщение о фиксации. В большинстве случаев нет 
	необходимости что-либо изменять, просто закройте редактор (и,при необходимости,
	сохраните это сообщение). Снова запустите git push.
  
10 ПОЛУЧЕНИЕ КРАТКОЙ СПРАВКИ ПО ИСПОЛЬЗОВАНИЮ СКРИПТА

Большинство скриптов (но не все!) в каталоге po для вывода краткого справочного 
сообщения по использованию данного скрипта поддерживают опцию "-h". Например, 
если выполнить в каталоге po команду:

	`./format-po.sh -h`

Вывод команды:

"Usage: ./format-po.sh language_code
This script reformats any *.po files. It wraps the lines at 80 characters and 
removes outdated messages at the end of the file.
It is mandatory to submit the language code as parameter.
Alternatively call it directly from the language directory, e.g. po/fr".

Еще пример:

	`./use-for-compendium.sh -h` 

Вывод команды:

"Usage: ./use-for-compendium.sh language_code
This script uses a certain *.po file for the compendium. It adds the gettext 
messages to the files in */common/*.
It is mandatory to call it with the relative path to the desired file.
Example: ./use-for-compendium.sh de/man1/chown.1.po".

11 СОЗДАНИЕ НОВЫХ ПЕРЕВОДОВ

Скрипт `./create-new-translation.sh` создает новый файл .po.
Это предполагает, что оригинальный файл Groff или Mdoc уже существует в каталоге
"upstream/man\*" по крайней мере для одного из поддерживаемых нами дистрибутивов.
Если нет, то попробуйте выяснить название дистрибутива, содержащего эту 
страницу руководства обратившись к 
[Марио Блэттерманну] (mailto:mario.blaettermann@gmail.com), чтобы получить страницу 
в проект manpages-l10n.

Помимо создания файла po, это скрипт создает (при необходимости) шаблон и
обновляет шаблоны компедиума в templates/common/ и файлы компедиума
для вашего языка в "po/*код_вашего_языка*/common". Скрипт никогда не затрагивает
другие языки, кроме вашего собственного.

Примечание: Не забудьте выполнить git add filename после того, как вы создали 
и/или обновили файл, прежде чем выполнять команду git push. 
 
12 ЗАПОЛНЯЙТЕ И ИСПОЛЬЗУЙТЕ КОМПЕДИУМ

После просмотра и фиксации файла po вы можете запустить скрипт 
`./use-for-compendium.sh`, чтобы добавить ранее просмотренные сообщения в свой 
компедиум. Например:

	`./use-for-compendium.sh nn/man1/chown.1.po`,

	где nn - код языка.

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

ВНИМАНИЕ: Вы всегда должны указывать относительный путь (т.е. путь,
относительно каталога po), только собственно названия файла недостаточно.

После добавления файла в компедиум вы можете записать изменения обратно во все
файлы po с помощью команды:

	`./update-translations.sh`

Может случиться так, что вы столкнетесь с неоднозначным сообщением Gettext, которое
не следует использовать в компедиуме. В таких случаях добавьте следующие строки 
в файл templates/exclude.pot:

msgid "I<source>"
msgstr ""

ВНИМАНИЕ! Не забудьте указать пустые двойные скобки в строке msgstr "", иначе в 
следующий раз обновление шаблонов завершится ошибкой! После добавления сообщения 
сначала запустите скрипт:

	`create-common-templates.sh`

Это гарантирует, что нежелательное сообщение действительно исчезнет из компедиума.

После этого вам также следует запустить скрипт 

	`.de/update-common.sh`

для вашего языка, (в примере выше de - код немецкого языка), 
чтобы другие скрипты, такие как `./create-new-translation.sh` или 
`./update-po.sh`, больше не использовали данное сообщение Gettext. 

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

13 ФОРМАТИРОВАНИЕ ФАЙЛОВ \*.PO

Скрипт `./format-po.sh` форматирует все файлы po на вашем языке так, как это 
сделал бы msgcat -w 80; т.е. он делает все строки длиной 80 символов.
Кроме того, будут удалены неиспользуемые сообщения Gettext в конце файлов po.

Примечание. Этот скрипт ожидает правильно отформатированные файлы po;
запустите msgfmt -vc *your_po_file* и убедитесь, что файл правильно отформатирован
с точки зрения Gettext. В противном случае скрипт может полностью уничтожить файл, 
и вам потребуется отменить изменения.

14 СОЗДАНИЕ ПЕРЕВЕДЕННЫХ СТРАНИЦ РУКОВОДСТВА

С помощью команды `./generate-manpage.sh` можно создать одну переведенную 
страницу руководства. Например, запустив из каталога .po для русского языка команду:

	`./generate-manpage.sh archlinux man1/chown.1.po ru`

При этом создается страница руководства в каталоге с названием "archlinux". 
Но вы также можете создать все страницы руководства для русского языка из всей 
коллекции файлов po, используя, например, команду:

	`./generate-all-manpages.sh ru/archlinux/man*`

Все созданные страницы получают дополнение, которое состоит из имен переводчиков 
и их почтовых адресов, указанных в заголовках файла .po, а также описания лицензии, 
взятого из файла po/ru/license.add.

15 ПРОВЕРКА БЕЗОПАСНОСТИ С ПОМОЩЬЮ GIT- HOOKS

GIT- HOOKS - это способ запуска скриптов до или после определенных шагов.
Каталог "hooks" в настоящее время содержит скрипт "pre-commit", который проверяет
форматирование файлов po, которые должны быть зафиксированы, и прерывает фиксацию 
с объяснением, если некоторые из этих файлов недействительны.

Чтобы "установить" этот hook, запустите его из корневой папки проекта:

	`ln -s ../../hooks/pre-commit .git/hooks/pre-commit`


16 АВТОМАТИЧЕСКОЕ СОЗДАНИЕ СООБЩЕНИЙ [DONE] С ИСПОЛЬЗОВАНИЕМ GIT- HOOKS

Используя тот же git-hook, что и вышеописанный, также можно включить автоматическое
создание сообщений "[DONE]" в ваш список рассылки l10n при фиксации новых переводов.

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

	`cp hooks/pre-commit.conf.template hooks/pre-commit.conf`

Как только появится файл _pre-commit.conf_exists, то просто заполните его 
необходимой информацией.

ВНИМАНИЕ: для этого hook требуется установить пакет curl.

17 ПРИМИТЕ УЧАСТИЕ В УПРАВЛЕНИИ ПАКЕТАМИ

Проект manpages-l10n имеет многоцелевое назначение, поэтому его необходимо 
выпускать каждые 3 месяца. Если вы хотите помочь в решении этих административных
задач, то сделайте следующие.

Во-первых, получите соответствующие права доступа в репозиторий salsa.

Затем:
    • Найдите с помощью grep номер текущей версии. Вы увидите некоторые совпадения 
в файлах "configure", "configure.ac", "CHANGES.md" и т.д.
(Не обращайте внимания на номера версий в заголовках файлов po). Запустите:

	`grep '^AC_INIT' configure.ac | sed 's/.*\[\(.*\)\].*/\1/'`
	`grep '^##' CHANGES.md | head -n1`

    •  Замените старый номер версии на новый в файле "configure.ac".
    •  Сделайте соответствующую запись в файле "CHANGES.md".
    • Запустите `./autoreconf`
    • Зафиксируйте и внесите изменения.
    • Создайте соответствующий тег:
      В командной строке:

	`git tag -a -m 'Release 4.22.0' 4.22.0`

	измените  соответствующий номер выпуска. 
	"-a" - для обозначения аннотации, обычно используемой для выпусков 
	(https://git-	scm.com/docs/git-tag)

	"-m " - сообщение, о котором вы упомянули.

	"4.22.0" - название тега

* Протолкните тег:

	`git push --tags`


Как только проталкивание будет завершено, укажите выпуск в веб-интерфейсе в 
разделе Deploy → Releases (Развертывание → Выпуски). Использовать "Выпуск 4.21.0" 
и добавьте в список изменений.

Вот и все. Пользователи и последующие упаковщики теперь могут загружать архивный 
файл tarball из известного местоположения.


