Provided by: po-debconf_1.0.16_all bug

НАЗВАНИЕ

       po-debconf -- общее описание

ОПИСАНИЕ

       The goal of "debconf" was to make package configuration user-friendly.
       In order to achieve this, it is important to ensure that users will get
       the question in their own language.  Translators need a framework to
       easily work on translations without having to track package
       development; "po-debconf" was designed to be able to work with standard
       "gettext" tools when translating debconf templates files.

ДОБАВЛЕНИЕ ПОДДЕРЖКИ ИНТЕРНАЦИОНАЛИЗАЦИИ (I18N) В ФАЙЛЫ ШАБЛОНОВ DEBCONF

       Если вы добавляете поддержку debconf в свой пакет, то вам нужно
       написать файл шаблонов на английском языке. Для того чтобы правильно
       добавить поддержку интернационализации (i18n) в свой пакет, требуется:

       - создать debian/po/POTFILES.in
           Этот файл содержит список мастер-шаблонов. Обычно он содержит
           только одну строку:

             [type: gettext/rfc822deb] templates

           Пути относительно родительского каталога.

       - Prepend an underscore before translatable fields in each template
           Обычно переводятся поля "Description", "Choices" и иногда
           "Default".

       - запустить debconf-updatepo
           Она создаст файл debian/po/templates.pot, который переводчики будут
           переводить на свой язык.

       - добавить зависимость сборки от "po-debconf" в файл debian/control

ОБНОВЛЕНИЕ ШАБЛОНОВ

       In order to help translators, PO files in your package should always be
       up-to-date, otherwise they may waste their time translating unused
       strings.  For that, simply call the following command without
       arguments:

         $ debconf-updatepo

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

       При переименовании, добавлении или удалении файлов шаблонов, также не
       забудьте внести соответствующие изменения в файл debian/po/POTFILES.in,
       иначе английские строки пропадут из PO-файлов и будут показаны
       пользователям даже если PO-файлы полностью переведены.

       The debconf-updatepo program is idempotent, it modifies PO files only
       if their content has been updated.  Thus the best way to provide up-to-
       date PO files in your source package is to call this command from the
       "clean" target of the debian/rules file.

       Заметьте, что вы должны запускать debconf-updatepo даже в случае
       использования dh_installdebconf. Последний вызывает po2debconf, который
       в свою очередь запускает debconf-updatepo, если обнаруживаются
       устаревшие файлы, но это не очень хорошее решение как минимум по двум
       причинам:

       1. Для обнаружения устаревших файлов po2debconf использует временные
          отметки и может неправильно сработать, если используется "pbuilder"
          или если устаревшие переводы были записаны на диск после изменения
          шаблонов

       2. dh_installdebconf вызывается уже после генерации файла ".diff.gz"

ОБЪЕДИНЕНИЕ ПЕРЕВОДОВ И ОРИГИНАЛА

       Вам нужно проверить, что при сборке пакета переводы попадают в готовый
       пакет. Вы можете делать это вручную или автоматически с помощью
       сценария dh_installdebconf (проверьте, что в зависимостях сборки есть
       "debhelper (>= 4.1.16)").

       Чтобы сделать это вручную, нужно объединить шаблоны и переводы во время
       сборки (и должна быть зависимость от "po-debconf"), например:

         $ po2debconf debian/templates > debian/tmp/DEBIAN/templates

       ОСТОРОЖНО: эти два файла с именем templates имеют разное содержимое.
       Первый содержит только английский текст и некоторые поля, помеченные
       для перевода, а второй содержит текст на всех остальных языках. Надо
       добавить, что вы НЕ МОЖЕТЕ хранить только объединённые шаблоны, иначе
       вы не сможете договориться с переводчиками, чтобы они выполняли
       обновление.

НОВЫЕ МАСТЕР ШАБЛОНЫ

       Новый формат исходных мастер-шаблонов почти повторяет распространяемый
       файл шаблонов, но здесь переводимые поля начинаются с символа
       подчёркивания. Пример:

         Template: debconf/frontend
         Type: select
         _Choices: Dialog, Readline, Gnome, Editor, Noninteractive
         Default: Dialog
         _Description: Interface to use for configuring packages:
          Packages that use debconf for configuration share a common look and
          feel.  You can select the type of user interface they use.
          .
          The dialog frontend is a full-screen, character based interface,
          while the readline frontend uses a more traditional plain text
          interface, and the gnome frontend is a modern X interface.  The
          editor frontend lets you configure things using your favorite text
          editor. The noninteractive frontend never asks you any questions.

   РАЗДЕЛЕНИЕ СПИСКА ВЫБОРА
       Since "po-debconf" 0.6.0, localized fields may contain two leading
       underscores.  In this case, the field value is supposed to be a comma
       separated list of values, which are put in separate msgids.  Thus if
       the previous example did contain

         __Choices: Dialog, Readline, Gnome, Editor, Noninteractive

       то было бы 5 разных msgid. Заметим, что пробелы после запятых не
       обязательны.

       When a choices list never changes, "_Choices" may be considered fine.
       However, splitting such lists may help avoiding frequent mistakes in
       translations such as omitting a choice or using non-standard commas.
       For such reasons, the use of "__Choices" will ease translator's life
       and is strongly recommended.

       Unfortunately if you decide to switch from "_Choices" to "__Choices",
       all translations become fuzzy.  Here is an explanation to make this
       change without translation loss (it requires "po-debconf" >= 1.0).
       Suppose that we want to switch the previous example to "__Choices".
       You copy the templates file into a temporary file.

         $ cp debian/templates debian/foo

       Отредактируйте debian/foo и оставьте только поля "Template", "Type" и
       "_Choices" из этого примера

         Template: debconf/frontend
         Type: select
         _Choices: Dialog, Readline, Gnome, Kde, Editor, Noninteractive

       Запустите debconf-gettextize с параметрами "--merge" и "--choices",
       чтобы собрать PO-файлы, как если бы было записано "__Choices", и
       объединить эти PO-файлы с существующими:

         $ debconf-gettextize --merge --choices debian/foo

       В конце удалите foo и вручную отредактируйте debian/templates заменив
       "_Choices" на "__Choices" перед тем как запустить debconf-updatepo.

   PUTTING IN COMMENTS FOR TRANSLATORS
       "Dpkg" maintainers decided that by convention lines beginning with a
       number sign ("#") are comments in debian/control files, and
       "po-debconf" follows this rule.  Since "po-debconf" 0.8.0, such
       comments are written into PO files, and can then contain valuable
       information for translators.  Incidentally all previous "po-debconf"
       versions ignore lines which do not contain a colon, thus if your
       comments does not contain any colons, there is no need to add a
       versioned build dependency against "po-debconf".  Here is an example:

         Template: debconf/button-yes
         Type: text
         # Translators, this text will appear on a button, so KEEP IT SHORT
         _Description: Yes

       В "po-debconf" 1.0 были добавлены специальные комментарии, учитывающие
       строки с несколькими элементами (например, поле Choices) или параграфы
       (например, в Description). С помощью новых директив разработчики
       получают больший контроль над тем, что показывать переводчикам. Команды
       имеют вид "#flag:directive"; директивы описаны далее.

       translate:spec, translate!:spec
          Отметить только некоторые элементы для перевода; spec является
          списком чисел через запятую, в котором указаны какие строки будут
          выводиться в PO-файлы. Можно указывать диапазоны значений через знак
          минус (например, "2-6"), звёздочка ("*") означает все строки.
          Например, из

            Template: partman-basicfilesystems/fat_mountpoint
            Type: select
            #flag:translate:3,4
            __Choices: /dos, /windows, Enter manually, Do not mount it
            _Description: Mount point for this partition:

          "Enter manually" и "Do not mount it" появятся в PO-файлах, а "/dos"
          и "/windows" -- нет. Если после ключевого слова translate поставить
          восклицательный знак, то в spec указываются какие строки будут
          исключены из PO-файлов, а все остальные строки будут выводиться.
          Предыдущий пример можно переписать как

            Template: partman-basicfilesystems/fat_mountpoint
            Type: select
            #flag:translate!:1,2
            __Choices: /dos, /windows, Enter manually, Do not mount it
            _Description: Mount point for this partition:

          Это же ключевое слово можно также применить к полю Description,
          чтобы быть уверенным, что некоторые строки не переводятся.

            Template: partman-crypto/options_missing
            Type: error
            #flag:translate!:3
            _Description: Required encryption options missing
             The encryption options for ${DEVICE} are incomplete. Please
             return to the partition menu and select all required options.
             .
             ${ITEMS}

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

       comment:spec, comment!:spec
          Комментарий ниже этой директивы относится к строкам, указанным в
          spec, которая задаётся выше. По умолчанию, комментарий записывается
          перед переводимым полем вместе со всеми строками принадлежащими
          этому полю.(Замечание: в "po-debconf" < 1.0 комментарий записывался
          только в первой строке)

            Template: arcboot-installer/prom-variables
            Type: note
            # Translators, the 4th string of this description has been dropped
            # from PO files.  It contains shell commands and should not be
            # translated.
            #flag:comment:3
            # "Stop for Maintenance" should be left in English
            #flag:translate!:4
            _Description: Setting PROM variables for Arcboot
             If this is the first Linux installation on this machine, or if the
             hard drives have been repartitioned, some variables need to be set
             in the PROM before the system is able to boot normally.
             .
             At the end of this installation stage, the system will reboot.
             After this, enter the command monitor from the "Stop for
             Maintenance" option, and enter the following commands:
             .
                setenv OSLoader arcboot
                setenv OSLoadFilename Linux
             .
             You will only need to do this once.  Afterwards, enter the "boot"
             command or reboot the system to proceed to the next stage of the
             installation.

          В примере выше комментарий указывался без директивы "#flag:comment",
          неявным добавлением "#flag:comment:*". Этот комментарий появился во
          всех строках, но указание Stop for Maintenance напечатано только
          перед соответствующей строкой.

       partial
          Это ключевое слово указывает po2debconf сохранить переведённые
          строки, даже если не все строки были переведены. Используйте с
          осторожностью, данное ключевое слово было добавлено для очень
          специфичных случаев.

   УВЕДОМЛЕНИЕ ПЕРЕВОДЧИКОВ ПЕРЕД АНОНСИРОВАНИЕМ НОВОЙ ВЕРСИИ
       Обычно переводчики уведомляются с веб-страницы состояния проекта
       (смотрите ниже), что перевод устарел и есть ссылка на новый файл
       будущего релиза. Но разработчикам, перед тем как заливать новую версию,
       предлагается рассмотреть, например, за неделю до срока, попросить
       сопровождающих перевод обновить его. Для этой цели была написана
       специальная программа -- podebconf-report-po. Не бойтесь злоупотреблять
       ею!

DEBUGGING

       You will find that debconf-loadtemplate will not accept a templates
       file with i18n markups.  However, it will accept a merged file, so if
       you have been debugging your debconf setup like this

         rm /tmp/{config,templates}.dat{,-old}
         debconf-loadtemplate debian/templates
         DEBIAN_PRIORITY=low debconf -freadline debian/config configure 28.0

       you will now need something like this instead:

         po2debconf debian/templates > debian/tmp/DEBIAN/templates
         rm /tmp/{config,templates}.dat{,-old}
         debconf-loadtemplate debian/tmp/DEBIAN/templates
         DEBIAN_PRIORITY=low debconf -freadline debian/config configure 28.0

ПРЕДОСТЕРЕЖЕНИЯ

       o "Debconf" 1.2.0 распознаёт поля в виде -., например,
         "Description-de.ISO-8859-1" или "Choices-ru.KOI8-R". По умолчанию,
         po2debconf сохраняет файлы шаблонов в новом формате. Ранние версии
         "debconf" игнорируют эти поля и отображают английские сообщения.
         Смотрите в po2debconf(1) как изменять кодировку и выходной формат.

       o A given English string may be given only one unique translation in a
         given language.  It is impossible to give two different translations,
         depending on the context.  To solve this issue, you have to add
         special markups to the different occurrences of a given string to
         make them different.  (These markers will only be visible to
         translators, and they will be removed from the string before being
         displayed to user)

         Эти метки должны добавляться в конец строк для перевода, они должны
         начинаться с "[ " (левая квадратная скобка с пробелом после) и
         заканчиваться "]" (правая скобка), и могут содержать любые символы
         внутри кроме скобок и символов новой строки. Например, "[ blahblah]"
         допустимая метка, а "[ bla[bla]bla]" нет. Для любителей Perl regexp,
         метки распознаются (и удаляются) с помощью выражения:

           $msg =~ s/\[\s[^\[\]]*\]$//s;

       o Пробелы обрабатываются неодинаково "po-debconf" и "debconf-utils";
         последний переформатирует параграфы при обновлении и объединении
         переводов, так как "debconf-utils" очень умный и считает, что пробелы
         не являются частью строк, при определении неясных элементов. (то
         есть, требуется внимание переводчика, так как оригинал изменился)

         С другой стороны, "po-debconf" полагается на "gettext" при
         определении неясных элементов, и не рассматривает пробелы как
         специальные символы. То есть, лишние пробелы должны быть удалены в
         конце строк в мастер-файлах шаблонов, или они появятся в PO- и
         POT-файлах.

         По этой же причине, debconf-gettextize может отметить текст как
         неясный из-за несовпадения пробельных символов, и переводчики должны
         вручную снимать неясность с таких строк. Это случается только при
         преобразовании шаблонов в "po-debconf" формат, если, конечно, вы
         произвольно не изменяете пробелы в мастер-файлах шаблонов, что
         болезненно отражается на переводчиках.

       o Обычно, поле Default: не должно переводиться, если шаблон имеет тип
         Select или Multiselect. В редких случаях (например, при выборе языка
         по умолчанию для приложения) локализованные значения более
         выразительны.

         Локализованное значение должно не переводиться, а выбираться из
         английских значений поля Choices. Лучшим путём достигнуть этой цели
         является вставка комментария в файл шаблонов, который будет
         скопирован в PO-файлы.

           Template: geneweb/lang
           Type: select
           __Choices: Danish (da), Dutch (nl), English (en), Esperanto (eo)
           #  You must NOT translate this string, but you can change its value.
           #  The comment between brackets is used to distinguish this msgid
           #  from the one in the Choices list; you do not have to worry about
           #  them, and have to simply choose a msgstr among the English values
           #  listed in the Choices field above, e.g. msgstr "Dutch (nl)"
           _Default: English (en)[ default language]
           _Description: Geneweb default language

         Значение по умолчанию также присутствует в поле Choices, и оба имеют
         различные переводы: первое содержит не переведённое значение,
         выбираемое из Choices, а второе имеет обычный перевод. Так как
         "gettext" не может содержать два различных перевода одного msgid, то
         msgid должны отличаться с помощью комментариев в квадратных скобках,
         как описывалось в предыдущем разделе.

         До версии "po-debconf" 0.8.0, такие комментарии были недоступны и
         сопровождающие заменяли поле _Default: на поле _DefaultChoice:, чтобы
         как-то выделить такие поля в PO-файлах:

           #. DefaultChoice
           msgid ""
           "English[ default: do not translate bracketed material, put your "
           "own language here but UNTRANSLATED.  If it is not in the list, "
           "put English (without bracketed material)]"
           msgstr ""
           "Swedish"

         Простые комментарии менее подвержены ошибкам и приветствуются.

ВЕБ-СТРАНИЦЫ СОСТОЯНИЯ

       Статистика по "po-debconf" переводам доступна здесь
       <http://www.debian.org/intl/l10n/po-debconf/> (или с зеркал); она
       обновляется автоматически при поступлении нового пакета. Сюда попадают
       только пакеты, имеющие файлы debian/po/templates.pot и
       debian/po/POTFILES.in, поэтому вы должны проверить, что ваш пакет с
       исходными текстами содержит их.

       С этой страницы переводчики могут получить PO- и POT-файлы, но они
       всегда должны связаться с предыдущим переводчиком (его почтовый адрес
       можно найти в PO-файле) и/или их коллегами переводчиками через
       debian-l10n-<>@lists.debian.org (если такой список существует),
       чтобы удостовериться, что никто в данный момент не работает над тем же
       переводом, а также изучить имеющиеся сообщения об ошибках пакета,
       который они намереваются переводить, чтобы проверить, что о переводе
       уже не сообщено.

       После перевода этих файлов, они должны быть посланы сопровождающему в
       виде отчёта об ошибке с важностью wishlist и тегом patch.

СМОТРИТЕ ТАКЖЕ

       debconf-gettextize(1), debconf-updatepo(1), dh_installdebconf(1),
       podebconf-report-po(1), po2debconf(1), debconf-devel(7).

АВТОРЫ

         Мартин Квинсон (Martin Quinson) <Martin.Quinson@ens-lyon.fr>
         Дэнис Барбье (Denis Barbier) <barbier@linuxfr.org>

                                  2009-04-29                     PO-DEBCONF(7)