PO4A(1p)

ИМЕ
po4a - у једном кораку ажурира и PO фајлове и преведене документе

СИНОПСИС
po4a [опције] конфиг_фајл

ОПИС
po4a (PO for anything [PO за било шта]) олакшава одржавање превода докумената употребом класичних gettext алата. Главна особина po4a је да раскида везу између садржаја превода и структуре његовог документа. Молимо да погледате страницу po4a(7) у којој је изложен прости увод у овај пројекат.

Када по први пут покренете програм po4a, само са конфигурационим фајлом и документима који треба да се преведу (такозваним мастер документима), он ће креирати POT фајл (који се такође зове и шаблон превода) који садржи све преводиве стрингове у документу дате у облику који преводиоцима олакшава рад.

Ови POT фајлови могу или да се преведу одређеним едитором као што је GNOME Translation Editor, KDE-ов Lokalize или poedit, или могу да се интегришу у платформу за локализацију на мрежи као што су weblate или pootle. Резултат превода је скуп PO фајлова, по један за сваки језик.

Када програм po4a покренете заједно са мастер документима и са PO фајловима, он креира преведене документе уметањем превода садржаја (који се проналази у PO фајловима) у структуру оригиналног мастер документа.

Ако су се у међувремену мастер документи изменили, po4a ће сагласно са тим да измени PO и POT фајлове, тако да преводиоци једноставно могу да открију измене и ажурирају свој рад. У зависности од ваших подешавања po4a ће или да одбаци делимично преведене документе, или ће да направи документ мешајући енглески (за нове или измењене пасусе) и циљни језик (за пасусе за које у PO фајлу већ постоји превод).

Подразумевано се преведени документи израђују онда када је барем 80% њиховог садржаја преведено (погледајте опцију --keep испод). Одбацивање превода чим проценат преведених стрингова није 100% може да буде обесхрабрујуће за преводиоце, док приказивање „превода” који је далеко од завршеног може да представља проблем за крајње кориснике.

  Графички преглед
 мастер документи ------+-------->-------->---------+
  (писање док)          |                           |
                        V       (po4a извршавања)   >-----+--> преводи
                        |                           |     |
 постојећи PO фајлови -->--> ажурирани PO фајлови >-+     |
      ^                                 |                 |
      |                                 V                 |
      +----------<---------<------------+                 ^
          (ручни процес превођења)                        |
                                                          |
 додатак -->----------------------------------------------+

Мастер документе креирају писци документације. Програм po4a било какве измене у њима аутоматски рефлектује у PO фајлове, које преводиоци затим ажурирају. Све измене у PO фајловима (било ручне, било оне које направи po4a), аутоматски се рефлектују у преведена документа. Овај процес можете да опонашате употребом po4a-updatepo(1) и po4a-translate(1) скрипти у makefiles, али то брзо постаје незграпно и понављајуће (погледајте po4a(7)). Стога се топло препоручује да у свом процесу изградње користите програм po4a.

ОПЦИЈЕ

-k, --keep
    Најмањи ниво преведености који је потребан да се резултујући фајл задржи (тј. запише) (подразумевано: 80). То значи да је подразумевано потребно да барем 80% неког фајла буде преведено како би се његов превод записао на диск.

-h, --help
    Приказује кратку поруку помоћи.

-M, --master-charset
    Скуп карактера којим су записани фајлови који садрже документе за превод. Имајте на уму да сви мастер документи морају да користе исти скуп карактера.

-L, --localized-charset
    Скуп карактера који користе фајлови локализованих докумената. Имајте на уму да ће сви преведени документи користити исти скуп карактера.

-A, --addendum-charset
    Скуп карактера додатка. Имајте на уму да би сви додаци требало да буду записани употребом истог скупа карактера.

-V, --version
    Приказује верзију скрипте и завршава извршавање.

-v, --verbose
    Увећава детаљност извештавања програма.

-q, --quiet
    Умањује детаљност извештавања програма.

-d, --debug
    Исписује неке информације битне за отклањање грешака.

-o, --option
    Додатна опција (или више њих) које се прослеђују додатку формата. Погледајте документацију сваког од додатака да сазнате више информација о важећим опцијама и њиховом значењу. На пример, AsciiDoc парсеру бисте могли да проследите '-o tablecells', док би текст парсер прихватио '-o tabs=split'.

-f, --force
    POT и PO фајлови се увек генеришу, чак и у случају када po4a сматра да то није неопходно.

    Подразумевано понашање (када није наведено --force) је као што следи:

        У случају да POT фајл већ постоји, он се регенерише из мастер документа или ако је конфигурациони фајл новији (само ако није наведено --no-update). POT фајл се такође уписује у привремени документ и po4a проверава да ли су измене заиста неопходне.

        Такође, превод се регенерише само у случају када је његов мастер документ, PO фајл, један од његових додатака или конфигурациони фајл новији. Како би се спречио покушај регенерације превода који не пролазе тест потребног минималног процента завршетка (погледајте --keep), може да се креира фајл са .po4a-stamp екстензијом (погледајте --stamp).

    У случају да мастер документ укључује фајлове, требало би да користите заставицу --force јер се време модификације ових фајлова не узима обзир.

    PO фајлови се увек регенеришу сагласно POT фајлу са msgmerge -U.

--stamp
    Наводи po4a да креира печат фајлове у случају да се превод не генерише јер проценат завршености није прешао задату границу. Ови печат фајлови се именују сагласно са очекиваним преведеним документом, и имају .po4a-stamp екстензију.

    Напомена: ово само активира креирање .po4a-stamp фајлова. Печат фајлови се увек користе ако постоје, и могу да се обришу помоћу --rm-translations или када се фајл комплетно преведе.

--no-translations
    Не генеришу се преведени документи, само се ажурирају POT и PO фајлови.

--no-update
    POT и PO фајлови се не мењају, могуће је само да се ажурира превод.

--keep-translations
    Задржава постојеће фајлове превода чак и у случају када превод не задовољава критеријум задат са --keep. Ова опција не креира нове фајлове превода са мало садржаја, али ће да сачува постојеће преводе који постају застарели услед измена над мастер фајловима.

    УПОЗОРЕЊЕ: ова заставица на прилично драстичан начин мења понашање програма po4a: ваши преведени фајлови се уопште неће ажурирати све док се превод не побољша. Користите ову заставицу само у случају да вам више одговара да достављате застарели превод документације него да достављате прецизну али непреведену документацију.

--rm-translations
    Уклања преведене фајлове (имплицира --no-translations).

--no-backups
    Ова заставица нема никакву функцију почевши од верзије 0.41, и може бити уклоњена у наредним издањима програма.

--rm-backups
    Ова заставица нема никакву функцију почевши од верзије 0.41, и може бити уклоњена у наредним издањима програма.

--translate-only преведени-фајл
    Преводи само наведени фајл. Може да буде корисно за убрзавање обраде у случају када конфигурациони фајл садржи доста фајлова. Имајте на уму да ова опција не ажурира PO и POT фајлове. Ова опција може да се употреби више пута.

--variable пром=вредност
    Дефинише променљиву која ће да се развије у po4a конфигурационом фајлу. Свако појављивање $(пром) ће да се замени са вредност. Ова опција може да се користи више пута.

--srcdir ИЗВОРНИДИР
    Поставља базни директоријум за све улазне документе наведене у po4a конфигурационом фајлу.

    Ако су наведени и циљнидир и изворнидир, улазни фајлови се траже у следећим директоријумима, према редоследу: циљнидир, текући директоријум и изворнидир. Излазни фајлови се записују у циљнидир ако је наведен, или у текући директоријум.

--destdir ЦИЉНИДИР
    Поставља базни директоријум за све излазне документе наведене у po4a конфигурационом фајлу (погледајте --srcdir изнад).

  Опције које мењају POT заглавље

--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 обавијају, тј. на то како се додају преломи линија у садржај ових стрингова.

--master-language
    Језик изворних фајлова који садрже документе који се преводе. Водите рачуна да сви мастер документи морају да буду написани истим језиком.

--msgid-bugs-address имејл@адреса
    Поставља адресу за пријаву msgid багова. Подразумевано, креирани POT немају Report-Msgid-Bugs-To поља.

--copyright-holder стринг
    Поставља власника права умножавања у POT заглавље. Подразумевана вредност је "Free Software Foundation, Inc."

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

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

  Опције за измену PO фајлова

--msgmerge-opt опције
    Додатне опције за msgmerge(1).

    Напомена: $lang ће да се развије у текући језик.

--no-previous
    Ова опција уклања --previous из опција које се прослеђују програму msgmerge. Тиме се дозвољава подршка за верзије програма gettext старије од 0.16.

--previous
    Ова опција додаје --previous опцијама које се прослеђују програму msgmerge. Захтева да је верзија програма gettext 0.16 или каснија, и подразумевано је активирана.

КОНФИГУРАЦИОНИ ФАЈЛ
Програм po4a очекује конфигурациони фајл као свој аргумент. Овај фајл мора да садржи следеће елементе:

•   Путању до PO фајлова и листу језика који постоје у пројекту;

•   Необавезно, неке глобалне опције и такозване конфигурационе алијасе који се користе као шаблони за конфигурисање појединачних мастер фајлова;

•   Листу сваког од мастер фајлова који се преводи, заједно са специфичним параметрима.

Све линије садрже команду унутар великих заграда, иза које следе њени параметри. Коментари почињу карактером '#' и протежу се до краја линије. Можете да означите крај линије како бисте развукли команду на неколико линија.

  Проналажење PO и POT фајлова
Најједноставније решење је да се зада путања до директоријума који садржи ваш пројекат превода као што следи.

 [po_directory] man/po/

Наведени директоријум мора да садржи скуп PO фајлова, сваки назван XX.po где је "XX" ISO 639-1 језика који се користи у том фајлу. Директоријум такође мора да садржи један POT фајл, са ".pot" екстензијом фајла.

Ако вам више одговара, исте информације можете да наведете експлицитно, као што следи:

 [po4a_paths] man/po/project.pot de:man/po/de.po fr:man/po/fr.po

Ово најпре наводи путању до POT фајла, а затим путање до немачких и француских PO фајлова.

Коначно, исте информације могу да се запишу на следећи начин:

 [po4a_langs] fr de
 [po4a_paths] man/po/project.pot $lang:man/po/$lang.po

$lang компонента се аутоматски развија помоћу наведене листе језика, чиме се смањује ризик грешке при копирању/налепљивању онда када се додаје нови језик.

Централизовани или подељени PO фајлови?

Програм po4a подразумевано креира један јединствени PO фајл за сваки циљни језик, који садржи комплетан садржај вашег пројекта превода. Како ваш пројекат расте, величина ових фајлова може да постане проблематична. Када се користи веблејт, могуће је да се наведу приоритети за сваки сегмент превода (тј. msgid) тако да се прво преведу они битнији. Ипак, неки преводилачки тимови радије деле садржај на неколико фајлова.

Ако желите да имате један PO фајл за сваки мастер фајл, потребно је само да користите стринг $master у имену ваших PO фајлова у "[po4a_paths]" линији, као што следи.

 [po4a_paths] doc/$master/$master.pot $lang:doc/$master/$lang.po

Ако постоји конфликт са именима јер више фајлова имају исто име, име мастер фајла може да се наведе додавањем опције "master:file="име:

 [po4a_langs] de fr ja
 [po4a_paths] l10n/po/$master.pot $lang:l10n/po/$master.$lang.po
 [type: xml] foo/gui.xml $lang:foo/gui.$lang.xml master:file=foo-gui
 [type: xml] bar/gui.xml $lang:bar/gui.$lang.xml master:file=bar-gui

У подељеном режиму, програм po4a креира привремени компендијум током ажурирања PO фајлова, како би се делили преводи из свих PO фајлова. Ако два PO files фајла имају различите преводе за исти стринг, програм po4a ће да означи стринг као fuzzy и поставиће оба превода у све PO фајлове који садрже тај стринг. Када преводилац уклони fuzzy ознаку и изабере један од превода, тај превод се аутоматски користи у сваком PO фајлу.

  Навођење фокумената за превођење
Такође морате да наведете листу докумената који треба да се преведу. За сваки мастер фајл морате да наведете који парсер формата ће да се користи, локацију произведеног преведеног документа, и необавезно, нека подешавања. Ево примера:

 [type: sgml] doc/my_stuff.sgml fr:doc/fr/mon_truc.sgml \
              de:doc/de/mein_kram.sgml
 [type: man] script fr:doc/fr/script.1 de:doc/de/script.1
 [type: docbook] doc/script.xml fr:doc/fr/script.xml \
             de:doc/de/script.xml

Али опет, читање и измена ових компликованих линија није једноставна, нпр. када се додаје нови језик. Много је једноставније да се ствари реорганизују употребом $lang шаблона као што следи:

 [type: sgml]    doc/my_stuff.sgml $lang:doc/$lang/my_stuff.sgml
 [type: man]     script.1          $lang:po/$lang/script.1
 [type: docbook] doc/script.xml    $lang:doc/$lang/script.xml

  Навођење опција
Постоје два типа опција: po4a опције су подразумеване вредности за опције командне линије програма po4a док се формат опције користе за промену понашања парсера формата. Као po4a опције бисте могли на пример да у свом конфигурационом фајлу наведете да је подразумевана вредност параметра командне линије --keep 50% уместо 80%. Формат опције су документоване на одређеној страници сваког модула за парсирање, нпр. Locale::Po4a::Xml(3pm). На пример, могли бисте да XML парсеру проследите nostrip како не би уклонио размаке око стрингова које пронађе.

Ове опције можете да проследите одређеном мастер фајлу, или чак одређеном преводу тог фајла употребом "opt:" и "opt_XX:" за језик "XX". У наредном примеру, опција nostrip се прослеђује XML парсеру (за све језике), док се граница за француски превод спушта на 0% (дакле, увек се задржава).

 [type:xml] toto.xml $lang:toto.$lang.xml opt:"-o nostrip" opt_fr:"--keep 0"

У сваком случају, ови сегменти конфигурације морају да се нађу на крају линије. Најпре мора да дође декларација фајлова, затим додатак ако постоји (погледајте испод), па тек онда опције. Груписање сегмената конфигурације није толико битно, јер се интерно елементи спајају као стрингови. Следећи примери су сви еквивалентни међусобно:

  [type:xml] toto.xml $lang:toto.$lang.xml opt:"--keep 20" opt:"-o nostrip" opt_fr:"--keep 0"
  [type:xml] toto.xml $lang:toto.$lang.xml opt:"--keep 20 -o nostrip" opt_fr:"--keep 0"
  [type:xml] toto.xml $lang:toto.$lang.xml opt:--keep opt:20 opt:-o opt:nostrip opt_fr:--keep opt_fr:0

Имајте на уму да се опције специфичне за језик не користе када се изграђује POT фајл. Тако је, на пример, немогуће да се nostrip проследи парсеру само када се изграђује француски превод, јер се исти POT фајл користи за ажурирање сваког језика. Дакле, једине опције које могу да буду специфичне за језик су оне које се користе када се прави превод, као што је опција "--keep".

Конфигурациони алијаси

Када желите да се исте опције проследе већем броју фајлова, најбоље је да дефинишете алијас типа, на начин како је објашњено у наставку. У следећем примеру, "--keep 0" се прослеђује сваком италијанском преводу употребом типа "test", који је проширење типа "man".

  [po4a_alias:test] man opt_it:"--keep 0"
  [type: test] man/page.1 $lang:man/$lang/page.1

Постојећи тип такође можете да проширите поновним коришћењем истог имена за алијас, као што следи. То се не интерпретира као погрешна рекурзивна дефиниција.

  [po4a_alias:man] man opt_it:"--keep 0"
  [type: man] man/page.1 $lang:man/$lang/page.1

Глобалне подразумеване опције

"[options]" линије можете такође да употребите за дефинисање опција које морају да се користе за све фајлове, без обзира на њихов тип.

  [options] --keep 20 --option nostrip

Као и са опцијама командне линије, и у конфигурационом фајлу можете да скратите параметре који се прослеђују:

  [options] -k 20 -o nostrip

Приоритет опција

Опције свих извора се спајају, чиме се једноставно обезбеђује да детаљније опције могу преиначити подразумеване вредности. Редослед је као што следи:

•   "[options]" линије постављају подразумеване вредности које било који други извор може да преиначи.

•   Затиме се користе алијаси типа. Подешавања за одређени језик преиначују подешавања која се примењују за све језике.

•   Подешавања која су посебна за дати мастер фајл преиначују и подразумевана и она која долазе од алијаса типа. И у овом случају такође, подешавања специфична за језик преиначују глобална подешавања.

•   Коначно, параметри који се задају у командној линији програма po4a преиначују било која подешавања из конфигурационог фајла.

Пример

Ево примера који показује на који начин се обележавају размаци и знаци навода:

 [po_directory] man/po/

 [options] --master-charset UTF-8

 [po4a_alias:man] man opt:"-o \"mdoc=NAME,SEE ALSO\""
 [type:man] t-05-config/test02_man.1 $lang:tmp/test02_man.$lang.1 \
            opt:"-k 75" opt_it:"-L UTF-8" opt_fr:--verbose

  Додатак: додавање допунског садржаја у превод
Ако желите да превод допуните додатним одељком, не пример, да изјавите захвалност преводиоцу, онда морате да дефинишете додатак линији која дефинише ваш мастер фајл. Молимо вас да погледате страницу po4a(7) како би сазнали више детаља у вези синтаксе фајлова додатака.

 [type: pod] script fr:doc/fr/script.1 \
             add_fr:doc/l10n/script.fr.add

Такође можете да употребите језичке шаблоне на начин који следи:

 [type: pod] script $lang:doc/$lang/script.1 \
             add_$lang:doc/l10n/script.$lang.add

У случају да додатак не може да се примени превод се одбацује.

Модификатори за декларацију додатка

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

?   Укљчује addendum_path у случају да овај фајл постоји, у супротном не ради ништа.

@   addendum_path није регуларан додатак већ фајл који садржи листу додатака, по један у свакој линији. Испред сваког додатка могу да се наведу модифкатори.

!   addendum_path се одбацује, не учитава се и ниједна каснија спецификација додатка га неће учитати.

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

 [type: pod] script $lang:doc/$lang/script.1  add_$lang:?doc/l10n/script.$lang.add

Оно што следи укључује листу додатака за сваки језик:

 [type: pod] script $lang:doc/$lang/script.1  add_$lang:@doc/l10n/script.$lang.add

  Филтрирање преведених стрингова
Понекад неке стрингове желите да сакријете од процеса превођења. У том циљу, вашем мастер фајлу можете да додате параметар "pot_in" када се изграђује POT file. Ево примера:

  [type:docbook] book.xml          \
          pot_in:book-filtered.xml \
          $lang:book.$lang.xml

Са овим подешавањем, стрингови који треба да се преведу биће извучени из book-filtered.xml (који мора да се креира пре позивања програма po4a) док ће преведени фајлови да се изграде из book.xml. Као резултат, било који стринг који је део book.xml али се не налази у book-filtered.xml неће постати део PO фајлова, чиме се преводиоци спречавају да их преведу. Тако да ће ови стрингови остати неизмењени када се буде креирали преведени документи. Наравно да ово смањује ниво преведености, тако да ће вам вероватно бити потребна опција "--keep" како би обезбедили да се документи ипак креирају.

  ПРИМЕР КОНФИГУРАЦИЈЕ
ДАЉИРАД: Да ли је овај одељак заиста користан?

Претпоставимо да одржавате програм под именом foo који има man страницу man/foo.1 која се природно одржава само на енглеском језику. Сада ви као узводни или низводни одржавалац желите да креирате и одржавате превод. Најпре програмом po4a-gettextize(1) морате да креирате POT фајл који обавезно мора да се пошаље преводиоцима.

Тако да бисмо у нашем случају позвали

 cd man && po4a-gettextize -f man -m foo.1 -p foo.pot

Затим бисте овај фајл послали одговарајућим језичким листама или га понудили за преузимање негде на свом вебсајту.

Претпоставимо сада да сте пре следећег издања програма примили три превода: de.po (заједно са додатком de.add), sv.po и pt.po. Пошто не желите да мењате свој Makefile (или више њих) сваки пут када вам стигне нови превод, можете да у свом Makefile искористите програм po4a са погодним конфигурационим фајлом. Назовимо га po4a.cfg. У нашем примеру би то изгледало овако:

 [po_directory] man/po4a/po/

 [type: man] man/foo.1 $lang:man/translated/$lang/foo.1 \
            add_$lang:?man/po4a/add_$lang/$lang.add opt:"-k 80"

У овом примеру се претпоставља да би све ваше генерисане man странице (и сви PO и фајлови додатака) требало да се чувају у man/translated/$lang/ (респективно у man/po4a/po/ и man/po4a/add_$lang/) под текућим директоријумом. У нашем примеру би директоријум man/po4a/po/ укључивао de.po, pt.po и sv.po, а директоријум man/po4a/add_de/ би укључивао de.add.

Приметите употребу модификатора ? јер додатак долази само уз немачки превод (de.po).

Да бисте заиста изградили преведене man странице тада бисте (једном!) додали следећу линију у build циљ одговарајућег Makefile:

        po4a po4a.cfg

Једном када је ово постављено више не морате да дирате Makefile када стигне нови превод, нпр. ако вам француски тим пошаље fr.po и fr.add ви их једноставно сместите у man/po4a/po/ и man/po4a/add_fr/ респективно, па када се програм следећи пут изгради, аутоматски ће да се изгради и француски превод и смести у man/translated/fr/.

Имајте на уму да вам је и даље потребан одговарајући циљ да инсталирате локализоване странице приручника, заједно са енглеским.

Коначно, ако не сместите генерисане фајлове у ваш систем за контролу верзија, биће вам потребна и линија у вашем clean циљу:
        -rm -rf man/translated

ПОГЛЕДАЈТЕ ТАКОЂЕ
po4a-gettextize(1), po4a-normalize(1), po4a-translate(1), po4a-updatepo(1), po4a(7).

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

ПРАВА УМНОЖАВАЊА И ЛИЦЕНЦА
Права умножавања 2002-2020 by SPI, inc.

Овај програм је слободан софтвер; можете да га редистрибуирате и/или мењате под условима GPL (погледајте фајл COPYING).