НАЗВА¶

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

gettextize($$)

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

filter($)

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

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

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

to_utf8()

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

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

gettext($%)

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

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

stats_get()

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

    [якесь використання файла PO для перекладу даних]
    ($percent,$hit,$queries) = $pofile->stats_get();
    print "Знайдено переклади для $percent\%  ($hit з $queries) рядків.\n";
    

stats_clear()

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

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

push(%)

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

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

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. Якщо таке кодування не вказано, поверне рядок «UTF-8».

set_charset($)

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

АВТОРИ¶

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