PO4A.7(1)

ИМЕ
po4a - радни оквир за превод документације и осталог материјала

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

Овај документ служи као увод у po4a који се обраћа потенцијалним корисницима који разматрају да ли да употребе овај алат и радозналима који желе да разумеју зашто су ствари онакве какве су.

Зашто po4a?
Филозофија Слободног Софтвера је да се технологија заиста учини доступном свима. Али лиценцирање није једина брига: непреведени слободни софтвер је бескористан корисницима који не говоре енглески језик. Стога, имамо да одрадимо још посла како би софтвер био доступан свима.

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

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

Regarding documentation, however, the situation still somewhat disappointing. At first translating documentation may seem to be easier than translating a program as it would seem that you just have to copy the documentation source file and start translating the content. However, when the original documentation is modified, keeping track of the modifications quickly turns into a nightmare for the translators. If done manually, this task is unpleasant and error-prone.

Застарели преводи су често гори од ситуације када уопште нема превода. Крајњи корисницу могу да буду заварани документацијом која описује старо понашање програма. Уз то, они не могу да имају директну интеракцију са одржаваоцима јер не говоре енглески језик. А одржаваоци такође не могу да поправе проблем јер не знају сваки језик на који је њихова документација преведена. Ове потешкоће, које су често последица лошег избора алата, могу да поткопају мотивацију преводиоца волонтера, чиме се проблем додатно погоршава.

Циљ po4a пројекта је да олакша рад преводиоцима документације. Тачније, он омогућава одржавање превода документације.

Идеја је да се искористи и прилагоди gettext приступ овом пољу. Као са gettext, текстови се издвајају из својих оригиналних локација и представљају преводиоцима као PO каталози превода. Преводиоци могу да искористе класичне gettext алате да прате рад који треба да се уради, сарађују и да се организују у тимове. po4a затим умеће преводе директно у структуру документације и тако прави преведене изворне фајлове који могу да се обраде и дистрибуирају на исти начин као и енглески фајлови. Сваки пасус који није преведен остаје на енглеском у излазном документу, па се на тај начин обезбеђује да крајњи корисници никада не виде застарели превод у документацији.

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

Молимо да такође погледате и ЧПП ниже у овом документу да бисте видели комплетнију листу добрих и лоших страна овог приступа.

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

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
The easiest way to use this tool in your project is to write a configuration file for the po4a program, and only interact with this program. Please refer to its documentation, in po4a(1). The rest of this section provides more details for the advanced users of po4a wanting to deepen their understanding.

  Detailed schema of the po4a workflow
Make sure to read po4a(1) before this overly detailed section to get a simplified overview of the po4a workflow. Come back here when you want to get the full scary picture, with almost all details.

In the following schema, master.doc is an example name for the documentation to be translated; XX.doc is the same document translated in the language XX while doc.XX.po is the translation catalog for that document in the XX language. Documentation authors will mostly be concerned with master.doc (which can be a manpage, an XML document, an AsciidDoc file, etc); the translators will be mostly concerned with the PO file, while the end users will only see the XX.doc file.

Transitions with square brackets such as "[po4a updates po]" represent the execution of a po4a tool while transitions with curly brackets such as "{ update of master.doc }" represent a manual modification of the project's files.

                                   master.doc
                                       |
                                       V
     +<-----<----+<-----<-----<--------+------->-------->-------+
     :           |                     |                        :
{translation}    |         { update of master.doc }             :
     :           |                     |                        :
   XX.doc        |                     V                        V
 (optional)      |                 master.doc ->-------->------>+
     :           |                   (new)                      |
     V           V                     |                        |
  [po4a-gettextize]   doc.XX.po -->+   |                        |
          |            (old)       |   |                        |
          |              ^         V   V                        |
          |              |   [po4a updates po]                  |
          V              |           |                          V
   translation.pot       ^           V                          |
          |              |        doc.XX.po                     |
          |              |         (fuzzy)                      |
   { translation }       |           |                          |
          |              ^           V                          V
          |              |     {manual editing}                 |
          |              |           |                          |
          V              |           V                          V
      doc.XX.po --->---->+<---<-- doc.XX.po    addendum     master.doc
      (initial)                 (up-to-date)  (optional)   (up-to-date)
          :                          |            |             |
          :                          V            |             |
          +----->----->----->------> +            |             |
                                     |            |             |
                                     V            V             V
                                     +------>-----+------<------+
                                                  |
                                                  V
                                     [po4a updates translations]
                                                  |
                                                  V
                                                XX.doc
                                             (up-to-date)

Again, this schema is overly complicated. Check on po4a(1) for a simplified overview.

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

On the top right part, the action of the original author is depicted, updating the documentation. The middle right part depicts the automatic updates of translation files: the new material is extracted and compared against the exiting translation. The previous translation is used for the parts that didn't change, while partially modified parts are connected to the previous translation with a "fuzzy" marker indicating that the translation must be updated. New or heavily modified material is left untranslated.

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

The bottom part of the figure shows how po4a creates a translated source document from the master.doc original document and the doc.XX.po translation catalog that was updated by the translators. The structure of the document is reused, while the original content is replaced by its translated counterpart. Optionally, an addendum can be used to add some extra text to the translation. This is often used to add the name of the translator to the final document. See below for details.

Upon invocation, po4a updates both the translation files and the translated documentation files automatically.

  Starting a new translation project
If you start from scratch, you just have to write a configuration file for po4a, and you are set. The relevant templates are created for the missing files, allowing your contributors to translate your project to their language. Please refer to po4a(1) for a quick start tutorial and for all details.

If you have an existing translation, i.e. a documentation file that was translated manually, you can integrate its content in your po4a workflow using po4a-gettextize. This task is a bit cumbersome (as described in the tool's manpage), but once your project is converted to po4a workflow, everything will be updated automatically.

  Updating the translations and documents
Once setup, invoking po4a is enough to update both the translation PO files and translated documents. You may pass the "--no-translations" to po4a to not update the translations (thus only updating the PO files) or "--no-update" to not update the PO files (thus only updating the translations). This roughly corresponds to the individual po4a-updatepo and po4a-translate scripts which are now deprecated (see "Why are the individual scripts deprecated" in the FAQ below).

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

Са 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>

Here, po4a searches for the first line matching "<section"> after the line matching "About this document" in the translation, and add the addendum before that line since we provided a beginboundary, i.e. a boundary marking the beginning of the next section. So this header line requires placing the addendum after the section containing "About this document", and instruct po4a that a section starts with a line containing the "<section"> tag. This is equivalent to the previous example because what you really want is to add this addendum either after "/section"> or before "<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"

    You should select a two-step approach by setting mode=after. Then you should narrow down search to the line after AUTHORS with the position argument regex. Then, you should match the beginning of the next section (i.e., ^\.SH) with the beginboundary argument regex. That is to say:

     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

На који начин програм функционише?
This chapter gives you a brief overview of the po4a internals, so that you may feel more confident to help us to maintain and to improve it. It may also help you to understand why it does not do what you expected, and how to solve your problems.

  TransTractors and project architecture
At the core of the po4a project, the Locale::Po4a::TransTractor(3pm) class is the common ancestor to all po4a parsers. This strange name comes from the fact that it is at the same time in charge of translating document and extracting strings.

More formally, it takes a document to translate plus a PO file containing the translations to use as input while producing two separate outputs: Another PO file (resulting of the extraction of translatable strings from the input document), and a translated document (with the same structure as the input one, but with all translatable strings replaced with content of the input PO). Here is a graphical representation of this:

   Улазни документ --\                             /---> Излазни документ
                      \      TransTractor::       /       (преведен)
                       +-->--   parse()  --------+
                      /                           \
   Улазни PO --------/                             \---> Излазни PO
                                                          (издвојен)

This little bone is the core of all the po4a architecture. If you provide both input and disregard the output PO, you get po4a-translate. If you disregard the output document instead, you get po4a-updatepo. The po4a uses a first TransTractor to get an up-to-date output POT file (disregarding the output documents), calls msgmerge -U to update the translation PO files on disk, and builds a second TransTractor with these updated PO files to update the output documents. In short, po4a provides one-stop solution to update what needs to be, using a single configuration file.

po4a-gettextize also uses two TransTractors, but another way: It builds one TransTractor per language, and then build a new PO file using the msgids of the original document as msgids, and the msgids of the translated document as msgstrs. Much care is needed to ensure that the strings matched this way actually match, as described in po4a-gettextize(1).

  Format-specific parsers
All po4a format parsers are implemented on top of the TransTractor. Some of them are very simple, such as the Text, Markdown and AsciiDoc ones. They load the lines one by one using TransTractor::shiftline(), accumulate the paragraphs' content or whatever. Once a string is completely parsed, the parser uses TransTractor::translate() to (1) add this string to the output PO file and (2) get the translation from the input PO file. The parser then pushes the result to the output file using TransTractor::pushline().

Some other parsers are more complex because they rely on an external parser to analyze the input document. The Xml, HTML, SGML and Pod parsers are built on top of SAX parsers. They declare callbacks to events such as "I found a new title which content is the following" to update the output document and output POT files according to the input content using TransTractor::translate() and TransTractor::pushline(). The Yaml parser is similar but different: it serializes a data structure produced by the YAML::Tiny parser. This is why the Yaml module of po4a fails to declare the reference lines: the location of each string in the input file is not kept by the parser, so we can only provide "$filename:1" as a string location. The SAX-oriented parsers use globals and other tricks to save the file name and line numbers of references.

One specific issues arises from file encodings and BOM markers. Simple parsers can forget about this issue, that is handled by TransTractor::read() (used internally to get the lines of an input document), but the modules relying on an external parser must ensure that all files are read with an appropriate PerlIO decoding layer. The easiest is to open the file yourself, and provide an filehandle or directly the full string to your external parser. Check on Pod::read() and Pod::parse() for an example. The content read by the TransTractor is ignored, but a fresh filehandle is passed to the external parser. The important part is the "<:encoding($charset)" mode that is passed to the open() perl function.

  Po objects
The Locale::Po4a::Po(3pm) class is in charge of loading and using PO and POT files. Basically, you can read a file, add entries, get translations with the gettext() method, write the PO into a file. More advanced features such as merging a PO file against a POT file or validating a file are delegated to msgmerge and msgfmt respectively.

  Contributing to po4a
Even if you have never contributed to any Open Source project in the past, you are welcome: we are willing to help and mentor you here. po4a is best maintained by its users nowadays. As we lack manpower, we try to make the project welcoming by improving the doc and the automatic tests to make you confident in contributing to the project. Please refer to the CONTRIBUTING.md file for more details.

Пројекти отвореног кода који користе po4a
Следи веома делимична листа пројеката који за своју документацију у продукцији користе po4a. Ако свој пројекат желите да додате на ову листу, само нам пошаљите мејл (или Merge захтев).

•   adduser (man): алат за управљање корисницима и групама.

•   apt (man, docbook): Debian менаџер пакета.

•   aptitude (docbook, svg): терминалски менаџер пакета за Debian

•   F-Droid website <https://gitlab.com/fdroid/fdroid-website> (markdown): installable catalog of FOSS (Free and Open Source Software) applications for the Android platform.

•   git <https://github.com/jnavila/git-manpages-l10n> (asciidoc): дистрибуирани систем за контролу верзија који служи за праћење измена у изворном коду.

•   Linux manстране <https://salsa.debian.org/manpages-l10n-team/manpages-l10n> (man)

    Овај пројекат обезбеђује инфраструктуру за превођење многих manстраница на различите језике, спремне за интеграцију у неколико главних дистрибуција (Arch Linux, Debian и из њега изведене, Fedora).

•   Stellarium <https://github.com/Stellarium/stellarium> (HTML): бесплатан планетаријум отвореног кода за ваш компјутер. po4a се користи за превод описа небеске културе.

•   Jamulus <https://jamulus.io/> (markdown, yaml, HTML): a FOSS application for online jamming in real time. The website documentation is maintained in multiple languages using po4a.

•   Још једна ставка која треба да се среди: <https://gitlab.com/fdroid/fdroid-website/> <https://github.com/fsfe/reuse-docs/pull/61>

ЧПП

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

  Why are the individual scripts deprecated?
Indeed, po4a-updatepo and po4a-translate are deprecated in flavor of po4a. The reason is that while po4a can be used as a drop-in replacement to these scripts, there is quite a lot of code duplication here. Individual scripts last around 150 lines of codes while the po4a program lasts 1200 lines, so they do a lot in addition of the common internals. The code duplication results in bugs occuring in both versions and needing two fixes. One example of such duplication are the bugs #1022216 in Debian and the issue #442 in GitHub that had the exact same fix, but one in po4a and the other po4a-updatepo.

In the long run, I would like to drop the individual scripts and only maintain one version of this code. The sure thing is that the individual scripts will not get improved anymore, so only po4a will get the new features. That being said, there is no deprecation urgency. I plan to keep the individual scripts as long as possible, and at least until 2030. If your project still use po4a-updatepo and po4a-translate in 2030, you may have a problem.

We may also remove the deprecation of these scripts at some point, if a refactoring reduces the code duplication to zero. If you have an idea (or better: a patch), your help is welcome.

  Шта је са осталим алатима за превођење документације помоћу 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/

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

•   Addenda are somewhat strange at the first glance.

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

•   Чак и са једноставним интерфејсом, он је ипак нови алат који људи морају научити како да користе.

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

ПОГЛЕДАЈТЕ ТАКОЂЕ

•   Документација све-у-једном алата који би требало да користите: po4a(1).

•   Документација појединачних po4a скрипти: po4a-gettextize(1), po4a-updatepo(1), po4a-translate(1), po4a-normalize(1).

•   Додатне помоћне скрипте: msguntypot(1), po4a-display-man(1), po4a-display-pod(1).

•   Парсери сваког од формата, тачније, да сазнате које опције прихвата сваки од њих: Locale::Po4a::AsciiDoc(3pm) Locale::Po4a::Dia(3pm), Locale::Po4a::Guide(3pm), Locale::Po4a::Ini(3pm), Locale::Po4a::KernelHelp(3pm), Locale::Po4a::Man(3pm), Locale::Po4a::RubyDoc(3pm), Locale::Po4a::Texinfo(3pm), Locale::Po4a::Text(3pm), Locale::Po4a::Xhtml(3pm), Locale::Po4a::Yaml(3pm), Locale::Po4a::BibTeX(3pm), Locale::Po4a::Docbook(3pm), Locale::Po4a::Halibut(3pm), Locale::Po4a::LaTeX(3pm), Locale::Po4a::Pod(3pm), Locale::Po4a::Sgml(3pm), Locale::Po4a::TeX(3pm), Locale::Po4a::Wml(3pm), Locale::Po4a::Xml(3pm).

•   Имплементација основне инфраструктуре: Locale::Po4a::TransTractor(3pm) (од посебне важности за разумевање организације кода), Locale::Po4a::Chooser(3pm), Locale::Po4a::Po(3pm), Locale::Po4a::Common(3pm). Молимо вас да у стаблу изворног кода такође погледате и фајл CONTRIBUTING.md.

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