Provided by: po4a_0.55-1_all bug

НАЗВА

       Locale::Po4a::Po — модуль для керування файлами PO

КОРОТКИЙ ОПИС

           use Locale::Po4a::Po;
           my $pofile=Locale::Po4a::Po->new();

           # Прочитати файл PO
           $pofile->read('file.po');

           # Додати запис
           $pofile->push('msgid' => 'Hello', 'msgstr' => 'bonjour',
                         'flags' => "wrap", 'reference'=>'file.c:46');

           # Видобути переклад
           $pofile->gettext("Hello"); # повертає 'bonjour'

           # Записати результат до файла
           $pofile->write('otherfile.po');

ОПИС

       За допомогою модуля Locale::Po4a::Po ви зможете керувати каталогами повідомлень. Ви можете
       завантажити дані з файла і записати їх до файла (суфіксом назви якого є, зазвичай, po), ви
       можете динамічно створювати нові записи або надсилати запити щодо перекладу певного рядка.

       Повний опис каталогів повідомлень у форматі PO та принципів їхнього використання наведено
       у документації info до комплекту програм gettext (вузол «PO Files»).

       Цей модуль є частиною проекту po4a. Метою його створення було використання файлів PO (від
       початку створених для полегшення перекладу інтерфейсу програм) для перекладу будь-чого,
       зокрема документації (сторінок підручника, документації info), описів пакунків, шаблонів
       debconf та будь-чого, що корисно перекладати.

ПАРАМЕТРИ, ЯКІ МОЖНА ПЕРЕДАВАТИ ЦЬОМУ МОДУЛЮ

       --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».

Функції, які стосуються усіх каталогів повідомлень

       new()
           Створює каталог повідомлень. Якщо вказано аргумент, він вважатиметься назвою файла PO,
           який слід завантажити.

       read($)
           Читає файл PO (назва передається як аргумент). Наявні у self записи не вилучаються,
           нові додаються наприкінці каталогу.

       write($)
           Записує поточний каталог до вказаного файла.

       write_if_needed($$)
           Подібна до write, але якщо файл PO або POT вже існує, об'єкт буде записано до
           тимчасового файла, який буде порівняно із наявним файлом з метою визначити, чи
           потрібне оновлення (таким чином, ми уникаємо внесення змін до POT лише для оновлення
           посилань на рядки або поля дати створення POT).

       gettextize($$)
           Ця функція створює один каталог перекладених повідомлень з двох каталогів —
           початкового і перекладу. Процедуру описано у підручнику з po4a(7), розділ Перетворення
           на формат gettextization: як це працює?.

       filter($)
           Ця функція видобуває каталог з наявного файла перекладу. До каталогу-результату буде
           включено лише ті записи, які містять посилання на вказаний файл.

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

           Іноді я люблю Perl ;)

       to_utf8()
           Розкодовує UTF-8 у рядках перекладів (msgstr) PO. Не виконує ніяких дій, якщо
           кодування у файлі PO не вказано кодування (немає значення «CHARSET»), або якщо дані
           вже записано у кодуванні UTF-8, або дані є символами ASCII.

Функції для використання каталогу повідомлень для перекладів

       gettext($%)
           Надсилає запит щодо перекладу рядка, переданого як аргумент, до поточного каталогу
           перекладів. Функція повертає початковий (неперекладений) рядок, якщо рядок не буде
           знайдено у каталозі.

           Після рядка, який слід перекласти, ви можете передати хеш додаткових аргументів. Ось
           коректні записи цих аргументів:

           wrap
               булеве значення, яке вказує на те, чи розглядаєте ви пробіли як неважливу частину
               рядка. Якщо має значення «yes» («так»), функція переводить рядок у канонічну
               форму, перш ніж шукати переклад, а потім виконує перенесення рядків у результаті
               пошуку.

           wrapcol
               позиція, на якій слід переносити рядки (типове значення: 76).

       stats_get()
           Повертає статистичні дані щодо пошуку відповідників з часу останнього виклику
           stats_clear(). Будь ласка, зауважте, що ці статистичні дані — це не ті дані, які
           виводить команда msgfmt --statistic. Це статистичні дані щодо використання файла PO,
           тоді як дані msgfmt — це звіт щодо стану файла. Приклад використання:

               [якесь використання файла PO для перекладу даних]

               ($percent,$hit,$queries) = $pofile->stats_get();
               print "Знайдено переклади для $percent\%  ($hit з $queries) рядків.\n";

       stats_clear()
           Вилучає статистику щодо відповідників gettext.

Функції для збирання каталогу повідомлень

       push(%)
           Дописати запис наприкінці поточного каталогу. Аргументи слід вказувати у форматі
           таблиці хешів. Коректні ключі:

           msgid
               рядок початковою мовою.

           msgstr
               переклад.

           reference
               позначка того, де було знайдено цей рядок. Приклад: file.c:46 (означає «file.c», у
               рядку 46). Може бути списком відокремлених пробілами значень, якщо рядок
               трапляється у декількох місцях.

           comment
               коментар, доданий сюди вручну (перекладачами). Формат є довільним.

           automatic
               коментар, який буде автоматично додано програмою для видобування рядків.
               Докладніший опис можна знайти у розділі щодо параметра --add-comments підручника
               до програми xgettext.

           flags
               список усіх прапорців для цього запису, відокремлених пробілами.

               Коректними прапорцями є такі: c-text, python-text, lisp-text, elisp-text, librep-
               text, smalltalk-text, java-text, awk-text, object-pascal-text, ycp-text, tcl-text,
               wrap, no-wrap and fuzzy.

               Із призначенням прапорців можна ознайомитися у документації з gettext.

           type
               здебільшого внутрішній аргумент: використовується під час перетворення на формат
               gettext даних документів. Ідея полягає у поєднанні оригіналу і перекладу у одному
               об'єкті PO, який використовує один із елементів msgid як msgid, а інший — як
               msgstr. Щоб переконатися, що усе гаразд, кожному msgid в об'єктах PO надається
               тип, який визначається на основі структури документа (наприклад «chapt», «sect1»,
               «p» тощо у DocBook). Якщо типи рядків не однакові, це означає, що структура
               документів є різною, тому процес обробки повідомляє про помилку.

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

           wrap
               булеве значення, яке вказує на те, чи можна нехтувати пробілами при косметичному
               переформатуванні. Якщо має значення true, рядок переводиться до канонічної форми
               перед його використанням.

               Ця інформація записується до файла PO за допомогою прапорця wrap або no-wrap.

           wrapcol
               позиція, на якій слід переносити рядки (типове значення: 76).

               Ця інформація не записується до файла PO.

Різноманітні функції

       count_entries()
           Повертає кількість записів у каталозі (без заголовка).

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

       equals_msgid(po)
           Повертає ($uptodate, $diagnostic), де $uptodate вказує, чи усі msgid у поточному файлі
           po містяться у файлі, який передано як параметр (при порівнянні файлів усі інші поля
           буде проігноровано). Неформально, якщо $uptodate має значення false, файли po буде
           змінено при обробці po4a-updatepo.

           Якщо $uptodate має значення false, параметр $diagnostic містить діагностичні дані щодо
           причин.

       msgid($)
           Повертає msgid із вказаним номером.

       msgid_doc($)
           Повертає msgid із вказаною позицією у документі.

       get_charset()
           Повертає кодування символів, яке вказано у заголовку файла PO. Якщо таке кодування не
           вказано, поверне рядок «CHARSET».

       set_charset($)
           Встановлює для кодування символів у заголовку PO значення, вказане як перший аргумент
           функції. Якщо ви не викликатимете цю функцію (і не читатимете файл із визначеним
           кодуванням символів), типовим значенням залишиться «CHARSET». Це значення не змінює
           поведінки модуля, просто використовується для заповнення поля у заголовку і повернення
           значення у функції get_charset().

АВТОРИ

        Denis Barbier <barbier@linuxfr.org>
        Martin Quinson (mquinson#debian.org)