LOCALE::PO4A::PO.3PM(1)

ИМЕ
Locale::Po4a::Po - модул за манипулацију PO фајла

СИНОПСИС
    use Locale::Po4a::Po;
    my $pofile=Locale::Po4a::Po->new();

    # Читање PO фајла
    $pofile->read('фајл.po');

    # Уметање ставке
    $pofile->push('msgid' => 'Hello', 'msgstr' => 'bonjour',
                  'flags' => "wrap", 'reference'=>'file.c:46');

    # Издвајање превода
    $pofile->gettext("Hello"); # враћа 'bonjour'

    # Уписивање назад у фајл
    $pofile->write('другифајл.po');

ОПИС
Locale::Po4a::Po који вам омогућава да манипулишете каталозима порука. Можете да учитате и уписујете у фајл (чија екстензија је обично po), можете у лету да градите нове ставке или да захтевате превод стринга.

За потпунији опис каталога порука у PO формату, као и начин њихове употребе, молимо да погледате info документацију програма gettext (чвор "`PO Files"').

Овај модуле је део пројекта po4a, чији је циљ да се PO фајлови (изворно направљених за олакшавање превода порука неког програма) користе за превођење свега, укључујући и документацију (man страница, 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 стринг
    Поставља власника права умножавања у POT заглавље. Подразумевана вредност је "Free Software Foundation, Inc."

--package-name стринг
    Поставља име пакета у POT заглавље. Подразумевано је "PACKAGE".

--package-version стринг
    Поставља верзију пакета у POT заглавље. Подразумевано је "VERSION".

Функције које се тичу каталога порука у целини

new()
    Креира нови каталог порука. Ако се наведе аргумент, то ће бити име PO фајла који би требало да се учита.

read($)
    Чита PO фајл (чије име је дато аргументом). Претходно постојеће ставке у објекту се не уклањају, нове се додају на крај каталога.

write($)
    Уписује текући каталог у дати фајл.

write_if_needed($$)
    Као write, али у случају да PO или POT фајл већ постоји, објекат ће да се упише у привремени фајл који ће затим да се упореди са постојећим како би се проверило да ли је неопходно ажурирање (на овај начин се избегава измена POT фајла само да би се ажурирала линија референце, или поље POT-Creation-Date).

filter($)
    Ова функција издваја каталог из постојећег. У излазни каталог се смештају само оне ставке које имају референцу у датом фајлу.

    Ова функција парсира свој аргумент, конвертује га у дефиницију Perl функције, одређује вредност ове дефиниције и филтрира поља за коју функција враћа истиниту вредност.

    Понекад волим Perl ;)

to_utf8()
    Поново кодира msgstr стрингове из PO фајла у UTF-8. Не ради ништа у случају да скуп карактера није наведен у PO фајлу (вредност "CHARSET"), или је већ UTF-8 или ASCII.

Функције за коришћење каталога порука у преводима

gettext($%)
    Захтева из текућег каталога превод за стринг који је дат као аргумент. У случају да се превод не пронађе, функција враћа оригинални (непреведени) стринг.

    Након стринга који треба да се преведе, можете да наведете хеш додатних аргумената. Ево важећих ставки:

    wrap
        логичка вредност која указује на то да ли се празни карактери у стрингу сматрају за битне карактере. Ако је тачно, функција канонизује стринг пре тражења превода, и обавија резултат.

    wrapcol
        колона око које се врши обавијање (подразумевано: 76).

stats_get()
    Враћа статистику у вези успешности програма gettext у проналажења превода од тренутка када је последњи пут позвана функција 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 и fuzzy.

        За њихово значење, погледајте gettext документацију.

    type
        ово је углавном интерни аргумент: користи се током gettextизације докумената. Идеја је да се у PO објекат парсирају и оригинал и превод, да се споје у нови каталог користећи msgid једног као msgid, а msgid другог као msgstr. Да би се обезбедило да све буде како треба, сваком msgid у PO објектима се даје тип, заснован на његовој структури (као "chapt", "sect1", "p" и тако даље у DocBook). Ако типови стрингова нису исти, то значи да два фајла немају исту структуру, па процес пријављује грешку.

        Ова информација се у PO фајл уписује као аутоматски коментар јер се на тај начин преводиоцима приказује нешто од контекста у вези стрингова који треба да преведу.

    wrap
        логичка вредност која говори да ли је код козметичких реформатирања дозвољено да се претумбају празни карактери. Ако је истинита, стринг се канонизује пре употребе.

        Ова информација се у 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().

АУТОРИ
 Дени Барбије <barbier@linuxfr.org>
 Мартин Квинсон (mquinson#debian.org)