НАЗВА¶

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

    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');

ОПИС¶

Повний опис каталогів повідомлень у форматі 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($%)

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

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

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

set_charset($)

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

АВТОРИ¶

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