PO4A(1p)

НАЗВА
po4a — оновлення файлів PO і перекладених документів у один прохід

КОРОТКИЙ ОПИС
po4a [параметри] файл_налаштувань

ОПИС
Метою проекту po4a (PO для усього) є спрощення перекладу (та, що ще цікавіше, супровід перекладів) за допомогою інструментів gettext у областях, де такий переклад спочатку не передбачався, зокрема у документації.

Програма po4a корисна, якщо ви хочете уникнути викликів po4a-gettextize(1), po4a-updatepo(1) і po4a-translate(1) у складних Makefile, де у вас декілька файлів для перекладу, різні формати або є потреба у визначенні різних параметрів для різних документів.

Зміст
Цей документ упорядковано так:

  ОПИС

  ВСТУП

  СИНТАКСИС ФАЙЛА НАЛАШТУВАНЬ
Визначення мов шаблона

Визначення шляхів для вхідних даних перекладача

Автовиявлення шляхів і мов

Визначення документів для перекладу

Визначення параметрів для модулів

Визначення альтернативних назв

Режим поділу

  ПАРАМЕТРИ

  ПРИКЛАД

  НЕДОЛІКИ

  ТАКОЖ ПЕРЕГЛЯНЬТЕ

  АВТОРИ

  АВТОРСЬКІ ПРАВА ТА ЛІЦЕНЗУВАННЯ

ВСТУП
Програма po4a є відповідальною за оновлення як файлів PO (для синхронізації їх із початковими документами), так і перекладених документів (для синхронізації їх із файлами PO). Основною метою є спрощення користування po4a без потреби у запам'ятовуванні параметрів командного рядка.

Це також надає вам змогу створювати суміш з документів у різних форматах у одному файлі POT, отже, ви можете обмежитися одним файлом для усього проекту.

Цю поведінку можна імітувати іншими інструментами комплекту po4a (наприклад, за допомогою файлів Makefile), але це доволі складно зробити. Такі складні Makefile важко відтворити для кожного з проектів, де використовується po4a.

Процес обробки можна коротко описати наступним чином. Усі зміни у основному документі буде відтворено у файлах PO, а усі зміни у файлах PO (вручну або у спосіб, описаний на попередньому кроці) буде відтворено у перекладених документах.

Звичайний випадок без визначення pot_in:

 <- поч. файли  ->|<-----результати збирання----->

 додаток ----------------------------------+
                                            |
 основний документ-+---------------------+  |
                   V                     +--+--> переклади
 старі файли PO -+--> оновлені файли PO +
      ^                      |
      |                      V
      +<.....................+
    (оновлені файли PO вручну скопійовано
     до початкового коду наступного
     випуску під час оновлення вручну
     матеріалів для перекладу)

Особливий випадок із зазначенням pot_in:

 <- поч. файли->|<-------результати збирання-------->

 осн. документ------+--------------------------+
                   :                          |
 зовнішня         :    фільтрований |
 програма========X..> основний          |
 фільтрування         документ              |
                        |                     |
                        V                     +--> переклади
 старі файли PO----+--> оновлені файли PO +
      ^                           |
      |                           V
      +<..........................+
    (оновлені файли PO вручну копіюють
     до початкового коду наступного
     випуску під час оновлення даних
     перекладу вручну)

Цей інструмент не дає змоги обернути процес обробки, отже, зміни у перекладах буде перезаписано вмістом файлів PO. Фактично, цей інструмент не можна використовувати для перетворення наявних перекладів до системи po4a. Для цього завдання, будь ласка, скористайтеся po4a-gettextize(1).

СИНТАКСИС ФАЙЛА НАЛАШТУВАНЬ
Обов'язковим аргументом є шлях до файла налаштувань, яким слід скористатися. Його синтаксис розроблено простим і близьким до файлів налаштувань, які використовуються у проектах intl-tools.

Коментарі у цих файлах позначаються символом «#». Цей символ робить коментарем усі дані до кінця рядка. Рядки можна продовжувати екрануванням кінця рядка. Усі непорожні ярдки мають починатися з команди [], за якою має бути вказано аргументи команди (здається складним, але насправді, я сподіваюся, усе просто ;)

  Визначення мов шаблона
Зауваження: рекомендуємо користуватися [po_directory], а не [po4a_langs] або [po4a_paths]. Див. розділ Автовиявлення шляхів і мов нижче.

Це необов'язкова команда, яка спрощує увесь файл налаштувань і робить його придатнішим для масштабування. Вам слід вказати список мов, якими ви хочете перекладати документи. Це доволі просто, ось так:

 [po4a_langs] fr de

Це уможливлює для вас розгортання $lang до списку усіх вказаних мов у решті файла налаштувань.

  Визначення шляхів для вхідних даних перекладача
Зауваження: рекомендуємо користуватися [po_directory], а не [po4a_langs] або [po4a_paths]. Див. розділ Автовиявлення шляхів і мов нижче.

По-перше, вам слід вказати, де зберігаються створені перекладачами файли (тобто файли, якими перекладачі користуються для виконання перекладу). Зробити це можна за допомогою такого рядка:

 [po4a_paths] doc/l10n/project.doc.pot \
              fr:doc/l10n/fr.po de:doc/l10n/de.po

Командою, таким чином, є [po4a_paths]. Першим аргументом є шлях до файла POT, яким слід скористатися. Усі наступні аргументи мають зрозумілу форму:

    <мова>:<шлях до файла PO для цієї мови>

Якщо вами було визначено мови шаблонів, ви можете переписати наведений вище рядок у такий спосіб:

 [po4a_paths] doc/l10n/project.doc.pot $lang:doc/l10n/$lang.po

Ви також можете використовувати змінну $master для посилання на назву основного документа. У цьому випадку po4a використовуватиме режим поділу: один POT і один PO (для кожної мови) буде створено для кожного з документів, вказаних у файлі налаштувань po4a. Див. розділ Режим поділу.

 [po4a_paths] doc/$master/$master.pot $lang:doc/$master/$lang.po

  Автовиявлення шляхів і мов
Іншою командою можна скористатися для того, щоб вказати назву каталогу, де зберігаються файли PO і POT. Якщо використано цю команду, po4a виявить файл POT як єдиний файл *.pot з вказаного каталогу. Крім того, po4a використовуватиме список файлів *.po для визначення списку мов (вилучаючи з назв файлів суфікс). Ці мови буде використано для заміни змінної $lang у решті файла налаштувань.

Цю команду не слід використовувати разом з командою [po4a_langs] або [po4a_paths].

Якщо ви користуєтеся цією командою, вам слід створити порожній файл POT під час першого запуску po4a, щоб повідомити програмі назву файла POT.

 [po_directory] po4a/po/

  Визначення документів для перекладу
Тепер, ви, природно, маєте вказати, які документи перекладаються, їхній формат, та визначити, куди слід записувати перекладені документи. Зробити це можна за допомогою таких рядків:

 [type: sgml] doc/my_stuff.sgml fr:doc/fr/mon_truc.sgml \
              de:doc/de/mein_kram.sgml
 [type: pod] script fr:doc/fr/script.1 de:doc/de/script.1 \
             add_fr:doc/l10n/script.fr.add
 [type: docbook] doc/script.xml fr:doc/fr/script.xml \
             de:doc/de/script.xml \
             pot_in:doc/script.filtered.xml

Ця частина також майже очевидна. Зауважте, що у другому випадку doc/l10n/script.fr.add є додатком для додавання французької версії цього документа. Будь ласка, зверніться до підручника з po4a(7), щоб дізнатися більше про додатки.

Формальніше, формат є таким:

 [type: <формат>] <основний документ> (<мова>:<перекладений документ>)* \
                  (pot_in:<фільтрований основний документ>)? \
                  (add_<мова>:<модифікатор>*<шлях до додатка>)*

Якщо вказано pot_in, для створення файла POT використовується фільтрнований основний документ замість файла основний документ. За допомогою цієї можливості розширюється діапазон способів виключення даних, які не слід додавати до файлів PO. Для створення зовнішньої програми фільтрування можна скористатися препроцесором C (cpp) або інструментом перетворення на основі XSL (наприклад, xsltproc). Цю програму фільтрування слід викликати до виклику po4a.

Якщо не буде вказано модифікатора, значенням параметра шлях_до_додатка буде шлях до додатка. Можливі модифікатори:

?   Включити шлях_до_додатка, якщо цей файл існує, інакше, не робити нічого.

@   шлях_до_додатків не є звичайним файлом додатка, а є файлом, що містить список додатків, по одному на рядок. Перед записом кожного з додатків може бути вказано модифікатори.

!   шлях_до_додатків відкидається, він не завантажується, його не буде завантажено будь-якою подальшою специфікацією додатків.

Якщо вами було визначено мови шаблонів, ви можете переписати наведений вище рядок у такий спосіб:

 [type: pod] script $lang:doc/$lang/script.1 \
             add_fr:doc/l10n/script.fr.add

Якщо для всіх мов шляхи до додатків подібні, ви можете написати ось так:

 [type: pod] script $lang:doc/$lang/script.1 \
             add_$lang:doc/l10n/script.$lang.add

  Визначення параметрів для модулів
po4a приймає параметри, які буде передано модулю обробки. Ці параметри специфічні для кожного з модулів і визначаються за допомогою перемикача -o.

Якщо вам потрібен специфічний параметр для одного з документів, які ви хочете перекласти, ви також можете вказати його у файлі налаштувань. Параметри впроваджуються за допомогою ключового слова opt. Аргумент ключового слова opt слід брати у подвійні лапки, якщо у ньому міститься пробіл (наприклад, якщо ви вказуєте декілька параметрів або параметр з аргументом). Ви також можете вказати параметри, які стосуються лише певної мови, за допомогою ключового слова opt_мова.

Ось приклад:
 [type:man] t-05-config/test02_man.1 $lang:tmp/test02_man.$lang.1 \
            opt:"-k 75" opt_it:"-L UTF-8" opt_fr:-v

У аргументах можуть містити пробіли, якщо ви скористаєтеся одинарними або екранованими подвійними лапками:
 [po4a_alias:man] man opt:"-o \"mdoc=NAME,SEE ALSO\" -k 20"

Якщо ви хочете вказати однакові параметри для багатьох документів, ви можете скористатися альтернативною назвою (див. розділ Визначення альтернативних назв нижче).

Ви також можете встановити параметри для усіх документів, вказаних у файлі налаштувань:
 [options] opt:"..." opt_fr:"..."

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

 [po4a_alias:test] man opt:"-k 21" opt_es:"-o debug=splitargs"

Цей код визначає альтернативну назву модуля test, заснованого на модулі man, із параметром -k 21, який застосовується до усіх мов, і параметром -o debug=splitargs, який застосовується для перекладу іспанською.

Ця альтернативна назва модуля надалі може використовуватися як звичайний модуль:

 [type:test] t-05-config/test02_man.1 $lang:tmp/test02_man.$lang.1 \
            opt_it:"-L UTF-8" opt_fr:-v

Зауважте, що ви можете визначати додаткові параметри для окремих файлів.

  Режим поділу
Режим поділу використовується, якщо $master використано у рядку [po4a_paths].

Якщо використовується режим поділу, використовуються тимчасовий великий файл POT і тимчасові великі файли PO. Це надає змогу спільного використання перекладів для усіх файлів PO.

Якщо буде виявлено два файли PO із різними перекладами одного і того самого рядка, po4a позначить переклад рядка як неточний і надішле обидва переклади до усіх файлів PO, які містять цей рядок. Далі, коли перекладач оновлюватиме переклад і вилучить позначку неточного перекладу у одному з файлів PO, переклад цього рядка буде оновлено у всіх інших файлах PO автоматично.

Якщо існуватимуть конфлікти назв, пов'язані із тим, що декілька з файлів матимуть однакові назви, назву основного файла можна вказати за допомогою параметра "master:file="назва:

 [po4a_langs] de fr ja
 [po4a_paths] l10n/po/$master.pot $lang:l10n/po/$master.$lang.po
 [type: xml] foo/gui.xml $lang:foo/gui.$lang.xml master:file=foo-gui
 [type: xml] bar/gui.xml $lang:bar/gui.$lang.xml master:file=bar-gui

ПАРАМЕТРИ

-k, --keep
    Мінімальне порогове значення частки перекладених рядків у відсотках, щоб файл результат було збережено, тобто записано (типове значення: 80). Інакше кажучи, типово, щоб файл було записано, його має бути перекладено принаймні на 80%.

-h, --help
    Показати коротке довідкове повідомлення.

-M, --master-charset
    Кодування файлів, які містять документи для перекладу. Зауважте, що у поточній версії усі основні документи мають зберігатися у одному кодуванні. Це відоме обмеження, яке ми намагаємося усунути.

-L, --localized-charset
    Кодування файлів, у яких містяться дані перекладених документів. Зауважте, що у поточній версії дані усізх перекладених документів мають зберігатися у одному кодуванні. Це відоме обмеження, над усуванням якого ми працюємо.

-A, --addendum-charset
    Кодування для додатків. Зауважте, що дані усіх додатків мають зберігатися у одному кодуванні.

-V, --version
    Вивести дані щодо версії скрипту і завершити роботу.

-v, --verbose
    Збільшити докладність повідомлень програми.

-q, --quiet
    Зменшити докладність повідомлень програми.

-d, --debug
    Вивести деякі діагностичні відомості.

-o, --option
    Додаткові параметри, які слід передати додатку форматування. Кожен параметр слід вказувати у форматі назва=значення. Докладніші відомості щодо параметрів кожного з додатків можна знайти у документації до відповідного додатка.

-f, --force
    Завжди створювати файли POT і PO, навіть якщо po4a це видається непотрібним.

    Типова поведінка (якщо не вказано --force) така:

        Якщо файл POT вже існує, його буде повторно створено, якщо момент часу внесення змін до основного документа або файла налаштувань є новішим за момент часу внесення змін до файла POT. Крім того, файл POT буде записано до тимчасового документа, за яким po4a визначить, чи справді слід вносити якісь зміни до файла.

        Крім того, перекладений документ буде повторно створено, лише якщо його основний документ, файл PO, один із додатків або файл налаштувань виявиться актуальнішим. Щоб запобігти спробам повторного створення перекладених документів, які не проходять перевірки на порогове значення перекладів (див. --keep), буде створено файл із суфіксом назви .po4a-stamp (див. --stamp).

    Якщо до основного документа включаються додаткові файли, вам слід скористатися прапорцем --force, інакше час внесення змін до цих включених файлів не буде враховано.

    Файли PO завжди повторно створюються на основі файла POT за допомогою msgmerge -U.

--stamp
    Наказати po4a створити файли штампів, якщо перекладений документ не створено через те, що його переклад не досяг порогового значення. Назви цих файлів штампів будуть відповідати назвам очікуваних перекладених документів із додаванням суфікса .po4a-stamp.

    Зауваження: цей параметр вмикає лише створення файлів .po4a-stamp. Програма завжди використовуватиме файли штампів, якщо вони існують, їх буде вилучено, лише якщо вказано параметр --rm-translations або переклад файла буде завершено.

--no-translations
    Не створювати перекладених документів, лише оновити файли POT і PO.

--no-update
    Не змінювати файли POT і PO, лише оновити, якщо можливо, перекладені документи.

--keep-translations
    Зберегти файли наявного перекладу, якщо не досягнуто порогового значення, вказаного за допомогою --keep. При цьому не буде створено нових файлів із недостатнім рівнем перекладу, натомість буде збережено застарілі файли, рівень достовірності перекладу у яких впаде через зміни у основних файлах.

    УВАГА: цей прапорець змінює поведінку po4a у доволі критичний спосіб: файли перекладу не оновлюватимуться, аж доки не буде поліпшено переклад. Використовуйте цей прапорець, лише якщо ви надаєте перевагу розповсюдженню застарілої перекладеної документації перед розповсюдженням точної, але не перекладеної документації.

--rm-translations
    Вилучити перекладені файли (із неявним додаванням --no-translations).

--no-backups
    Цей прапорець не діє з версії 0.41, його може бути вилучено у наступних випусках.

--rm-backups
    Цей прапорець не діє з версії 0.41, його може бути вилучено у наступних випусках.

--translate-only перекладений-файл
    Перекласти лише вказаний файл. Може бути корисним для пришвидшення обробки файла налаштувань, якщо у файлі налаштувань міститься багато файлів. Зауважте, що використання цього параметра не призведе до оновлення файлів PO і POT. Цей параметр можна використовувати декілька разів у одній команді.

--variable змінна=значення
    Визначити змінну, яку буде розгорнуто у файлі налаштувань po4a. Усі випадки використання змінної $(змінна) буде замінено на значення. Цей параметр можна використовувати декілька разів у одній команді.

--srcdir КАТАЛОГ_ПОЧАТКОВИХ_ДАНИХ
    Встановити базовий каталог для усіх вхідних документів, які вказано у файлі налаштувань po4a.

--destdir КАТАЛОГ_ПРИЗНАЧЕННЯ
    Встановити базовий каталог для усіх виведених документів, які вказано у файлі налаштувань po4a.

  ПАРАМЕТРИ ДЛЯ ВНЕСЕННЯ ЗМІН ДО ЗАГОЛОВКА POT

--porefs тип[,wrap|nowrap]
    Вказує формат посилань. Аргумент тип може мати значення never, якщо не слід взагалі створювати посилань; file, якщо слід вказати файл без номерів рядків; counter, якщо слід замінити номер рядка значенням лічильника; і full, якщо посилання слід включити повністю (типове значення: full).

    За аргументом можна вказати кому і ключове слово wrap або nowrap. Посилання типово записуються в один рядок. Використання ключового слова wrap призведе до перенесення рядків у посиланнях з метою імітувати поведінку інструментів gettext (xgettext і msgmerge). Цей варіант стане типовим у майбутньому випуску, оскільки його використання має більше сенсу. Варіант nowrap лишиться доступним для користувачів, які хочуть зберегти поведінку попередніх версій програми.

--msgid-bugs-address адреса@електронної.пошти
    Встановити адресу для звітування щодо помилок у msgid (початкових неперекладених рядках). Типово, у створених файлах POT не буде полів Report-Msgid-Bugs-To.

--copyright-holder рядок
    Встановити запис авторських прав у заголовку POTr. Типовим значенням є «Free Software Foundation, Inc.»

--package-name рядок
    Встановити назву пакунка для заголовка POT. Типовою є назва пакунка «PACKAGE».

--package-version рядок
    Встановити версію пакунка для заголовка POT. Типовим є запис «VERSION».

  ПАРАМЕТРИ ДЛЯ ВНЕСЕННЯ ЗМІН ДО ФАЙЛІВ PO

--msgmerge-opt параметри
    Додаткові параметри для msgmerge(1).

    Зауваження: $lang буде розгорнуто до запису поточної мови.

--no-previous
    Цей параметр вилучає --previous з параметрів, які передаються msgmerge. За його допомогою реалізовано підтримку версій gettext до 0.16.

--previous
    Цей параметр додає --previous до параметрів, які передаються msgmerge. Щоб ним можна було скористатися, у системі має бути встановлено gettext 0.16 або новішу версію. Цей параметр типово задіяно.

  ПРИКЛАД
Припустімо, ви є супровідником програми із назвою foo, сторінкою підручника якої є man/foo.1. Актуальний стан, звичайно ж, підтримується лише для англійського варіанта цієї сторінки. Тепер, ви, як супровідник основної версії або пакунків з програмою, хочете створити і супроводжувати переклад. По-перше, вам слід створити файл POT, який ви надішлете перекладачам, за допомогою po4a-gettextize(1).

Отже, у нашому прикладі слід віддати команду

 cd man && po4a-gettextize -f man -m foo.1 -p foo.pot

Далі, цей файл слід надіслати до відповідних списків листування перекладачів або запропонувати отримувати його з якоїсь адреси на вашому сайті.

Далі, припустімо, що ви отримали три переклади перед наступним випуском програми: de.po (з додатком de.add), sv.po та pt.po. Оскільки ви не хочете вносити зміни до ваших файлів Makefile кожного разу, коли з'являється новий переклад, ви можете скористатися po4a з відповідним файлом налаштувань у вашому Makefile. Нехай файл налаштувань має назву po4a.cfg. У нашому прикладі його вміст буде таким:

 [po_directory] man/po4a/po/

 [type: man] man/foo.1 $lang:man/translated/$lang/foo.1 \
            add_$lang:?man/po4a/add_$lang/$lang.add opt:"-k 80"

У цьому прикладі ми припускали, що ваші створені сторінки підручника (і усі файли PO і додатків) мають зберігатися у man/translated/$lang/ (відповідно у man/po4a/po/ і man/po4a/add_$lang/) у поточному каталозі. У нашому прикладі каталог man/po4a/po/ міститиме de.po, pt.po і sv.po, а каталог man/po4a/add_de/ міститиме de.add.

Зверніть увагу на використання модифікатора ?, оскільки лише переклад німецькою (de.po) супроводжується додатком.

Для збирання самих перекладених сторінок підручника вам слід (лише одного разу!) додати такий рядок до цілі build відповідного файла Makefile:

        po4a po4a.cfg

Щойно усе буде налаштовано, вам не доведеться знову редагувати Makefile, якщо з'явиться новий переклад, тобто, якщо, наприклад, перекладачі французькою надішлють вам fr.po і fr.add, ви просто запишете відповідні файли до man/po4a/po/ і man/po4a/add_fr/, і під час наступного збирання програми переклад французькою буде автоматично зібрано до man/translated/fr/.

Зауважте, що відповідну ціль для встановлення перекладених сторінок підручника разом із англійськими все ж доведеться створити окремо.

Нарешті, якщо ви не зберігаєте створені файли у вашій системі керування версіями, вам потрібен буде рядок і у вашій цілі clean:
        -rm -rf man/translated

НЕДОЛІКИ

•   Дублює частину коду програм po4a-*.

Будемо раді латкам ;)

ТАКОЖ ПЕРЕГЛЯНЬТЕ
po4a-gettextize(1), po4a-normalize(1), po4a-translate(1), po4a-updatepo(1), po4a(7)

АВТОРИ
 Denis Barbier <barbier@linuxfr.org>
 Nicolas François <nicolas.francois@centraliens.net>
 Martin Quinson (mquinson#debian.org)

АВТОРСЬКІ ПРАВА ТА ЛІЦЕНЗУВАННЯ
© SPI, inc., 2002–2012

Ця програма є вільним програмним забезпеченням; ви можете поширювати її і/або вносити до неї зміни за умов дотримання GPL (див. файл COPYING).