ОПИС

ВСТУП

СИНТАКСИС ФАЙЛА НАЛАШТУВАНЬ

Визначення мов шаблона

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

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

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

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

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

Режим поділу

ПАРАМЕТРИ

ПРИКЛАД

НЕДОЛІКИ

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

АВТОРИ

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

Визначення мов шаблона

Зауваження: рекомендуємо користуватися [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

ПАРАМЕТРИ ДЛЯ ВНЕСЕННЯ ЗМІН ДО ЗАГОЛОВКА 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