
        *****************************************************
        *           GENERATED FILE, DO NOT EDIT             *
        * THIS IS NO SOURCE FILE, BUT RESULT OF COMPILATION *
        *****************************************************

This file was generated by po4a(7). Do not store it (in VCS, for example),
but store the PO file used as source file by po4a-translate.

In fact, consider this as a binary, and the PO file as a regular .c file:
If the PO get lost, keeping this translation up-to-date will be harder.

=encoding UTF-8

=head1 NUME

po4a - cadru pentru traducerea documentației și a altor materiale

=head1 Introducere

po4a (PO pentru orice) facilitează întreținerea traducerii documentației
utilizând instrumentele clasice gettext. Principala caracteristică a po4a
este că decuplează traducerea conținutului de structura documentului său.

Acest document servește drept introducere la proiectul po4a, cu accent pe
utilizatorii potențiali care se gândesc dacă să utilizeze acest instrument
și pe cei curioși care doresc să înțeleagă de ce lucrurile sunt așa cum
sunt.

=head1 De ce po4a?

Filozofia software-ului liber este de a face tehnologia cu adevărat
disponibilă pentru toată lumea. Dar licențierea nu este singurul aspect de
luat în considerare: software-ul liber netradus este inutil pentru cei care
nu vorbesc limba engleză. Prin urmare, mai avem încă ceva de lucru pentru a
face software-ul disponibil pentru toată lumea.

Această situație este bine înțeleasă de majoritatea proiectelor și toată
lumea este acum convinsă de necesitatea de a traduce totul. Cu toate
acestea, traducerile efective reprezintă un efort uriaș al multor persoane,
paralizat de mici dificultăți tehnice.

Din fericire, software-ul Open Source este de fapt foarte bine tradus cu
ajutorul suitei de instrumente gettext. Aceste instrumente sunt utilizate
pentru a extrage șirurile de caractere de tradus dintr-un program și pentru
a le prezenta într-un format standardizat (denumit fișiere PO sau cataloage
de traducere). Un întreg ecosistem de instrumente a apărut pentru a ajuta
traducătorii să traducă efectiv aceste fișiere PO. Rezultatul este apoi
utilizat de gettext în timpul execuției pentru a afișa mesaje traduse
utilizatorilor finali.

Cu toate acestea, în ceea ce privește documentația, situația este încă
oarecum dezamăgitoare. La început, traducerea documentației poate părea mai
ușoară decât traducerea unui program, deoarece s-ar părea că trebuie doar să
copiați fișierul sursă al documentației și să începeți să traduceți
conținutul. Cu toate acestea, atunci când documentația originală este
modificată, urmărirea modificărilor se transformă rapid într-un coșmar
pentru traducători. Dacă este efectuată manual, această sarcină este
neplăcută și predispusă la erori.

Traducerile învechite sunt adesea mai rele decât lipsa oricărei
traduceri. Utilizatorii finali pot fi înșelați de documentația care descrie
un comportament vechi al programului. În plus, aceștia nu pot interacționa
direct cu cei care se ocupă de întreținere, deoarece nu vorbesc engleza. În
plus, responsabilul cu întreținerea nu poate rezolva problema, deoarece nu
cunoaște toate limbile în care este tradusă documentația sa. Aceste
dificultăți, cauzate adesea de un instrumentar slab, pot submina motivația
traducătorilor voluntari, agravând și mai mult problema.

B<Obiectivul proiectului po4a este de a ușura munca traducătorilor de
documentație>. În special, acesta face traducerile de documentație I<ușor de
întreținut>.

Ideea este de a reutiliza și adapta abordarea gettext la acest domeniu. Ca
și în cazul gettext, textele sunt extrase din locațiile lor originale și
prezentate traducătorilor sub formă de cataloage de traduceri
PO. Traducătorii pot utiliza instrumentele clasice gettext pentru a
monitoriza munca de făcut, a colabora și a se organiza ca echipe. po4a
injectează apoi traducerile direct în structura documentației pentru a
produce fișiere sursă traduse care pot fi prelucrate și distribuite la fel
ca fișierele în limba engleză. Orice paragraf care nu este tradus este lăsat
în limba engleză în documentul rezultat, asigurându-se că utilizatorii
finali nu văd niciodată o traducere învechită în documentație.

Acest lucru automatizează cea mai mare parte a muncii de întreținere a
traducerii. Descoperirea paragrafelor care necesită o actualizare devine
foarte ușoară, iar procesul este complet automatizat atunci când elementele
sunt reordonate fără alte modificări. Verificarea specifică poate fi, de
asemenea, utilizată pentru a reduce șansele de erori de formatare care ar
conduce la un document defectuos.

Pentru o listă mai completă a avantajelor și dezavantajelor acestei
abordări, consultați și secțiunea B<Întrebări și răspunsuri frecvente> de
mai jos din acest document.

=head2 Formatele acceptate

În prezent, această abordare a fost implementată cu succes pentru mai multe
tipuri de formate de formatare a textului:

=over

=item man (analizator matur)

Vechiul format de pagini de manual, folosit de atât de multe
programe. Sprijinul po4a este foarte binevenit aici, deoarece acest format
este oarecum dificil de utilizat și nu este foarte prietenos pentru
începători.

Modulul L<Locale::Po4a::Man(3pm)|Man> acceptă, de asemenea, formatul mdoc,
utilizat de paginile man BSD (acestea sunt destul de comune și în Linux).

=item AsciiDoc (analizator matur)

Acest format este un format de marcare simplificat menit să faciliteze
crearea documentației. De exemplu, este utilizat pentru documentarea
sistemului git. Aceste pagini de manual sunt traduse folosind po4a.

Consultați L<Locale::Po4a::AsciiDoc> pentru detalii.

=item pod (analizator matur)

Acesta este formatul documentației în linie Perl. Limbajul și extensiile în
sine sunt documentate folosind acest format, în plus față de majoritatea
scripturilor Perl existente. Acesta facilitează păstrarea documentației
aproape de codul real prin încorporarea ambelor în același fișier. Face
viața programatorului mai ușoară, dar, din păcate, nu și pe cea a
traducătorului, până când nu utilizați po4a.

Consultați L<Locale::Po4a::Pod> pentru detalii.

=item sgml (analizator matur)

Chiar dacă a fost înlocuit de XML în prezent, acest format este încă
utilizat pentru documentele care au mai mult de câteva ecrane. Acesta poate
fi utilizat chiar și pentru cărți complete. Actualizarea documentelor de
această lungime poate fi foarte dificilă. B<diff> se dovedește adesea inutil
atunci când textul original a fost reindentat după actualizare. Din
fericire, po4a vă poate ajuta după acest proces.

În prezent, numai DTD DebianDoc și DTD DocBook sunt acceptate, dar adăugarea
suportului pentru unul nou este foarte ușoară. Este chiar posibil să
utilizați po4a pe un DTD SGML necunoscut fără a modifica codul, furnizând
informațiile necesare pe linia de comandă. Consultați
L<Locale::Po4a::Sgml(3pm)> pentru detalii.

=item TeX / LaTeX (analizator matur)

Formatul LaTeX este un format important de documentație utilizat în lumea
software-ului liber și pentru publicații.

Modulul L<Locale::Po4a::LaTeX(3pm)|LaTeX> a fost testat cu documentația
Python, o carte și câteva prezentări.

=item text (analizator matur)

Formatul Text este formatul de bază pentru multe formate care includ blocuri
lungi de text, inclusiv Markdown, fortunes, secțiunea de introducere YAML,
debian/changelog și debian/control.

Acesta acceptă formatul comun utilizat în generatoarele de situri statice,
README-uri și alte sisteme de documentare. Consultați
L<Locale::Po4a::Text(3pm)|Text> pentru detalii.

=item xml și XHMTL (probabil un analizator matur)

Formatul XML este un format de bază pentru multe formate de documentație.

În prezent, po4a acceptă DTD DocBook (consultați
L<Locale::Po4a::Docbook(3pm)> pentru detalii) și XHTML.

=item BibTex (probabil un analizator matur)

Formatul BibTex este utilizat împreună cu LaTex pentru formatarea listelor
de referințe (bibliografii).

Consultați L<Locale::Po4a::BibTex> pentru detalii.

=item Docbook (probabil un analizator matur)

Un limbaj de marcare bazat pe XML care utilizează etichete semantice pentru
a descrie documentele.

Consultați L<Locale::Po4a:Docbook> pentru informații mai detaliate.

=item Guide XML (probabil un analizator matur)

Un format de documentație XML. Acest modul a fost dezvoltat special pentru a
ajuta la susținerea și menținerea traducerilor documentației Gentoo Linux
cel puțin până în martie 2016 (Conform datelor din situl Wayback
Machine). De atunci, Gentoo a trecut la formatul DevBook XML.

Consultați L<Locale::Po4a:Guide> pentru informații mai detaliate.

=item Wml (probabil un analizator matur)

Limbajul de marcare web, nu confundați WML cu WAP-ul utilizat pe telefoanele
mobile. Acest modul se bazează pe modulul Xhtml, care la rândul său se
bazează pe modulul XmL.

Consultați L<Locale::Po4a::Wml> pentru informații mai detaliate.

=item Yaml (probabil un analizator matur)

Un superset strict al JSON. YAML este adesea utilizat ca sisteme sau
proiecte de configurare. YAML se află la baza Ansible de la Red Hat.

Consultați L<Locale::Po4a::Yaml> pentru informații mai detaliate.

=item RubyDoc (probabil un analizator matur)

Formatul Ruby Document (RD), inițial formatul implicit de documentare pentru
Ruby și proiectele Ruby înainte de a fi convertit în RDoc în 2002. Deși se
pare că versiunea japoneză a manualului de referință Ruby încă utilizează
RD.

Consultați L<Locale::Po4a::RubyDoc> pentru informații mai detaliate.

=item Halibut (probabil un analizator într-un stadiu experimental)

Un sistem de producție a documentației, cu elemente similare TeX,
debiandoc-sgml, TeXinfo și altele, dezvoltat de Simon Tatham, dezvoltatorul
PuTTY.

Consultați L<Locale::Po4a:Halibut> pentru informații mai detaliate.

=item Ini (probabil un analizator într-un stadiu experimental)

Format de fișier de configurare popularizat de MS-DOS.

Consultați L<Locale::Po4a::Ini> pentru informații mai detaliate.

=item texinfo (analizator într-un stadiu foarte experimental)

Toată documentația GNU este scrisă în acest format (este chiar una dintre
cerințele pentru a deveni un proiect GNU oficial). Suportul pentru
L<Locale::Po4a::Texinfo(3pm)|Texinfo> în po4a este încă la început. Vă rugăm
să raportați erori și solicitări de caracteristici.

=item gemtext (analizator într-un stadiu foarte experimental)

Formatul nativ de text simplu al protocolului Gemini. Extensia C<.gmi> este
frecvent utilizată. Suportul pentru acest modul în po4a este încă în fază
incipientă. Dacă găsiți ceva în neregulă, vă rugăm să depuneți un raport de
eroare sau o cerere de caracteristică.

=item org (analizator într-un stadiu foarte experimental)

Formatul de document utilizat de modul Org. Suportul pentru acest modul în
po4a este încă în fază incipientă. Dacă găsiți ceva în neregulă, vă rugăm să
depuneți un raport de eroare sau o cerere de caracteristică.

=item vimhelp (analizator într-un stadiu foarte experimental)

Formatul utilizat pentru fișierele de ajutor Vim (și documentația unor
module terțe). Suportul pentru acest format în po4a este încă în fază
incipientă. Dacă găsiți ceva în neregulă, vă rugăm să depuneți un raport de
eroare sau o cerere de caracteristică.

=item simplepod (analizator într-un stadiu foarte experimental)

Similar cu I<pod> menționat anterior, acesta adoptă noul L<Pod::Simple> ca
analizator. Deoarece este nou creat, sunt de așteptat unele erori. Dacă
observați vreun comportament ciudat, vă rugăm să ne anunțați. În cele din
urmă, acest modul va înlocui I<pod>.

=item Alte formate acceptate

Po4a poate gestiona și unele formate mai rare sau specializate, cum ar fi
documentația opțiunilor de compilare pentru nucleele Linux 2.4+
(L<Locale::Po4a::KernelHelp>) sau diagramele produse de instrumentul dia
(L<Locale::Po4a::Dia>). Adăugarea unui nou format este adesea foarte ușoară,
iar sarcina principală este de a veni cu un analizator pentru formatul
țintă. Consultați L<Locale::Po4a::TransTractor(3pm)> pentru mai multe
informații despre acest lucru.

=item Formate neacceptate

Din păcate, po4a nu oferă încă suport pentru mai multe formate de
documentație. Multe dintre acestea ar fi ușor de acceptat în po4a. Aceasta
include formate care nu sunt utilizate doar pentru documentație, cum ar fi,
descrieri de pachete (deb și rpm), întrebări privind scripturile de
instalare a pachetelor, jurnale de modificări ale pachetelor și toate
formatele de fișiere specializate utilizate de programe, cum ar fi
scenariile de jocuri sau fișierele de resurse pentru «wine».

=back

=head1 Folosind po4a

Cel mai simplu mod de a utiliza acest instrument în proiectul dumneavoastră
este să scrieți un fișier de configurare pentru programul B<po4a> și să
interacționați numai cu acest program. Vă rugăm să consultați documentația
acestuia, în L<po4a(1)>. Restul acestei secțiuni oferă mai multe detalii
pentru utilizatorii avansați ai po4a care doresc să își aprofundeze
cunoștințele.

=head2 Schema detaliată a fluxului de lucru po4a

Asigurați-vă că citiți L<po4a(1)> înainte de această secțiune excesiv de
detaliată pentru a obține o imagine de ansamblu simplificată a fluxului de
lucru po4a. Reveniți aici când doriți să obțineți imaginea înfricoșătoare în
ansamblu, cu aproape toate detaliile.

În următoarea schemă, F<principal.doc> este un nume de exemplu pentru
documentația care urmează să fie tradusă; F<XX.doc> este același document
tradus în limba XX, în timp ce F<doc.XX.po> este catalogul de traducere
pentru documentul respectiv în limba XX. Autorii documentației vor fi
preocupați în principal de F<principal.doc> (care poate fi o pagină de
manual, un document XML, un fișier AsciiDoc etc.); traducătorii vor fi
preocupați în principal de fișierul PO, în timp ce utilizatorii finali vor
vedea doar fișierul F<XX.doc>.

Tranzițiile cu paranteze drepte precum C<[po4a actualizări po]> reprezintă
executarea unui instrument po4a, în timp ce tranzițiile cu acolade precum
C<{actualizare de principal.doc}> reprezintă o modificare manuală a
fișierelor proiectului.

                                   principal.doc
                                       |
                                       V
     +<-----<----+<-----<-----<--------+------->-------->-------+
     :           |                     |                        :
{traducere}      |       {actualizare de principal.doc}         :
     :           |                     |                        :
   XX.doc        |                     V                        V
 (opțional)      |              principal.doc ->-------->------>+
     :           |                   (nou)                      |
     V           V                     |                        |
  [po4a-gettextize]   doc.XX.po -->+   |                        |
          |           (vechi)      |   |                        |
          |              ^         V   V                        |
          |              |  [po4a actualizează po]              |
          V              |           |                          V
    traducere.pot        ^           V                          |
          |              |        doc.XX.po                     |
          |              |  (trad. aprox. „fuzzy”)              |
     {traducere}         |           |                          |
          |              ^           V                          V
          |              |     {editare manuală}                |
          |              |           |                          |
          V              |           V                          V
      doc.XX.po --->---->+<---<-- doc.XX.po    addendum     master.doc
      (inițial)                 (actualizat)  (opțional)   (actualizat)
          :                          |            |             |
          :                          V            |             |
          +----->----->----->------> +            |             |
                                     |            |             |
                                     V            V             V
                                     +------>-----+------<------+
                                                  |
                                                  V
                                   [po4a actualizează traducerile]
                                                  |
                                                  V
                                                XX.doc
                                             (actualizat)

Din nou, această schemă este excesiv de complicată. Consultați L<po4a(1)>
pentru o prezentare simplificată.

Partea din stânga descrie modul în care L<po4a-gettextize(1)> poate fi
utilizat pentru a converti un proiect de traducere existent la
infrastructura po4a. Acest script ia un document original și omologul său
tradus și încearcă să construiască fișierul PO corespunzător. O astfel de
conversie manuală este destul de greoaie (consultați documentația
L<po4a-gettextize(1)> pentru mai multe detalii), dar este necesară o singură
dată pentru a vă converti traducerile existente. Dacă nu aveți nicio
traducere de convertit, puteți să uitați de acest lucru și să vă concentrați
pe partea dreaptă a schemei.

În partea dreaptă sus, este descrisă acțiunea autorului original, care
actualizează documentația. Partea din dreapta mijloc prezintă actualizările
automate ale fișierelor de traducere: materialul nou este extras și comparat
cu traducerea existentă. Traducerea anterioară este utilizată pentru părțile
care nu s-au schimbat, în timp ce părțile parțial modificate sunt conectate
la traducerea anterioară cu un marcaj „fuzzy” (traducere aproximativă) care
indică faptul că traducerea trebuie actualizată. Materialele noi sau
puternic modificate sunt lăsate netraduse.

Apoi, blocul I<editare manuală> descrie acțiunea traducătorilor, care
modifică fișierele PO pentru a furniza traduceri pentru fiecare șir și
paragraf original. Acest lucru se poate face fie utilizând un editor
specific, cum ar fi B<GTranslator>, B<Lokalize> de la KDE sau B<poedit>, fie
utilizând o platformă de localizare din Internet, cum ar fi B<weblate> sau
B<pootle>. Rezultatul traducerii este un set de fișiere PO, unul pentru
fiecare limbă. Vă rugăm să consultați documentația gettext pentru mai multe
detalii.

Partea de jos a figurii arată cum B<po4a> creează un document sursă tradus
din documentul original F<principal.doc> și catalogul de traduceri
F<doc.XX.po> care a fost actualizat de traducători. Structura documentului
este reutilizată, în timp ce conținutul original este înlocuit cu omologul
său tradus. Opțional, un addendum poate fi utilizat pentru a adăuga text
suplimentar la traducere. Acesta este adesea utilizat pentru a adăuga numele
traducătorului la documentul final. A se vedea mai jos pentru detalii.

La invocare, B<po4a> actualizează automat atât fișierele de traducere, cât
și fișierele de documentație traduse.

=head2 Începerea unui nou proiect de traducere

Dacă începeți de la zero, trebuie doar să scrieți un fișier de configurare
pentru po4a și ați terminat. Șabloanele relevante sunt create pentru
fișierele lipsă, permițând colaboratorilor dvs. să traducă proiectul dvs. în
limba lor. Vă rugăm să consultați L<po4a(1)> pentru un tutorial de pornire
rapidă și pentru toate detaliile.

Dacă aveți o traducere existentă, adică un fișier de documentație care a
fost tradus manual, puteți integra conținutul său în fluxul de lucru po4a
utilizând B<po4a-gettextize>. Această sarcină este un pic greoaie (așa cum
este descris în pagina de manual a instrumentului), dar odată ce proiectul
dvs. este convertit în fluxul de lucru po4a, totul va fi actualizat automat.

=head2 Actualizarea traducerilor și a documentelor

Odată configurat, invocarea B<po4a> este suficientă pentru a actualiza atât
fișierele PO de traducere, cât și documentele traduse. Puteți trece
C<--no-translations> la B<po4a> pentru a nu actualiza traducerile
(actualizând astfel doar fișierele PO) sau C<--no-update> pentru a nu
actualiza fișierele PO (actualizând astfel doar traducerile). Aceasta
corespunde aproximativ scripturilor individuale B<po4a-updatepo> și
B<po4a-translate> care sunt acum depreciate (a se vedea „De ce sunt
depreciate scripturile individuale?” în secțiunea de mai jos).

=head2 CUM se utilizează addenda pentru a adăuga text suplimentar la traduceri

Adăugarea de text nou la traducere este probabil singurul lucru care este
mai ușor pe termen lung atunci când traduceți manual fișiere :). Acest lucru
se întâmplă atunci când doriți să adăugați o secțiune suplimentară la
documentul tradus, care nu corespunde niciunui conținut din documentul
original. Cazul clasic de utilizare este de a acorda credite (mulțumiri,
recunoașterea muncii depuse, ș.a.) echipei de traducere și de a indica modul
de raportare a problemelor specifice traducerii.

Cu po4a, trebuie să specificați fișiere B<addendum>, care pot fi privite
conceptual ca plasturi (patches) aplicați documentului localizat(tradus)
după procesare. Fiecare addendum trebuie să fie furnizat ca fișier separat,
al cărui format este totuși foarte diferit de cel al plasturilor
clasice. Prima linie este o I<linie de antet>, care definește punctul de
inserție al addendumului (cu o sintaxă din păcate criptică - a se vedea mai
jos), în timp ce restul fișierului este adăugat textual la poziția
stabilită.

Linia de antet trebuie să înceapă cu șirul B<PO4A-HEADER:>, urmat de o listă
de câmpuri I<cheie>B<=>I<valoare> separate prin punct și virgulă.

De exemplu, următorul antet declară un addendum care trebuie plasat chiar la
sfârșitul traducerii.

 PO4A-HEADER: mode=eof

Lucrurile sunt mai complexe atunci când doriți să adăugați conținut
suplimentar în mijlocul documentului. Următorul antet declară un addendum
care trebuie plasat după secțiunea XML care conține șirul C<Despre acest
document> în traducere.

 PO4A-HEADER: position=Despre acest document; mode=after; endboundary=</section>

În practică, atunci când încearcă să aplice un addendum, po4a caută prima
linie care corespunde argumentului C<poziție> (acesta poate fi o expresie
regulată „expreg”). Nu uitați că po4a ia în considerare aici documentul
B<tradus>. Această documentație este în limba engleză, dar linia dvs. ar
trebui probabil să sune după cum urmează dacă intenționați ca addendumul
dvs. să se aplice traducerii în franceză a documentului.

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

Odată ce C<poziția> este găsită în documentul țintă, po4a caută următoarea
linie după C<poziția> care corespunde C<endboundary> furnizată. Addendumul
este adăugat chiar B<după> acea linie (deoarece am furnizat un
I<endboundary>, adică o limită care încheie secțiunea curentă).

Exact același efect ar putea fi obținut cu următorul antet, care este
echivalent:

 PO4A-HEADER: position=Despre acest document; mode=after; beginboundary=<section>

Aici, po4a caută prima linie care corespunde C<< <section> >> după linia
care corespunde C<About this document> din traducere și adaugă addendumul
B<înainte> de această linie, deoarece am furnizat un I<beginboundary>, adică
o limită care marchează începutul secțiunii următoare. Așadar, această linie
de antet necesită plasarea addendumului după secțiunea care conține C<About
this document>, și să instruim po4a că o secțiune începe cu o linie care
conține eticheta C<< <section> >>. Acest lucru este echivalent cu exemplul
anterior, deoarece ceea ce doriți cu adevărat este să adăugați acest
addendum fie după C<< </section> >>, fie înainte de C<< <section> >>.

De asemenea, puteți stabili inserția I<mod> la valoarea C<before>, cu o
semantică similară: combinarea C<mode=before> cu un C<endboundary> va plasa
addendum-ul chiar B<after> (după) limita care corespunde, adică ultima linie
de limită potențială înainte de C<position>. Combinarea C<mode=before> cu un
C<beginboundary> va plasa addendumul chiar B<before> (înainte) față de
limita corespunzătoare, adică ultima linie de limită potențială înainte de
C<position>.

  Mod    | Tipul de limită |       Limita utilizată       | Punctul de inserție în raport cu limita
 ========|=================|==============================|=========================================
 'before'|  'endboundary'  | ultima înainte de 'position' | Imediat după limita selectată
 'before'| 'beginboundary' | ultima înainte de 'position' | Chiar înainte de limita selectată
 'after' |  'endboundary'  |    prima după 'position'     | Imediat după limita selectată
 'after' | 'beginboundary' |    prima după 'position'     | Chiar înainte de limita selectată
 'eof'   |   (niciunul)    |    nedeclarată               | Sfârșitul fișierului

=head3 Sfaturi și trucuri despre addenda

=over

=item

Amintiți-vă că acestea sunt expresii regulate. De exemplu, dacă doriți să
potriviți sfârșitul unei secțiuni nroff care se termină cu linia C<.fi>, nu
utilizați C<.fi> ca B<endboundary>, deoarece se va potrivi cu C<the[ fi]le>,
ceea ce evident nu este ceea ce vă așteptați. B<endboundary> corect în acest
caz este: C<^\.fi$>.

=item

Spațiile albe SUNT importante în conținutul poziției C<position> și al
limitelor. Astfel, cele două linii următoare B<sunt diferite>. Cea de-a doua
va fi găsită numai dacă există suficiente spații la final în documentul
tradus.

 PO4A-HEADER: position=Despre acest document; mode=after; beginboundary=<section>
 PO4A-HEADER: position=Despre acest document ; mode=after; beginboundary=<section>

=item

Deși se poate considera că această căutare contextuală operează aproximativ
pe fiecare linie a documentului B<tradus>, ea operează de fapt pe șirul
intern de date al documentului tradus. Acest șir de date interne poate fi un
text care se întinde pe un paragraf conținând mai multe linii sau poate fi
doar o etichetă XML. I<punctul de inserție> exact al addendumului trebuie să
fie înainte sau după șirul intern de date și nu poate fi în interiorul
șirului intern de date.

=item

Treceți argumentul C<-vv> la B<po4a> pentru a înțelege cum sunt adăugate
addendele la traducere. De asemenea, poate fi util să rulați B<po4a> în
modul de depanare pentru a vedea șirul de date interne reale atunci când
addendumul dvs. nu se aplică.

=back

=head3 Exemple de addenda

=over

=item

Dacă doriți să adăugați ceva după următoarea secțiune nroff:

  .SH "AUTHORS"

Ar trebui să selectați o abordare în doi pași prin definirea
B<mode=after>. Apoi ar trebui să restrângeți căutarea la linia de după
B<AUTHORS> cu expresia regulată a argumentului B<position>. Apoi, ar trebui
să potriviți începutul următoarei secțiuni (și anume, B<^\.SH>) cu expresia
regulată a argumentului B<beginboundary>. Adică:

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

=item

Dacă doriți să adăugați ceva imediat după o anumită linie (de exemplu, după
linia „Drepturi de autor Băiat Deștept”), utilizați un argument B<position>
care corespunde acestei linii, definiți B<mode=after> și dați un
B<beginboundary> care corespunde oricărei linii.

 PO4A-HEADER:mode=after;position=Drepturi de autor Băiat Deștept, 2004;beginboundary=^

=item

Dacă doriți să adăugați ceva la sfârșitul documentului, dați un argument
B<position> care să corespundă oricărei linii din document (dar numai unei
linii. Po4a nu va continua dacă nu este unic) și dați un argument
B<endboundary> care să nu se potrivească cu nimic. Nu folosiți aici șiruri
simple precum B<"EOF">, ci preferați-le pe cele care au mai puține șanse să
se afle în documentul dumneavoastră.

 PO4A-HEADER:mode=after;position=Despre acest document;beginboundary=FakePo4aBoundary

=back

=head3 Un exemplu mai detaliat

Documentul original (formatat POD):

 |=head1 NUME
 |
 |fantoma - un program fictiv
 |
 |=head1 AUTHOR
 |
 |eu_însămi

Apoi, următorul addendum va asigura adăugarea unei secțiuni (în franceză)
despre traducător la sfârșitul dosarului (în franceză, „TRADUCTEUR” înseamnă
„TRADUCĂTOR”, iar „moi” înseamnă „eu”).

 |PO4A-HEADER:mode=after;position=AUTOR;beginboundary=^=head
 |
 |=head1 TRADUCĂTOR
 |
 |eu_însămi
 |

Pentru a plasa addendumul înainte de AUTOR, utilizați următorul antet:

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

Acest lucru funcționează deoarece următoarea linie care se potrivește cu
B<beginboundary> C</^=head1/> după secțiunea „NAME” (tradusă prin „NOM” în
franceză), este cea care declară autorii. Deci, addendumul va fi pus între
cele două secțiuni. Rețineți că, dacă ulterior se adaugă o altă secțiune
între secțiunile „NAME” și „AUTHOR”, po4a va plasa în mod eronat addenda
înaintea noii secțiuni.

Pentru a evita acest lucru, puteți realiza același lucru folosind
B<mode>=I<before>:

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

=head1 Cum funcționează acesta?

Acest capitol vă oferă o scurtă prezentare generală a componentelor interne
ale po4a, astfel încât să vă simțiți mai încrezători și să ne ajutați să îl
menținem și să îl îmbunătățim. De asemenea, vă poate ajuta să înțelegeți de
ce nu face ceea ce vă așteptați și cum să soluționați problemele ce pot
apărea.

=head2 TransTractors și arhitectura proiectului

La baza proiectului po4a, clasa
L<Locale::Po4a::TransTractor(3pm)|TransTractor> este strămoșul comun al
tuturor analizatorilor po4a. Acest nume ciudat provine din faptul că se
ocupă în același timp de traducerea documentelor și de extragerea șirurilor
de caractere.

Mai formal, acesta ia un document de tradus plus un fișier PO care conține
traducerile de utilizat ca intrare, producând în același timp două rezultate
separate: un alt fișier PO (rezultat din extragerea șirurilor traductibile
din documentul de intrare) și un document tradus (cu aceeași structură ca
cel de intrare, dar cu toate șirurile traductibile înlocuite cu conținutul
PO de intrare). Iată o reprezentare grafică a acestui lucru:

   Document intrare --\                             /---> Document ieșire
                       \      TransTractor::       /         (tradus)
                        +-->--   parse()  --------+
                       /                           \
   PO intrare --------/                             \---> PO ieșire
                                                          (extras)

Acest mic os este nucleul întregii arhitecturi „scheletului” po4a. Dacă
furnizați ambele documente de intrare și nu țineți cont de PO de ieșire,
obțineți B<po4a-translate>. Dacă în schimb desconsiderați documentul de
ieșire, obțineți B<po4a-updatepo>. B<po4a> utilizează un prim TransTractor
pentru a obține un fișier POT de ieșire actualizat (fără a ține cont de
documentele de ieșire), apelează la B<msgmerge -U> pentru a actualiza
fișierele PO de traducere de pe disc și construiește un al doilea
TransTractor cu aceste fișiere PO actualizate pentru a actualiza documentele
de ieșire. Pe scurt, B<po4a> oferă o soluție unică pentru a actualiza ceea
ce este necesar, utilizând un singur fișier de configurare.

B<po4a-gettextize> utilizează, de asemenea, două TransTractors, dar într-un
alt mod: Construiește un TransTractor pentru fiecare limbă, iar apoi
construiește un nou fișier PO folosind msgids din documentul original ca
msgids și msgids din documentul tradus ca msgstrs. Este nevoie de multă
atenție pentru a se asigura că șirurile potrivite în acest mod corespund
într-adevăr, după cum se descrie în L<po4a-gettextize(1)>.

=head2 Analizatori specifici formatului

Toți analizatorii de format po4a sunt implementați pe partea de sus a
TransTractor. Unii dintre ei sunt foarte simpli, cum ar fi cei Text,
Markdown și AsciiDoc. Aceștia încarcă liniile una câte una folosind
C<TransTractor::shiftline()>, acumulează conținutul paragrafelor sau orice
altceva. Odată ce un șir de caractere este complet analizat, analizatorul
utilizează C<TransTractor::translate()> pentru (1) a adăuga acest șir la
fișierul PO de ieșire și (2) pentru a obține traducerea din fișierul PO de
intrare. Analizatorul apoi introduce rezultatul în fișierul de ieșire
utilizând C<TransTractor::pushline()>.

Alți analizatori sunt mai complecși deoarece se bazează pe un analizator
extern pentru a analiza documentul de intrare. Analizatorii Xml, HTML, SGML
și Pod sunt construiți pe baza analizatorilor SAX. Aceștia declară reapeluri
la evenimente precum „Am găsit un titlu nou al cărui conținut este
următorul” pentru a actualiza documentul de ieșire și fișierele POT de
ieșire în funcție de conținutul de intrare utilizând
C<TransTractor::translate()> și C<TransTractor::pushline()>. Analizatorul
Yaml este similar, dar diferit: acesta serializează o structură de date
produsă de analizatorul YAML::Tiny. Acesta este motivul pentru care modulul
Yaml din po4a nu reușește să declare liniile de referință: locația fiecărui
șir de caractere din fișierul de intrare nu este păstrată de analizator,
astfel încât nu putem furniza decât „$filename:1” ca locație a
șirului. Analizatorii orientați pe SAX utilizează caractere joker și alte
trucuri pentru a salva numele fișierului și numerele de linie ale
referințelor.

O problemă specifică provine din codificarea fișierelor și marcatorii
BOM. Analizatorii simpli pot uita de această problemă, care este tratată de
C<TransTractor::read()> (utilizat intern pentru a obține liniile unui
document de intrare), dar modulele care se bazează pe un analizator extern
trebuie să se asigure că toate fișierele sunt citite cu un strat de
decodificare PerlIO adecvat. Cel mai simplu este să deschideți chiar
dvs. fișierul și să furnizați un identificator de fișier sau direct șirul
complet analizatorului dvs. extern. Consultați C<Pod::read()> și
C<Pod::parse()> pentru un exemplu. Conținutul citit de TransTractor este
ignorat, dar un identificator de fișier nou este transmis analizatorului
extern. Partea importantă este modul C<< "<:encoding($charset)" >> care este
transmis funcției perl B<open()>.

=head2 Obiecte PO

Clasa L<Locale::Po4a::Po(3pm)|Po> este responsabilă de încărcarea și
utilizarea fișierelor PO și POT. Practic, puteți citi un fișier, adăuga
intrări, obține traduceri cu metoda B<gettext()>, scrie PO într-un
fișier. Funcțiile mai avansate, cum ar fi fuzionarea unui fișier PO cu un
fișier POT sau validarea unui fișier, sunt delegate către B<msgmerge> și,
respectiv, B<msgfmt>.

=head2 Contribuind la po4a

Chiar dacă nu ați contribuit niciodată în trecut la vreun proiect Open
Source, sunteți binevenit: suntem dispuși să vă ajutăm și să vă îndrumăm
aici. po4a este cel mai bine întreținut de utilizatorii săi în zilele
noastre. Deoarece nu dispunem de personal, încercăm să facem proiectul
primitor prin îmbunătățirea documentației și a testelor automate pentru a vă
face încrezători în contribuția la proiect. Vă rugăm să consultați fișierul
CONTRIBUTING.md pentru mai multe detalii.

=head1 Proiecte cu cod-sursă deschis „open-source” care utilizează po4a

Iată o listă foarte parțială a proiectelor care utilizează po4a în producție
pentru documentația lor. Dacă doriți să vă adăugați proiectul la listă,
trimiteți-ne un e-mail (sau o cerere de îmbinare „merge request”).

=over

=item

adduser (man): instrument de gestionare a utilizatorilor și a grupurilor.

=item

apt (man, docbook): Gestionarul de pachete Debian.

=item

aptitude (docbook, svg): gestionar de pachete bazat pe terminal pentru
Debian

=item

L<F-Droid website|https://gitlab.com/fdroid/fdroid-website> (markdown):
catalog instalabil de aplicații de software liber și cod-sursă deschis
(„Free and Open Source Software”: FOSS) pentru platforma Android.

=item

L<git|https://github.com/jnavila/git-manpages-l10n> (asciidoc): sistem
distribuit de control al versiunilor pentru urmărirea modificărilor în codul
sursă.

=item

L<Linux manpages|https://salsa.debian.org/manpages-l10n-team/manpages-l10n>
(pagini de manual)

Acest proiect oferă o infrastructură pentru traducerea multor pagini de
manual în diferite limbi, gata de integrare în câteva distribuții majore
(Arch Linux, Debian, Fedora, Mageia, openSUSE și derivatele acestora).

=item

L<Stellarium|https://github.com/Stellarium/stellarium> (HTML): un planetariu
cu cod-sursă deschis, gratuit pentru calculatorul dumneavoastră. po4a este
utilizat pentru a traduce descrierile obiectelor cerești.

=item

L<Jamulus|https://jamulus.io/> (markdown, yaml, HTML): o aplicație FOSS
pentru bruiaj în linie în timp real. Documentația sitului web este menținută
în mai multe limbi utilizând po4a.

=item

Alt element de rezolvat: L<https://gitlab.com/fdroid/fdroid-website/>
L<https://github.com/fsfe/reuse-docs/pull/61>

=back

=head1 Întrebări și răspunsuri frecvente

=head2 Cum se pronunță po4a?

Eu personal o vocalizez ca L<pouah|https://en.wiktionary.org/wiki/pouah>,
care este o onomatopee franceză pe care o folosim în loc de expresie de
dezgust :) Poate că am un simț al umorului ciudat :)

=head2 De ce sunt depreciate scripturile individuale?

Într-adevăr, B<po4a-updatepo> și B<po4a-translate> sunt depreciate în
favoarea lui B<po4a>. Motivul este că, deși B<po4a> poate fi utilizat ca
înlocuitor al acestor scripturi, există destul de multe duplicații de cod
aici. Scripturile individuale au în jur de 150 de linii de cod, în timp ce
programul B<po4a> are 1200 de linii, astfel încât acestea fac multe lucruri
în plus față de elementele interne comune. Duplicarea codului duce la
apariția unor erori în ambele versiuni și la necesitatea a două
remedieri. Un exemplu de astfel de duplicare sunt bug-urile #1022216 din
Debian și problema #442 din GitHub care au avut exact același remediu, dar
unul în B<po4a> și celălalt B<po4a-updatepo>.

Pe termen lung, aș dori să renunț la scripturile individuale și să mențin o
singură versiune a acestui cod. Lucrul sigur este că scripturile individuale
nu vor mai fi îmbunătățite, astfel încât doar B<po4a> va beneficia de noile
caracteristici. Acestea fiind spuse, nu există nicio urgență de
depreciere. Intenționez să păstrez scripturile individuale cât de mult
posibil și cel puțin până în 2030. Dacă proiectul dvs. utilizează încă
B<po4a-updatepo> și B<po4a-translate> în 2030, s-ar putea să aveți o
problemă.

De asemenea, am putea elimina deprecierea acestor scripturi la un moment
dat, dacă o refactorizare reduce duplicarea codului la zero. Dacă aveți o
idee (sau mai bine: un plasture „patch” :)), ajutorul dvs. este binevenit.

=head2 Ce se întâmplă cu celelalte instrumente de traducere pentru documentație
care utilizează gettext?

Există câteva dintre ele. Iată o listă posibil incompletă, și multe alte
instrumente apar la orizont.

=over

=item B<poxml>

Acesta este instrumentul dezvoltat de cei de la KDE pentru a gestiona
DocBook XML. AFAIK, a fost primul program care a extras șiruri de caractere
pentru a le traduce din documentație în fișiere PO și le-a injectat înapoi
după traducere.

Poate gestiona doar XML și doar un anumit DTD. Sunt destul de nemulțumit de
gestionarea listelor, care se termină cu un msgid mare. Când lista devine
mare, fragmentul devine mai greu de înghițit.

=item B<po-debiandoc>

Acest program realizat de Denis Barbier este un fel de precursor al
modulului SGML po4a, care îl depreciază mai mult sau mai puțin. După cum
spune și numele, acesta gestionează doar DTD-ul DebianDoc, care este mai
mult sau mai puțin un DTD depreciat.

=item B<xml2po.py>

Folosit de echipa de documentare GIMP din 2004, funcționează destul de bine,
chiar dacă, după cum sugerează și numele, funcționează doar cu fișiere XML
și are nevoie de fișiere makefile configurate special.

=item B<Sphinx>

Proiectul de documentare Sphinx utilizează, de asemenea, gettext în mod
extensiv pentru a-și gestiona traducerile. Din păcate, acesta funcționează
doar pentru câteva formate de text, rest și markdown, deși este probabil
singurul instrument care gestionează întregul proces de traducere.

=back

Principalele avantaje ale po4a față de acestea sunt ușurința de a adăuga
conținut suplimentar (care este chiar mai rău acolo) și capacitatea de a
realiza gettextizarea.

=head2 REZUMAT al avantajelor abordării bazate pe gettext

=over 2

=item

Traducerile nu sunt stocate împreună cu originalul, ceea ce face posibilă
detectarea dacă traducerile devin neactualizate.

=item

Traducerile sunt stocate în fișiere separate unele de altele, ceea ce
previne interferența între traducătorii din limbi diferite, atât atunci când
își trimit modificările, cât și la nivelul codificării fișierelor.

=item

Acesta se bazează intern pe B<gettext> (dar B<po4a> oferă o interfață foarte
simplă, astfel încât nu trebuie să înțelegeți elementele interne pentru a-l
utiliza). În acest fel, nu trebuie să reinventăm roata și, datorită
utilizării lor pe scară largă, putem crede că aceste instrumente sunt mai
mult sau mai puțin lipsite de erori.

=item

Nu s-a schimbat nimic pentru utilizatorul final (în afară de faptul că
traducerile vor fi, sperăm, mai bine întreținute). Fișierul de documentație
rezultat distribuit este exact același.

=item

Nu este nevoie ca traducătorii să învețe o nouă sintaxă de fișier, iar
editorul lor preferat de fișiere PO (cum ar fi modul PO din Emacs, Lokalize
sau Gtranslator) va funcționa foarte bine.

=item

gettext oferă o modalitate simplă de a obține statistici despre ceea ce este
făcut, ceea ce ar trebui revizuit și actualizat și ceea ce mai este de
făcut. Unele exemple pot fi găsite la aceste adrese:

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

=back

Dar nu totul este „în roz”, iar această abordare are și unele dezavantaje cu
care trebuie să ne confruntăm.

=over 2

=item

Addenda este oarecum ciudată la prima vedere.

=item

Nu puteți adapta textul tradus la preferințele dvs., cum ar fi divizarea
unui paragraf aici și unirea altor două acolo. Dar, într-un anumit sens,
dacă există o problemă cu originalul, aceasta ar trebui oricum raportată ca
eroare.

=item

Chiar și cu o interfață ușoară, acesta rămâne un instrument nou pe care
oamenii trebuie să îl învețe.

Unul dintre visele mele ar fi să integrez cumva po4a la Gtranslator sau
Lokalize. Când se deschide un fișier de documentație, șirurile de caractere
sunt extrase automat, iar un fișier tradus + fișier po poate fi scris pe
disc. Dacă reușim să facem un modul MS Word (TM) (sau cel puțin RTF),
traducătorii profesioniști ar putea chiar să-l folosească.

=back

=head1 CONSULTAȚI ȘI

=over

=item

Documentația instrumentului „totul în unul” pe care ar trebui să o
utilizați: L<po4a(1)> ;).

=item

Documentația scripturilor individuale po4a: L<po4a-gettextize(1)>,
L<po4a-updatepo(1)>, L<po4a-translate(1)>, L<po4a-normalize(1)>.

=item

Scripturile de ajutor suplimentare: L<msguntypot(1)>,
L<po4a-display-man(1)>, L<po4a-display-pod(1)>.

=item

Analizatorii fiecărui format, în special pentru a vedea opțiunile acceptate
de fiecare dintre ei: L<Locale::Po4a::AsciiDoc(3pm)>
L<Locale::Po4a::Dia(3pm)>, L<Locale::Po4a::Gemtext(3pm)>,
L<Locale::Po4a::Guide(3pm)>, L<Locale::Po4a::Ini(3pm)>,
L<Locale::Po4a::KernelHelp(3pm)>, L<Locale::Po4a::Man(3pm)>,
L<Locale::Po4a::RubyDoc(3pm)>, L<Locale::Po4a::Texinfo(3pm)>,
L<Locale::Po4a::Text(3pm)>, L<Locale::Po4a::Xhtml(3pm)>,
L<Locale::Po4a::Yaml(3pm)>, L<Locale::Po4a::BibTeX(3pm)>,
L<Locale::Po4a::Docbook(3pm)>, L<Locale::Po4a::Halibut(3pm)>,
L<Locale::Po4a::LaTeX(3pm)>, L<Locale::Po4a::Org(3pm)>,
L<Locale::Po4a::Pod(3pm)>, L<Locale::Po4a::SimplePod(3pm)>,
L<Locale::Po4a::Sgml(3pm)>, L<Locale::Po4a::TeX(3pm)>,
L<Locale::Po4a::VimHelp>, L<Locale::Po4a::Wml(3pm)>,
L<Locale::Po4a::Xml(3pm)>.

=item

Implementarea infrastructurii de bază: L<Locale::Po4a::TransTractor(3pm)>
(deosebit de important pentru a înțelege organizarea codului),
L<Locale::Po4a::Chooser(3pm)>, L<Locale::Po4a::Po(3pm)>,
L<Locale::Po4a::Common(3pm)>. Vă rugăm să verificați și fișierul
F<CONTRIBUTING.md> din arborele codului sursă.

=back

=head1 AUTORI

 Denis Barbier <barbier,linuxfr.org>
 Martin Quinson (mquinson#debian.org)
