Туторијал за брзи почетак¶

Претпоставимо да одржавате програм под именом foo који има man страницу man/foo.1 написану на енглеском језику (посредним језиком већине пројеката отвореног кода, мада po4a може да се користи за било коју комбинацију изворног и циљног језика). Пре неког времена, неко је доставио немачки превод под именом man/foo.de.1 и нестао. Ово представља проблем јер сте управо добили извештај о багу који каже да ваша документација садржи озбиљно погрешну информацију која мора да се исправи у свим језицима, али ви не познајете немачки језик тако да можете изменити само оригинал, а не и превод. Затим, још један сарадник жели да допринесе превод на јапански, још један језик којим не владате.

Време је двоју документацију конвертујете у po4a и тако решите хаос у одржавању документације. Желите да ажурирате документ када је то потребно, желите да колегама преводиоцима олакжате посао и желите обезбедити да ваши кориснии никада не виде застарелу и услед тога нетачну документацију.

Конверзија се састоји из два корака: постављање po4a инфраструктуре и конверзија претходно постојећег немачког превода како би се сачувао ранији рад. Овај други део се ради помоћу скрипте po4a-gettextize, као што следи. Из детаља у документацији скрипте po4a-gettextize(1) се види да је овај процес ретко кад у потпуности аутоматски, али једном када се обави, фајл de.po који садржи немачки превод може да се интегрише у ваш po4a процес рада.

  po4a-gettextize --format man --master foo.1 --localized foo.de.1 --po de.po

Хајде сада конфигуришемо po4a. Уз погодан распоред фајлова, ваша конфигурација може да буде овако једноставна:

 [po_directory] man/po4a/
 [type: man] man/foo.1 $lang:man/translated/foo.$lang.1

Она наводи да се сви PO фајлови (који садрже рад преводилаца) налазе у директоријуму man/po4a/ и да имате само један мастер фајл, man/foo.1. Ако имате неколико мастер фајлова, морали бисте да наведете неколико линија сличних другој линији. Свака та линија такође наводи и где да се упишу одговарајући фајлови превода. У овом случају, немачки превод фајла man/foo.1 је man/translated/foo.de.1.

Последња ствар која треба да се уради како би се комплетирала конфигурација po4a је POT фајл који садржи материјал шаблона који треба да се користи када се започиње нови превод. Једноставно креирајте празан фајл са .pot екстензијом у наведеном po_directory (нпр. man/po4a/foo.pot), а po4a ће га испунити са очекиваним садржајем.

Ево подсетника фајлова који се користе у овом подешавању:

  ├── man/
  │   ├── foo.1         <- Оригинална man страница, на енглеском језику
  │   ├── po4a/
  │   │   ├── de.po    <- немачки PO превод, добијен gettextизацијом
  │   │   └── foo.pot  <- POT шаблон будућих превода (у почетку празан)
  │   └── translated/  <- Директоријум у који ће се смештати преводи
  └── po4a.cfg         <- Конфигурациони фајл

Једном када је подешен, извршавањем програма po4a се парсира ваша документација, ажурира POT фајл шаблона, он се употреби за ажурирање PO фајлова превода, а ти фајлови се употребе за ажурирање фајлова превода документације. Све у једној команди:

        po4a --verbose po4a.cfg

И то је то. po4a је сада у потпуности конфигурисан. Када исправите грешку у man/foo.1, неисправан пасус у немачком преводу ће се заменити исправљеним текстом на енглеском. Мешање језика није баш оптимално, али то је једини начин да се у преводима које чак и не разумете исправе грешке и да се обезбеди да је садржај који се представи корисницима увек тачан. Ажурирање немачког превода је такође много једноставније у одговарајућем PO фајлу, тако да мешавина језика вероватно неће дуго потрајати. Коначно, када преводилац на јапански жели да допринесе нови превод, требало би да преименује foo.pot у jp.po и доврши превод. Када добијете тај фајл, једноставно га убаците у директоријум man/po4a/po/. Када поново покренете po4a, преведена страница ће се појавити као man/translated/foo.jp.1 (у случају да је преведена потребна количина текста).

Опције које мењају 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 или каснија, и подразумевано је активирана.

Проналажење PO и POT фајлова¶

Најједноставније решење је да се експлицитно зада путања до POT и PO фајлова, као што следи:

 [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_directory] man/po/

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

Имајте на уму да морате изабрати само једно од "po_directory" и "po4a_paths". Прво ("po_directory") је компактније, додатно умањује ризик грешака приликом копирања/убацивања, али вас приморава да користите очекивану структуру пројекта, као и имена фајлова. Друго ("po4a_paths"), је експлициније, вероватно и читљивије, и пожељно да се користи када подешавате свој први пројекат са po4a.

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

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

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

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

Овом линијом ће po4a да произведе одвојене POT и PO фајлове за сваки документ који се преводи. На пример, ако имате 3 документа и 5 језика, добићете 3 POT фајлова и 15 PO фајлова. Они добијају име наведено "po4a_paths" шаблоном, у којем се $master замењује са базним именом сваког документа који се преводи. У случају да дође до конфликта, на следећи начин можете навести POT фајл који треба да се користи, параметром "pot=".

Ова могућност такође може да се употреби у циљу груписања неколико преведених фајлова у исти POT фајл. Следећи пример генерише само 2 POT фајла: l10n/po/foo.pot (који садржи материјал из foo/gui.xml) и l10n/po/bar.pot (који садржи материјал и из bar/gui.xml и из bar/cli.xml).

 [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 pot=foo
 [type: xml] bar/gui.xml $lang:bar/gui.$lang.xml pot=bar
 [type: xml] bar/cli.xml $lang:bar/cli.$lang.xml pot=bar

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