НАЗВА

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 тип
Вказує формат посилань. Аргумент тип може мати значення never, якщо не слід взагалі створювати посилань; file, якщо слід вказати файл без номерів рядків; counter, якщо слід замінити номер рядка значенням лічильника; і full, якщо посилання слід включити повністю (типове значення: full).
--wrap-po no|newlines|число (типове значення: 76)
Визначає спосіб перенесення рядків у файлі po. Так можна вибрати між файлами із добре перенесеними рядками, які можуть спричиняти конфлікти у git, та файлами, які простіше обробляються автоматично, але є важчими для читання. Так історично склалося, що комплект програм gettext виконує переформатування файлів po так, щоб рядки було перенесено на 77-й позиції, з косметичних міркувань. За допомогою цього параметра можна встановити відповідну поведінку po4a. Якщо встановлено числове значення, po4a переноситиме рядки у файлі po після вказаної позиції і після символів розриву рядка у самих рядках. Якщо встановити значення newlines, po4a розриватиме рядки у msgid і msgstr лише після символів нового рядка у вмісті. Якщо встановити значення no, po4a не переноситиме рядки у файлі po взагалі. Перенесення рядків у коментарях виконується завжди інструментами gettext, які програма використовує на внутрішньому рівні. Зауважте, що цей параметр не стосується того, яким чином переноситимуться рядки у msgid і msgstr, тобто того, у який спосіб до цих рядків додаватимуться символи розриву рядків.
--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).
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()
Повертає кількість записів у документі. Якщо у документі певний рядок зустрічається декілька разів, його буде пораховано декілька разів.
msgid($)
Повертає msgid із вказаним номером.
msgid_doc($)
Повертає msgid із вказаною позицією у документі.
type_doc($)
Повертає тип msgid із заданою позицією у документі. Це, ймовірно, корисно лише для перетворення до формату gettext, і позиція зберігається окремо від {$msgid}{'type'}, оскільки останній запис може бути перезаписано іншим типом, коли $msgid дубльовано в основному документі.
get_charset()
Повертає кодування символів, яке вказано у заголовку файла PO. Якщо таке кодування не вказано, поверне рядок «UTF-8».
set_charset($)
Встановлює для кодування символів у заголовку PO значення, вказане як перший аргумент функції. Якщо ви не викликатимете цю функцію (і не читатимете файл із визначеним кодуванням символів), типовим значенням залишиться «UTF-8». Це значення не змінює поведінки модуля, просто використовується для заповнення поля у заголовку і повернення значення у функції get_charset().

АВТОРИ

 Denis Barbier <[email protected]>
 Martin Quinson (mquinson#debian.org)

Questions & Answers

Helpful answers and articles about Locale::Po4a::Po you may found on these sites:
Stack Overflow Server Fault Super User Unix & Linux Ask Ubuntu Network Engineering DevOps Raspberry Pi Webmasters Google Search