Подржани формати¶

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

man (стабилни парсер)

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

Модул Locale::Po4a::Man(3pm) такође подржава и mdoc формат који користе BSD man стране (оне су такође прилично уобичајене и на Linux системима).

AsciiDoc (стабилан парсер)

Ово је једноставан формат за обележавање који је намењен за поједностављивање писања документације. На пример, коришћен је за документовање git система. Те man стране су преведене уз помоћ po4a.

За још детаља, погледајте Locale::Po4a::AsciiDoc.

pod (стабилни парсер)

Ово је Perl Online Documentation формат. Сам језик и његова проширења су документовани употребом овог формата заједно са већином постојећих Perl скрипти. Он олакшава држање документације близу кода који описује уграђујући их заједно у исти фајл. Чини живот програмера једноставнијим, али на несрећу не и преводиочев. Све док не почнете да користите po4a.

За више детаља, погледајте Locale::Po4a::Pod.

sgml (стабилни парсер)

Чак и ако је данас превазиђен са XML форматом, овај формат се и даље користи за документе који су дугачки више од неколико екрана. Чак може да се користи и за комплетне књиге. Ажурирање докумената ове дужине може да буде прилично изазовно. diff се често показује бескорисним када је увлачење оригиналног текста поново урађено након ажурирања. На сву срећу, po4a може да вам помогне након тог процеса.

Тренутно су подржани само DebianDoc и DocBook DTD описи, али додавање подршке за неки нови је заиста једноставно. Чак је могуће да се употреби po4a на непознатом SGML DTD без измене кода достављајући неопходне информације преко командне линије. Погледајте Locale::Po4a::Sgml(3pm) за више детаља.

TeX / LaTeX (стабилни парсер)

LaTeX формат је главни формат документације који се користи у свету Слободног Софтвера као и за публикације.

Модул Locale::Po4a::LaTeX(3pm) је тестиран са Python документацијом, књигом и неким презентацијама.

text (стабилни парсер)

Text формат је базни формат за многе друге формате који укључују дугачке блокове текста, укључујући Markdown, fortunes, YAML одељак пре главног текста, debian/changelog, и debian/control.

Ово подржава уобичајене формате који се користе за Генераторе Статичког Сајта, ПРОЧИТАЈМЕ, и остале системе документације. Погледајте Locale::Po4a::Text(3pm) за више детаља.

xml и XHMTL (вероватно стабилан парсер)

XML формат је базни формат за многе формате документације.

po4a тренутно подржава DocBook DTD (погледајте Locale::Po4a::Docbook(3pm) за више детаља) и XHTML.

BibTex (вероватно стабилан парсер)

Формат BibTex се користи уз LaTex за форматирање листи референци (библиографије).

За више детаља, погледајте Locale::Po4a::BibTex.

Docbook (вероватно стабилан парсер)

Језик означавања заснован на XML који за описивање докумената користи семантичке ознаке.

За више детаља, погледајте Locale::Po4a:Docbook.

Guide XML (вероватно стабилан парсер)

XML формат документације. Овај модул је специјално развијен као помоћ за подршку и одржавање превода Gentoo Linux документације све до барем марта 2016 (како каже Wayback Machine). Од тада се Gentoo пребацио на DevBook XML формат.

За више детаља, погледајте Locale::Po4a:Guide.

Wml (вероватно стабилан парсер)

Web Markup Language, немојте да помешате WML са WAP протоколом који се користи на мобилним телефонима. Овај модул се ослања на Xhtml модул, који се са своје стране ослања на XmL модул.

За више детаља, погледајте <Locale::Po4a::Wml>.

Yaml (вероватно стабилан парсер)

Стриктни надскуп JSON. YAML се често користи за пројекте система или конфигурације. YAML је језгро за Ansible компаније Red Hat.

За више детаља, погледајте Locale::Po4a::Yaml.

RubyDoc (вероватно стабилан парсер)

Формат Ruby Document (RD), у почетку подразумевани формат документације за Ruby и Ruby пројекте пре конверзије у RDoc 2002. године. Мада изгледа да јапанска верзија Ruby референтног приручника још увек користи RD.

За више детаља, погледајте Locale::Po4a::RubyDoc.

Halibut (вероватно експериментални парсер)

Систем документације са елементима који личе на TeX, debiandoc-sgml, TeXinfo и остале, развио је Сајмон Татам, програмер програма PuTTY.

За више детаља, погледајте Locale::Po4a:Halibut.

Ini (вероватно експериментални парсер)

Формат фајла за конфигурацију који је MS-DOS учинио популарим.

За више детаља, погледајте Locale::Po4a::Ini.

texinfo (врло експериментални парсер)

Сва GNU документација је написано у овом формату (то је чак један од захтева да се постане званичан GNU пројекат). Подршка за Locale::Po4a::Texinfo(3pm) у po4a је и даље на почетку. Молимо да пријавите багове и поднесете захтеве за новим могућностима.

Остали подржани формати

Po4a такође може да обради и ређе или специјализоване формате, као што је документација опција компилације 2.4+ Linux кернела (Locale::Po4a::KernelHelp) или дијаграми које производи алат dial (Locale::Po4a:Dia). Додавање нових формата је често веома једноставно и главни задатак је да се изађе са парсером за ваш циљни формат. Погледајте Locale::Po4a::TransTractor(3pm) за више информација у вези овога.

Неподржани формати

Нажалост, po4a још нема подршку за неколико формата документације. Подршка за многе од њих би се лако додала у po4a. То укључује формате који се не користе само за документацију, као што су описи пакета (deb и rpm), питања у скриптама за инсталацију пакета, дневници измена пакета, и сво специјализовани фајл формати које користе програми као што су сценарија за игре или wine ресурс фајлови.

Графички преглед po4a скрипти¶

Схема која следи даје преглед начина на који свака po4a скрипта може да се користи. Овде је мастер.doc име дато као пример документације која треба да се преведе; XX.doc је тај исти документ преведен на језик XX док је doc.XX.po каталог превода за тај документ на језику XX. Аутори документације ће углавном да се баве са мастер.doc (што може да буде manстрана, XML документ, asciidoc фајл или нешто слично); преводиоци ће углавном да се фокусирају на PO фајл, док ће крајњи корисници да виде само фајл XX.doc.

                                   мастер.doc
                                       |
                                       V
     +<-----<----+<-----<-----<--------+------->-------->-------+
     :           |                     |                        :
{превођење}      |         { ажурирање мастер.doc }             :
     :           |                     |                        :
   XX.doc        |                     V                        V
(опционално)    |                  мастер.doc ->-------->------>+
     :           |                   (нови)                     |
     V           V                     |                        |
  [po4a-gettextize]   doc.XX.po -->+   |                        |
          |           (стари)      |   |                        |
          |              ^         V   V                        |
          |              |     [po4a-updatepo]                  |
          V              |           |                          V
     превод.pot          ^           V                          |
          |              |        doc.XX.po                     |
          |              |         (fuzzy)                      |
    { превођење }        |           |                          |
          |              ^           V                          V
          |              |    {ручно уређивање}                 |
          |              |           |                          |
          V              |           V                          V
      doc.XX.po --->---->+<---<-- doc.XX.po    додатак     мастер.doc
     (иницијални)                 (ажуриран) (опционално)  (ажуриран)
          :                          |            |             |
          :                          V            |             |
          +----->----->----->------> +            |             |
                                     |            |             |
                                     V            V             V
                                     +------>-----+------<------+
                                                  |
                                                  V
                                           [po4a-translate]
                                                  |
                                                  V
                                                XX.doc
                                              (ажуриран)

Ова схема је компликована, али у пракси, једном када се пројекат постави и конфигурише, користи се само њен десни део (који укључује po4a-updatepo(1) и po4a-translate(1)).

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

У врху десног дела је приказана акција оригиналног аутора, освежавање документације. Средњи десни део приказује аутоматизоване акције скрипте po4a-updatepo(1). Нови материјал се издваја и пореди са постојећим преводом. За делове који се нису изменили користиће се претходни превод, док се делимично измењени делови повезују са претходним преводом помоћу „fuzzy” ознаке која означава да превод мора да се ажурира. Нови или доста измењени материјал се оставља непреведен.

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

Доњи део слике приказује како po4a-translate(1) креира преведени изворни документ из мастер.doc оригиналног документа и doc.XX.po каталога превода који су преводиоци ажурирали. Поново се искоришћава структура документа, док се оригинални садржај замењује својим одговарајућим преводом. Необавезно, може да се употреби додатак како би се превод допунио неким додатним текстом. Ово се често користи да се дода име преводиоца финалном документу. Погледајте ниже за још детаља.

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

Започињање новог превода¶

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

Ако бисте радије да користите индивидуалне скрипте, требало би да на начин као што следи употребите po4a-gettextize(1) и креирате POT фајл. Овај фајл затим може да се копира у XX.po и тако започне нови превод.

  $ po4a-gettextize --format <формат> --master <мастер.doc> --po <превод.pot>

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

Интегрисање измена на оригиналном документу¶

За ово се користи скрипта po4a-updatepo(1) (за детаље, молимо да погледате њену документацију):

  $ po4a-updatepo --format <формат> --master <нови_мастер.doc> --po <стари_doc.XX.po>

Мастер документ се користи као улаз, док се PO фајл ажурира: он је уједно и улаз и излаз.

Генерисање преведеног документа¶

Једном када завршите са превођењем, хоћете да добијете преведену документацију и да је дистрибуирате корисницима заједно уз оригиналну. Да бисте то урадили, употребите програм po4a-translate(1) на следећи начин:

  $ po4a-translate --format <формат> --master <мастер.doc> --po <doc.XX.po> --localized <XX.doc>

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

Употреба додатака за додавање додатног текста преводима¶

Додавање новог текста преводу је вероватно једина ствар која је једноставнија на дуже стазе у случају када фајлове преводите ручно :). Ове се дешава када желите да додате допунски одељак преведеном документу, који не одговара никаквом садржају оригиналног документа. Класични случај употребе је за одавање признања преводилачком тиму, као и да се наведе начин за пријаву проблема који се тичу превода.

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

Линија заглавља мора да почне са стрингом PO4A-HEADER:, након чега следи листа кључ=вредност поља раздвојених са тачка запета знацима.

На пример, следеће заглавље декларише додатак који мора да се постави на сам крај превода.

 PO4A-HEADER: mode=eof

Ствари постају компликованије када додатни садржај желите да поставите у средину документа. Наредно заглавље декларише додатак који у превод мора да се постави након XML одељка који садржи стринг "У вези овог документа".

 PO4A-HEADER: position=У вези овог документа; mode=after; endboundary=</section>

У пракси, када покушава да примени додатак, програм po4a тражи прву линију која задовољава "position" аргумент (то може да буде регизраз). Не заборавите да po4a овде разматра преведени документ. Ова документација је на српском језику, али ваша линија би вероватно требало да изгледа као што следи, у случају да намеравате да свој додатак уметнете у француски превод.

 PO4A-HEADER: position=À propos de ce document; mode=after; endboundary=</section>

Онда када се у циљном документу пронађе "position", програм po4a тражи следећу линију након "position" која се подудара са наведеним "endboundary". Додатак се умеће непосредно иза те линије (јер смо задали endboundary, тј. границу на којој се завршава текући одељак).

Потпуно исти ефекат би могао да се добије следећим еквивалентним заглављем:

 PO4A-HEADER: position=У вези овог документа; mode=after; beginboundary=<section>

Овде програм po4a тражи у преводу прву линију која се подудара са "<section"> након линије која се подудара са "У вези овог документа", и умеће додатак испред те линије, јер смо задали beginboundary, тј. границу која означава почетак наредног одељка. Тако да ова линија заглавља захтева да се додатак постави иза одељка који садржи "У вези овог документа", и обавештава програм po4a да одељка започиње линијом која садржи ознаку "<section">. Ово је еквивалентно са претходним примером јер, у суштини, оно што заиста желите је да уметнете овај додатак иза "/section"> или испред "<section">.

Можете такође да поставите режим уметања mode на вредност "before", са сличном семантиком: комбиновање "mode=before" са "endboundary" ће да постави додатак непосредно иза пронађене границе, последње потенцијалне граничне линије испред "position". Комбиновање "mode=before" са "beginboundary" ће да постави додатак непосредно испред пронађене границе, последње потенцијалне граничне линије испред "position".

  Режим  | Врста границе |     Употребљена граница     | Место уметања гледано у односу на границу
 ========|===============|=============================|===========================================
 'before'| 'endboundary' | последња испред 'position'  | Непосредно иза изабране границе
 'before'|'beginboundary'| последња испред 'position'  | Непосредно испред изабране границе
 'after' | 'endboundary' | прва иза 'position'         | Непосредно иза изабране границе
 'after' |'beginboundary'| прва иза 'position'         | Непосредно испред изабране границе
 'eof'   |   (ништа)     |  нема                       | Крај фајла

Савети и трикови у вези додатака

• Запамтите да су све ово регуларни изрази. На пример, ако желите да пронађете крај nroff одељка који се завршава са линијом ".fi", немојте да користите ".fi" као endboundary, јер ће то да пронађе "the[ fi]le", што очигледно није оно што очекујете. У овом случају, исправна вредност за endboundary је: "^\.fi$".
• Празни карактери у садржају "position" и граница СУ БИТНИ. Тако да се наредне две линије разликују. Друга ће да се пронађе само онда када у преведеном документу има довољно празних карактера на крају.

   PO4A-HEADER: position=У вези овог документа; mode=after; beginboundary=<section>
   PO4A-HEADER: position=У вези овог документа ; mode=after; beginboundary=<section>
      

• Мада се може помислити да се ова претрага контекста оквирно врши над сваком линијом преведеног документа, она се у ствари врши над интерном стрингу података преведеног документа. Овај интерни стринг података може да буде текст који се протеже над пасусом који садржи више линија, или може да буде само једна XML ознака. Тачно место уметања додатка мора да буде пре или након интерног стринга података и не може да се нађе унутар тог стринга података.
• Да бисте разумели како се додаци умећу у превод, проследите аргумент -vv програму po4a. Од помоћи је и да покренете програм po4a у дибаг режиму јер тако можете да видите стварне интерне стрингове података у случају када се додатак не примењује.

Примери додатака

• Ако желите да додате нешто након следећег nroff одељка:

    .SH "AUTHORS"
      

  Требало би да изаберете приступ у два корака постављањем mode=after. Затим би требало да сузите претрагу на линију након AUTHORS регуларним изразом за аргумент position. Затим би требало да пронађете почетак наредног одељка (нпр. ^\.SH) помоћу регуларног израза за аргумент beginboundary. Дакле:

   PO4A-HEADER:mode=after;position=AUTHORS;beginboundary=\.SH
      

• Ако желите да додате нешто непосредно иза одређене линије (нпр. након линије „Права умножавања Велики Даса”), искористите position које се подудара са том линијом, mode=after и за beginboundary задајте да се подудара са било којом линијом.

   PO4A-HEADER:mode=after;position=Права умножавања Велики Даса, 2004;beginboundary=^
      

• Ако желите нешто да додате на крај документа, поставите да се position подудара са било којом линијом вашег документа (али само са једном линијом. Програм Po4a неће наставити даље ако није једна линија), и поставите да се endboundary не подудара ни са чим. Овде немојте да користите једноставне стрингове као "EOF", већ радије задајте оне за које је мала вероватноћа да постоје у вашем документу.

   PO4A-HEADER:mode=after;position=У вези овог документа;beginboundary=ЛажнаPo4aГраница
      

Детаљнији пример

Оригинални документ (POD форматиран):

 |=head1 NAME
 |
 |dummy - a dummy program
 |
 |=head1 AUTHOR
 |
 |me

Затим, следећи додатак ће обезбедити да се одељак (на француском) у вези преводиоца дода на крај фајла (на француском "TRADUCTEUR" значи "TRANSLATOR", а "moi" значи "me").

 |PO4A-HEADER:mode=after;position=AUTEUR;beginboundary=^=head
 |
 |=head1 TRADUCTEUR
 |
 |moi
 |

Да бисте уметнули свој додатак испред AUTHOR, употребите следеће заглавље:

 PO4A-HEADER:mode=after;position=NOM;beginboundary=^=head1

Ово функционише јер је наредна линија која се подудара са beginboundary /^=head1/ иза одељка "NAME" (преведено на "NOM" у француском), она која наводи ауторе. Дакле, додатак ће да се постави између ова два одељка. Приметите да ако се касније дода још један одељак између NAME и AUTHOR одељака, програм po4a ће погрешно да постави додатак испред тог новог одељка.

Да бисте ово спречили, исти резултат можете да постигнете употребом mode=before:

 PO4A-HEADER:mode=before;position=^=head1 AUTEUR

Како се изговара po4a?¶

Ја га лично изговарам као pouah <https://en.wiktionary.org/wiki/pouah>, што је француска ономатопејска реч коју користимо уместо бљак :) Вероватно имам чудан смисао за хумор :)

Шта је са осталим алатима за превођење документације помоћу gettext?¶

Има их неколико. Ево вероватно непотпуне листе, са још алата који су близу хоризонта.

poxml

Ово је алат који су развили KDE људи за обраду DocBook XML. Колико ја знам, то је први програм који издваја из документације стрингове за превод у PO фајлове, па их након превођења умеће назад.

Он може да ради само са XML форматом, и само са одређеним DTD. Посебно нисам задовољан начином на који обрађује листе, које на крају постају један велики msgid. Када листа постане велика, залогај постаје тежак за гутање.

po-debiandoc

Овај програм који је урадио Дени Барбије представља неку врсту претече po4a SGML модула, који га мање-више чини застарелим. Као што име говори, он обрађује само DebianDoc DTD, што је такође мање-више застарео DTD.

xml2po.py

Употребљава GIMP Тим за документацију од 2004. године, функционише прилично добро упркос томе што, као што име наговештава, ради само са XML фајловима и захтева специјално конфигурисане makefile фајлове.

Sphinx

За управљање својим преводима, Sphinx Documentation Project такође доста користи gettext. Нажалост, функционише само за неколико текст формата, rest и markdown, мада је вероватно једини алат који то ради управљајући комплетним процесом превођења.

Главне предности програма po4a над њима је једноставност уметања додатног садржаја (која је тамо још гора) и могућност постизања gettextизације.

РЕЗИМЕ предности приступа базираног на gettext¶

• Преводи се не чувају заједно са оригиналом, чиме је омогућено да се открије застарелост превода.
• Преводи се чувају засебно у одвојеним фајловима, чиме се спречава међусобно ометање преводиоца различитих језика, како током предаје својих закрпа тако и на нивоу кодирања фајла.
• Интерно је заснован на gettext (мада po4a нуди веома једноставан интерфејс, тако да не морате разумети унутрашње функционисање да бисте га користили). На тај начин не морамо поново да откријемо рупу на саксији, а из разлога што су ти алати широко распрострањени, можемо претпоставити и да су мање-више ослобођени багова.
• За крајње кориснике ништа није промењено (осим чињенице да ће највероватније боље да одржавају преводе). Резултујући фајл документације који се дистрибуира је потпуно исти.
• Нема потребе да преводиоци уче нову синтаксу фајлова и њихов омиљени едитор PO фајлова (као што су Емаксов PO режим, Lokalize или Gtranslator) ће сасвим лепо да функционише.
• gettext обезбеђује једноставан начин за добијање статистика у вези онога што је урађено, онога што треба да се редигује и ажурира, као и онога што је још преостало да се уради. Неки пример може да се пронађе на следећим адресама:

   - https://docs.kde.org/stable5/en/kdesdk/lokalize/project-view.html
   - http://www.debian.org/intl/l10n/
      

Али није све тако сјајно, овај приступ има и неке лоше стране са којима морамо да се носимо.

• Додаци су… чудни на први поглед.
• Преведени текст не можете да прилагодите по свом нахођењу, као на пример, да овде поделите пасус, а онде спојите друга два. Мада у неку руку, ако постоји проблем са оригиналом, то би у сваком случају требало да се пријави као баг.
• Чак и са једноставним интерфејсом, он је ипак нови алат који људи морају научити како да користе.

  Један од мојих снова би био да некако интегришемо po4a у Gtranslator или Lokalize. Када се фајл документације отвори, стрингови се аутоматски издвоје, и преведени фајл + po фајл могу да се упишу на диск. Ако успемо да урадимо MS Word (TM) модул (или макар RTF) можда би га чак користили и професионални преводиоци.