Provided by: po4a_0.41-1ubuntu1_all bug

NOM

       po4a - marc de treball per traduir documentació i d'altre material

Introducció

       L'objectiu del projecte po4a (PO per a tot) és facilitar la traducció (i sobretot el
       manteniment de les traduccions) utilitzant les eines de gettext en àrees on no eren
       d'esperar, com ara en la documentació.

Taula de continguts

       Aquest document està organitzat d'aquesta forma:

       1 Per què he d'utilitzar po4a? Per a què serveix?
           Aquest capítol introductori explica la motivació del projecte i la seva filosofia.
           Hauria de llegir-lo primer si està en el procés d'avaluació de po4a per a les seves
           pròpies traduccions.

       2 Com fer servir po4a?
           Aquest capítol és com un manual de referència on s'intenten contestar les preguntes
           dels usuaris, i se'ls ofereix una idea general del procés. Això introdueix a la forma
           de fer les coses amb po4a i serveix com a documentació introductòria de les eines
           específiques.

           Com començar una nova traducció?
           Com es transforma la traducció de tornada a un arxiu de documentació?
           Com actualitzar una traducció amb po4a?
           Com convertir una traducció pre-existent a po4a?
           Com afegir text extra a la traducció (com ara el nom del traductor)?
           Com fer tot això en una sola invocació al programa?
           HOWTO customize po4a?
       3 Com funciona?
           Aquest capítol ofereix una breu explicació del funcionament intern de po4a, de manera
           que es pugui sentir més segur per ajudar-nos a mantenir-lo i a millorar-lo. També el
           pot ajudar a entendre perquè no fa el què esperava, i com solucionar problemes.

       4 PMF
           Aquest capítol agrupa les Preguntes Més Freqüents. De fet, la majoria de preguntes
           actuals es poden formular d'aquesta manera: "Per què s'ha dissenyat d'aquesta forma i
           no d'una altra?" Si pensa que po4a no és la solució ideal per a la traducció de
           documentació, hauria de considerar llegir-se aquesta secció. Si no respon les seves
           preguntes, contacti amb nosaltres a la llista de correu
           <po4a-devel@lists.alioth.debian.org>. Volem saber la seva opinió.

       5 Notes específiques dels mòduls
           Aquest capítol presenta els punts específics de cada mòdul ja sigui des del punt de
           vista del traductor com des del de l'autor original. Llegeixi això per aprendre la
           sintaxi que es trobarà quan tradueixi textos amb un mòdul, o les regles que ha de
           seguir en el document original per facilitar la vida del traductor.

           Actualment, aquesta secció no forma part d'aquest document. En realitat, això es troba
           a la documentació de cada mòdul. Així s'ajuda a assegurar que la informació estigui
           actualitzada al mantenir la documentació i el codi junts.

Per què he d'utilitzar po4a? Per a què serveix?

       M'agrada la idea del programari de codi obert, cosa que fa possible que tot el món pugui
       accedir al programari i al seu propi codi font. Però al ser Francès, sóc ben conscient que
       la llicència no és la única restricció de la llibertat del programari: Els programes
       lliures no traduïts són inservibles per als qui no són de parla anglesa, i encara queda
       força feina per fer-los disponibles a tothom.

       La percepció d'aquesta situació pels responsables del programari lliure ha millorat
       dràsticament recentment. Nosaltres, com a traductors, hem guanyat la primera batalla i hem
       convençut a tot al món de la importància de les traduccions. Però per desgràcia, aquesta
       era la part fàcil. Ara hem de posar-nos en marxa i començar a traduir.

       Actualment el programari lliure es beneficia d'un nivell decent de traducció, gràcies al
       meravellós paquet d'eines gettext. Aquest pot extreure les cadenes a traduir d'un
       programa, presentar-les en un format uniforme als traductors, i després utilitzar el
       resultat del seu treball en temps d'execució per mostrar els missatges traduïts a
       l'usuari.

       Però la situació és bastant diferent pel que fa a la documentació. Molt sovint, la
       documentació traduïda no és suficientment visible (no es distribueix com a part del
       programa), només parcialment, o no està actualitzada. La darrera situació és la pitjor de
       totes. Per als usuaris, les traduccions antiquades poden ser pitjors que si no existís la
       traducció, si descriuen vells comportaments del programa que ja no s'utilitzen.

   El problema a solucionar
       Traduir documentació per sí sola no és molt difícil. Els textos són bastant més llargs que
       els missatges de programa, i per tant, tarden més a traduir-se. De tota manera, no es
       necessiten coneixements tècnics fer fer-ho. La part més difícil arriba quan la feina s'ha
       de mantenir. Detectar quines parts han canviat i necessiten ser actualitzades és molt
       difícil, ja que comporta errors desagradables. Crec que això explica per què tantes de les
       traduccions que hi ha escampades pel món estan antiquades.

   Les respostes de po4a
       Per tant, l'objectiu de po4a es fer mantenible la traducció de la documentació. La idea és
       reutilitzar la metodologia de gettext en aquest nou camp. Com en gettext, s'extreuen els
       textos del lloc original per tal de presentar-los als traductors en un format uniforme.
       Les eines clàssiques de gettext ajuden a mantenir la feina actualitzada quan surt una nova
       versió de l'original. Però a diferència del model clàssic de gettext, les traduccions es
       re-injecten a l'estructura del document original, de forma que poden ser processades i
       distribuïdes igual que la versió anglesa.

       Gràcies a això, és més fàcil descobrir quines parts del document han canviat i necessiten
       ser actualitzades. Un altre punt fort és que les eines faran pràcticament tota la feina
       quan l'estructura del document original es torni a organitzar i quan alguns capítols es
       moguin, s'ajuntin o se separin. Al extreure el text a traduir de l'estructura del
       document, també el manté lluny de la complexitat del formateig de text i redueix les
       oportunitats de danyar el document (encara que no li impedeixin completament de fer-ho).

       Si us plau, llegeixi també les PMF més avall en aquest document per a una llista més
       completa d'avantatges i desavantatges d'aquesta solució.

   Formats suportats
       Actualment, s'ha implementat satisfactòriament aquesta aproximació en alguns formats de
       text:

       man

       The good old manual pages' format, used by so much programs out there. The po4a support is
       very welcome here since this format is somewhat difficult to use and not really friendly
       to the newbies.  The Locale::Po4a::Man(3pm) module also supports the mdoc format, used by
       the BSD man pages (they are also quite common on Linux).

       pod

       Aquest és el format de Documentació Online de Perl. El llenguatge i les seves mateixes
       extensions estan documentades així, igual que la majoria de guions de Perl. Al barrejar-lo
       en el mateix fitxer és més fàcil mantenir la documentació propera al codi actual. Facilita
       la vida del programador, però per desgràcia, no la del traductor.

       sgml

       Encara que avui en dia gairebé hagi estat substituït per XML, aquest format encara
       s'utilitza habitualment per documents més extensos que algunes pantalles. Aquest permet
       fer llibres complets. Actualitzar una traducció de documents tan llargs pot ser realment
       un malson. Sovint diff es torna inservible quan s'ha reindentat el text original després
       de l'actualització. Afortunadament, po4a el pot ajudar en aquest procés.

       Actualment, només suporta els DTD de DebianDoc i de DocBook, però és realment fàcil afegir
       suport per alguns de nous. Fins i tot, és possible utilitzar po4a en un DTD desconegut de
       SGML sense canviar el codi, passant la informació necessària a la línia de comandes.
       Consulti <Locale::Po4a::Sgml(3pm)> per a més detalls.

       TeX / LaTeX

       The LaTeX format is a major documentation format used in the Free Software world and for
       publications.  The Locale::Po4a::LaTeX(3pm) module was tested with the Python
       documentation, a book and some presentations.

       texinfo

       All the GNU documentation is written in this format (that's even one of the requirement to
       become an official GNU project).  The support for Locale::Po4a::Texinfo(3pm) in po4a is
       still at the beginning.  Please report bugs and feature requests.

       xml

       The XML format is a base format for many documentation formats.

       Currently, the DocBook DTD is supported by po4a. See Locale::Po4a::Docbook(3pm) for
       details.

       altres

       Po4a també pot tractar algus formats estranys o específics, de la mateixa manera que la
       documentació de les opcions de compilació del kernel 2.4.x o els diagrames produïts per
       l'eina dia. Afegir-ne un de nou sol ser una tasca molt fàcil i la tasca principal és
       aconseguir un analitzador pel seu format. Consulti Locale::Po4a::TransTractor(3pm) per més
       informació.

   Formats no suportats
       Unfortunately, po4a still lacks support for several documentation formats.

       There is a whole bunch of other formats we would like to support in po4a, and not only
       documentation ones. Indeed, we aim at plugging all "market holes" left by the classical
       gettext tools.  It encompass package descriptions (deb and rpm), package installation
       scripts questions, package changelogs, and all specialized file formats used by the
       programs such as game scenarios or wine resource files.

Com fer servir po4a?

       Aquest capítol és com un manual de referència on s'intenten contestar les preguntes dels
       usuaris, i se'ls ofereix una idea general del procés. Això introdueix a la forma de fer
       les coses amb po4a i serveix com a documentació introductòria de les eines específiques.

   Visió esquemàtica
       The following schema gives an overview of the process of translating documentation using
       po4a. Do not be afraid by its apparent complexity, it comes from the fact that the whole
       process is represented here. Once you converted your project to po4a, only the right part
       of the graphic is relevant.

       Note that master.doc is taken as an example for the documentation to be translated and
       translation.doc is the corresponding translated text.  The suffix could be .pod, .xml, or
       .sgml depending on its format. Each part of the picture will be detailed in the next
       sections.

                                          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-updatepo]                  |
                 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-translate]
                                                         |
                                                         V
                                                       XX.doc
                                                   (up-to-date)

       A la part esquerra s'hi mostra la conversió d'una traducció que no utilitza po4a a aquest
       sistema. A dalt de la part dreta s'hi representa l'acció de l'autor original (actualitzar
       la documentació). Al mig de la part dreta s'hi simbolitzen les accions automàtiques de
       po4a. S'extrau el nou material i es compara amb la traducció existent. Es troben les parts
       que no han canviat, i es fa servir la traducció prèvia. Les parts parcialment modificades
       també es connecten a la traducció anterior, però se li afegeix un marcador indicant que la
       traducció s'ha d'actualitzar. La part de baix de la figura mostra com es construeix el
       document formatejat.

       Actualment, com a traductor, la única operació manual que hauria de fer-se és la part
       marcada {edició manual}. Sí, ho sento, però po4a ajuda a traduir. No tradueix res sol...

   Com començar una nova traducció?
       Aquesta secció presenta els passos necessaris per començar una nova traducció amb po4a.
       Els refinaments involucrats a la conversió d'un projecte existent al d'aquest sistema es
       detallen a la secció pertinent.

       Per començar una nova traducció utilitzant po4a, ha de seguir els següents passos:

       - Extract the text which have to be translated from the original <master.doc> document
         into a new translation template <translation.pot> file (the gettext format). For that,
         use the po4a-gettextize program this way:

           $ po4a-gettextize -f <format> -m <principal.doc> -p <traducció.pot>

         <format> is naturally the format used in the master.doc document. As expected, the
         output goes into translation.pot.  Please refer to po4a-gettextize(1) for more details
         about the existing options.

       - Ara toca traduir el que toca. Per això, canviï el nom del fitxer POT a doc.XX.po, per
         exemple (on XX és el codi ISO639 de l'idioma al que estigui traduint, per exemple fr pel
         francès), i editi el fitxer resultant. Sovint és bona idea no anomenar el fitxer XX.po
         per evitar confusions amb la traducció dels missatges de programa però això és cosa
         seva. No s'oblidi d'actualitzar les capçaleres dels fitxers PO, són importants.

         La traducció en qüestió es pot fer amb el mode PO d'Emacs o Lokalize (basat en KDE) o
         Granslator (basat en GNOME), o qualsevol programa que prefereixi. Fins i tot el clàssic
         vi pot servir, encara que no tingui un mode especialitzat per aquesta tasca.

         Si desitja aprendre més, definitivament ha de consultar la documentació de gettext,
         disponible en el paquet gettext-doc.

   Com es transforma la traducció de tornada a un arxiu de documentació?
       Un cop hagi acabat la traducció, voldrà obtenir la documentació traduïda i distribuir-la
       als usuaris junt amb l'original.  Per fer-ho, utilitzi el programa po4a-translate(1) així
       (on XX és el codi de l'idioma):

         $ po4a-translate -f <format> -m <principal.doc> -p <doc-XX.po> -l <XX.doc>

       Igual que abans, <format> és el format utilitzat en el principal.doc. Però aquest cop el
       fitxer PO passat amb el paràmetre -p és part de l'entrada. Aquesta és la seva traducció.
       La sortida va a XX.doc.

       Consulti po4a-translate(1) per més detalls.

   Com actualitzar una traducció amb po4a?
       To update your translation when the original master.doc file has changed, use the
       po4a-updatepo(1) program like that:

         $ po4a-updatepo -f <format> -m <nou_original.doc> -p <existent.XX.po>

       (Consulti po4a-updatepo(1) per més detalls)

       Naturalment, el nou paràgraf del document no es traduirà màgicament al fitxer PO amb
       aquesta operació, i necessitarà actualitzar l'arxiu PO manualment. Tanmateix, pot haver de
       refer les traduccions dels paràgrafs que s'hagin modificat una mica. Per assegurar que no
       s'oblidi de cap, es marquen com a "difuses" durant el procés, i s'haurà de treure la marca
       abans que pugui utilitzar la traducció a po4a-translate. De la mateixa manera que per a la
       traducció inicial, aquí és millor fer servir el seu editor PO preferit.

       Un cop el seu fitxer PO estigui altra vegada actualitzat, sense cap cadena per traduir ni
       cadenes difuses, pot generar el fitxer de documentació traduït, tal i com s'ha explicat a
       la secció anterior.

   Com convertir una traducció pre-existent a po4a?
       Often, you used to translate manually the document happily until a major reorganization of
       the original master.doc document happened. Then, after some unpleasant tries with diff or
       similar tools, you want to convert to po4a.  But of course, you don't want to loose your
       existing translation in the process. Don't worry, this case is also handled by po4a tools
       and is called gettextization.

       La gràcia està en que tant el document traduït com l'original tinguin la mateixa
       estructura de manera que les eines puguin encaixar els continguts correctament.

       Si està de sort (és a dir, si les estructures dels documents encaixen a la perfecció), tot
       funcionarà correctament i haurà acabat en pocs segons. En cas contrari, haurà d'entendre
       per què aquest procés té un nom tan espantós, i hauria d'estar preparat per a una mica de
       feina de grunyits. De totes maneres, recordi que aquest és el preu que ha de pagar per
       aconseguir després la comoditat de po4a. I la part bona és que només haurà de fer-ho una
       vegada.

       No puc emfatitzar-ho més. Per facilitar el procés, és important trobar la versió exacta
       que es va utilitzar a la traducció. La millor situació és dóna quan es va anotar quina
       revisió del VCS es va fer servir per a la traducció i no es va modificar durant el procés
       de traducció, de manera que la pugui utilitzar.

       No funcionarà bé si utilitza el text original actualitzat amb la traducció antiga. És un
       procés possible, però més difícil, i realment s'ha d'evitar sempre que sigui possible. De
       fet, imagino que si no aconsegueix trobar el text original, la millor solució és trobar a
       algú que faci la gettextització per vostè (però jo no, si us plau ;).

       Potser sóc massa catastrofista. Per molt que les coses vagin malament, segueix sent molt
       més ràpid que traduir-ho tot altra vegada. Jo vaig fer la gettextització de la traducció
       al francès existent de la documentació de Perl en un dia, encara que les coses van anar
       malament. Eren més de dos megabytes de text, i una traducció nova hagués pogut durar mesos
       com a mínim.

       Let me explain the basis of the procedure first and I will come back on hints to achieve
       it when the process goes wrong. To ease comprehension, let's use above example once again.

       Once you have the old master.doc again which matches with the translation XX.doc, the
       gettextization can be done directly to the PO file doc.XX.po without manual translation of
       translation.pot file:

        $ po4a-gettextize -f <format> -m <old_master.doc> -l <XX.doc> -p <doc.XX.po>

       Si està de sort, això és tot. Ha convertit la seva antiga traducció a po4a i ja pot
       començar amb la tasca d'actualització. Simplement segueixi el procés explicat unes
       seccions abans per sincronitzar el seu arxiu PO amb el document original més nou, i
       actualitzi la traducció segons convingui.

       Tingui en compte que, encara que tot sembli haver anat bé, encara es poden produir alguns
       errors en aquest procés. Això és degut a que po4a no és capaç d'entendre el text per
       assegurar-se que la traducció es refereix a l'original. És per això que les cadenes es
       marquen com a "difuses" durant el procés. Haurà de comprovar cuidadosament cada cadena
       abans d'eliminar la marca.

       Sovint, les estructures dels documents no encaixen a la perfecció, impedint a
       po4a-gettextize realitzar la seva tasca. Arribat a aquest punt, tot el joc es trasllada a
       la edició dels fitxers per fer encaixar les seves maleïdes estructures.

       El pot ajudar llegir la secció Gettextització: com funciona? de més avall. La comprensió
       del funcionament intern del procés l'ajudarà a fer-lo funcionar. El milor és que
       po4a-gettextize dóna molta informació quan alguna cosa no ha anat bé. Primer, apuntarà on
       s'ha trobat la discrepància d'estructures en els documents. Després mostrarà les cadenes
       que no encaixen, la seva posició en el text, i el tipus de cadascuna. A més a més, el
       fitxer PO generat fins al moment es guardarà a gettextization.failed.po.

       -   Borreu totes les parts extres de les traduccions, com per exemple la secció on
           s'especifiqui el nom del traductor, o els agraïments de gent que ha col·laborat a la
           traducció. Els apèndix, descrits a la següent secció, li permetran afegir de nou
           aquests continguts.

       -   No dubti a editar tant l'original com la traducció. El més important és aconseguir el
           fitxer PO. Ja tindrà temps d'actualitzar-lo més tard. Un cop dit això, és preferible
           editar la traducció quan es puguin editar els dos, ja que això facilita les coses un
           cop s'acabi la gettextització.

       -   Si fa falta, si algunes parts no estaven traduïdes, elimini-les de l'original. Quan
           més endavant sincronitzi el fitxer PO, tornaran a apareixer per sí soles.

       -   Si ha canviat una mica l'estructura (per ajuntar dos paràgrafs, o partir-ne algun),
           desfaci els canvis. Si hi ha problemes amb l'original, hauria d'informar l'autor
           original. Arreglar-ho a la traducció només ho arregla per una part de la comunitat. I
           a més, és impossible quan utilitza po4a ;)

       -   A vegades el contingut del paràgraf encaixa, però el seu tipus no. Arreglar això depèn
           molt del format. En POD i man, a vegades és culpa de que una de les dues línies
           comença amb espai i l'altra no. En aquests formats, aquest paràgraf no podria
           justificar-se i es tornaria d'un tipus diferent. Simplement elimini l'espai per
           solucionar-ho. També pot tractar-se d'un error tipogràfic al nom del tag.

           A més a més, dos paràgrafs poden ajuntar-se en el POD quan la línea de separació conté
           alguns espais, o quan no hi ha una línia de separació abans de la línia =item i del
           contingut de l'element.

       -   A vegades, hi ha una desincronització entre els fitxers, i la traducció s'encaixa a un
           paràgraf original equivocat. Aquest és un signe de que realment ja hi havia un
           problema abans. Comprovi gettextization.failed.po per veure quan comença la
           desincronització, i arreglar-ho allà.

       -   A vegades li pot donar la impressió que po4a s'ha menjat algunes parts del text, ja
           sigui de l'original o de la traducció. gettextization.failed.po indica que ambdós
           encaixaven correctament, i després ha fallat perquè intentava encaixar un paràgraf amb
           l'anterior o el posterior al correcte, com si el correcte hagués desaparegut. Maleeixi
           po4a com jo vaig fer el primer cop que em va passar. Abundantment.

           Aquesta situació és deguda a que el mateix paràgraf es repeteix al llarg del document.
           En aquest cas, no es crea una nova entrada al fitxer PO, sinó que se li afegeix una
           nova referència i la ja existent.

           Per tant, quan el mateix paràgraf apareix dos cops a l'original però no està traduït
           exactament igual cada cop, tindrà la sensació que ha desaparegut un paràgraf de
           l'original. Simplement elimini la nova traducció. Si creu que la segona traducció és
           millor, tregui-la d'on està, i substitueixi-la a la primera.

           En el cas contrari, si hi ha dos paràgrafs semblants però diferents que es van traduir
           de la mateixa forma, li pot donar la impressió que ha desaparegut un paràgraf de la
           traducció. La solució és afegir una cadena estúpida al paràgraf original (quelcom com
           "sóc diferent") per solucionar-ho. No s'espanti. Aquestes coses desapareixeran durant
           la sincronització, i quan el text afegit sigui suficientment curt, gettext encaixarà
           la seva traducció amb el text existent (marcant-lo com a difús, però no importa, ja
           que totes les cadenes es marquen com a difuses durant la gettextització).

       Amb una mica de sort, aquests trucs l'ajudaran a realitzar la seva gettextització i a
       obtenir el seu estimat fitxer PO. Ara estarà preparat per sincronitzar el seu fitxer i
       començar la traducció. Tingui en compte, que en textos grans, la primera sincronització
       pot tardar força temps.

       Per exemple, el primer po4a-updatepo de la traducció al francès de la documentació de Perl
       (un fitxer PO de 5.5Mb) va tardar dos dies aproximadament en una màquina G5 a 1Ghz. Sí, 48
       hores, però les següents vegades tan sols tardava una dotzena de segons al meu portàtil
       vell. Això és perquè la primera vegada, la majoria de msgids del fitxer PO no encaixen amb
       cap altre dels del fitxer POT. Això obliga a gettext a buscar la cadena més semblant
       utilitzant un costós algorisme de proximitat de cadenes.

   Com afegir text extra a la traducció (com ara el nom del traductor)?
       Degut a l'ús de gettext, fer-ho amb po4a és torna més difícil que abans, ja que simplement
       s'editava el nou fitxer paral·lelament a l'original. Però segueix sent possible gràcies
       als anomenats apèndixs.

       Per ajudar a la comprensió, consideri els apèndix com uns pegats aplicats al document
       traduït després del procés. Són bastant diferents que els pegats originals (només tenen
       una línia de context, que pot incloure una expressió regular de Perl, i únicament pot
       afegir text, sense eliminar res), però les funcionalitats són les mateixes.

       El seu objectiu és permetre al traductor afegir contingut extra al document, que no és
       traducció del document original. L'ús més habitual és afegir una secció sobre la traducció
       en si mateixa, llistant els col·laboradors i explicant com informar dels errors de la
       traducció.

       Els apèndixs s'han de proporcionar com fitxers a part. La primera línia forma una
       capçalera que indica el lloc del document resultant on s'ha de col·locar. La resta del
       fitxer d'apèndix s'afegirà sense modificacions a la posició determinada del document
       resultant.

       La capçalera té una sintaxi molt rígida: ha de començar amb la cadena PO4A-HEADER:,
       seguida per una llista de camps clau=valor separats per punt i coma (;). Els espais en
       blanc SÓN importants. Tingui en compte que no pot usar el caracter punt i coma (;) en els
       valors, i que les cometes no ajuden.

       Una vegada més, sona espantós, però els exemples de més endavant haurien d'ajudar-lo a
       trobar la forma d'escriure la línia de capçalera que necessiti. Per a il·lustrar la
       discussió, suposi que vol afegir una secció anomenada "Sobre aquesta traducció" després de
       l'anomenada "Sobre aquest document".

       Aquí hi ha les possibles claus de capçalera:

       position (obligatòria)
           una expressió regular. Es col·locarà l'apèndix prop de la línia que encaixi amb
           aquesta expressió regular. Tingui en compte que estem parlant del document traduït, no
           l'original. Si hi ha més d'una línia que encaixi (o cap), l'addició fallarà. Sempre és
           millor donar un error que inserir l'apèndix en el lloc equivocat.

           Aquesta línia es diu punt de posició a partir d'ara. El punt on s'inserirà l'apèndix
           es diu punt d'inserció. Aquests dos punts són molt propers, però no iguals. Per
           exemple, si desitja inserir una nova secció, és més fàcil posar el punt de posició en
           el títol de la secció anterior, i explicar-li a po4 on acaba la secció (recordi que el
           punt de posició ve donat per l'expressió regular, que ha d'encaixar una única línia).

           La localizació del punt d'inserció respecte el punt de posició està controlat pels
           camps mode, beginboundary i endboundary, que s'expliquen a continuació.

           En el nostre cas tindríem:

                position=<title>Sobre aquest document</title>

       mode (obligatori)
           Pot valdre les cadenes before (abans) o after (després), especificant la posició de
           l'apèndix, relativa al l<punt de posició>.

           Com volem que la nostra nova secció se situï sota de la que hem encaixat, tenim:

                mode=after

       beginboundary (utilitzada només quan mode=after, i obligatòriament en aquest cas)
       endboundary (idem)
           L'expressió regular que encaixi el final de la secció després de la qual va l'apèndix.

           Quan el mode=after, el punt d'inserció està després del punt de posició, però no
           justament després! Està situat al final de la secció que comença en el punt de
           posició, és a dir, abans o després de la línia encaixada pel paràmetre ???boundary,
           depenent de si s'ha fet servir beginboundary o endboundary.

           En el nostre cas, podem decidir-nos per indicar el final de la secció que encaixem
           afegint:

              endboundary=</section>

           o indicar el principi de la següent secció indicant:

              beginboundary=<section>

           En ambdós casos, es col·locarà el nostre apèndix després de </section> i abans de
           <section>. La primera opció és millor perquè funcionarà encara que re-organitzem el
           document.

           Ambdues formes existeixen degut a que els formats de documentació són diferents.
           Alguns tenen maneres de marcar el final d'una secció (com ara el </section> que acabem
           de veure), mentre altres no indiquen explícitament el final de secció (com passa en
           man). En el primer cas, interessarà fer un boundary que encaixi amb el final d'una
           secció, de forma que el punt d'inserció vingui just després. En el segon cas, haurem
           de fer un boundary que encaixi amb el principi de la següent secció, de forma que el
           punt d'inserció vingui just abans.

       Pot semblar obscur, però amb una mica de sort, els següents exemples l'il·luminaran.

       Seguint amb l'exemple que hem utilitzat fins ara, per tal d'afegir una secció anomenada
       "Sobre la traducció" després de la secció "Sobre aquest document" en un document SGML,
       podeu utilitzar qualsevol d'aquestes línies de capçalera:
          PO4A-HEADER: mode=after; position=Sobre aquest document; endboundary=</section>
          PO4A-HEADER: mode=after; position=Sobre aquest document; beginboundary=<section>

       Si voleu afegir quelcom després de la següent secció de nroff:
           .SH "AUTORS"

         haureu d'utilitzar un position que encaixi amb aquesta línia, i un beginboundary que
         encaixi amb el principi de la següent secció (com ara ^\.SH). Llavors l'annex s'afegirà
         després del punt de posició i immediatament abans de la primera línia que encaixi amb el
         beginboundary. És a dir:

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

       Si voleu afegir quelcom a una secció (com ara després de "Copyright Big Dude")  en lloc
       d'afegir una secció completa, proporcioneu una position que encaixi amb aquesta línia, i
       doneu un beginboundary que encaixi qualsevol línia.
          PO4A-HEADER:mode=after;position=Copyright Big Dude, 2004;beginboundary=^

       Si voleu afegir quelcom al final del document, utilitzeu una position que encaixi amb
       qualsevol línia del document (però només una línia. Po4a no seguirà si no és única), i
       doneu un endboundary que no encaixi amb res. No utilitzeu cadenes simples aquí, com ara
       "EOF", sinó cadenes que tinguin menys probabilitats de sortir en el vostre document.
          PO4A-HEADER:mode=after;position=<title>Quant a</title>;beginboundary=FakePo4aBoundary

       En qualsevol cas, recordeu que això són expressions regulars. Per exemple, si voleu
       encaixar el final d'una secció de nroff que acabi amb aquesta línia

         .fi

       no utilitzeu .fi com a endboundary, perquè encaixarà amb "el[ fi]txer", que obviament no
       és el què s'esperava. L'endboundary correcte en aquest cas és: ^\.fi$.

       Si l'annexe no es col·loca on esperàveu, proveu de passar el paràmetre -vv a les eines, de
       forma que explicarà què fa per col·locar l'annexe.

       Exemple més detallat

       Document original (en format POD):

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

       Llavors, el següent annexe s'assegurarà de que s'afegeix una secció (en català) sobre el
       traductor al final del fitxer.

        |PO4A-HEADER:mode=after;position=AUTOR;beginboundary=^=head
        |
        |=head1 TRADUCTOR
        |
        |jo

       Per tal de posar l'annexe abans d'AUTHOR, utilitzeu la següent capçalera:

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

       Això funciona perquè la següent línia que encaixa el beginboundary /^=head1/ després de la
       secció "NAME" (traduït com a "NOM" en català), és la que declara els autors. Per tant,
       l'annexe es col·locarà entre ambdues seccions.

   Com fer tot això en una sola invocació al programa?
       La utilització de po4a ha demostrat ser una mica confusa per als usuaris, ja que s'han de
       cridar dos programes diferents, en l'ordre adequat (po4a-updatepo i després
       po4a-translate), on cadascun d'ells necessita més de 3 paràmetres. A més, amb aquest
       sistema era difícil utilitzar un únic fitxer PO per tots els documents quan s'utilitzava
       més d'un format.

       El programa po4a(1) va ser dissenyat per solucionar aquestes dificultats. Una vegada heu
       convertit el vostre projecte a aquest sistema, escriviu un fitxer simple de configuració,
       explicant on són els fitxers de traducció (PO i POT), on són els documents originals, els
       seus formats, i on s'han de col·locar les traduccions.

       Després, una crida a po4a(1) sobre aquest fitxer assegura que els fitxers PO se
       sincronitzen amb el document original, i que el document traduït es genera correctament.
       Per suposat, segurament voldreu cridar aquest programa dues vegades: una abans d'editar el
       fitxer PO per actualitzar-lo, i una altra després, per obtenir els documents traduïts
       completament actualitzats. Però únicament haureu de recordar una línia de comandes.

   HOWTO customize po4a?
       po4a modules have options (specified with the -o option) that can be used to change the
       module behavior.

       It is also possible to customize a module or new / derivative / modified modules by
       putting a module in lib/Locale/Po4a/, and adding lib to the paths specified by the PERLLIB
       or PERL5LIB environment. For example:

          PERLLIB=$PWD/lib po4a --previous po4a/po4a.cfg

       Note: the actual name of the lib directory is not important.

Com funciona?

       Aquest capítol ofereix una breu explicació del funcionament intern de po4a, de manera que
       es pugui sentir més segur per ajudar-nos a mantenir-lo i a millorar-lo. També el pot
       ajudar a entendre perquè no fa el què esperava, i com solucionar problemes.

   Visió general
       L'arquitectura de po4a és orientada a objectes (en Perl. No és estupend?). L'avantpassat
       comú de totes les classes dels analitzadors s'anomena TransTractor. Aquest nom tan estrany
       ve del fet que s'encarrega simultàniament de traduir el document i d'extreure les cadenes.

       Més formalment, rep com a entrada un document a traduir junt amb un fitxer PO que conté
       les traduccions a utilitzar, i produeix dues sortides separades: un altre fitxer PO
       (resultant de l'extracció de les cadenes traduïbles del document d'entrada), i un document
       traduït (amb la mateixa estructura que el d'entrada, però amb les cadenes traduïbles
       canviades pel contingut del PO d'entrada). Aquí hi ha una representació gràfica:

          Document d'entrada -\                          /---> Document de sortida
                               \     TransTractor::     /           (traduït)
                                +-->-   parse()  ------+
                               /                        \
          PO d'entrada -------/                          \---> PO de sortida
                                                                   (extret)

       Aquest petit eix és el nucli de tota l'arquitectura de po4a. Si s'omet el PO d'entrada i
       el document de sortida, s'obté po4a-gettextize. Si proporcioneu ambdues entrades i ometeu
       el fitxer PO de sortida, obteniu po4a-translate.

       TransTractor::parse() és una funció virtual implementada per cada mòdul. Aquí hi ha un
       petit exemple per mostrar com funciona. Aquest analitza una llista de paràgrafs, on
       cadascun comença amb <p>.

         1 sub parse {
         2   PARAGRAF: while (1) {
         3     $my ($paragraf,$pararef,$linia,$lref)=("","","","");
         4     $my $primer=1;
         5     while (($linia,$lref)=$document->shiftline() && defined($linia)) {
         6       if ($linia =~ m/<p>/ && !$primer--; ) {
         7         $document->unshiftline($linia,$lref);
         8
         9         $paragraf =~ s/^<p>//s;
        10         $document->pushline("<p>".$document->translate($paragraf,$pararef));
        11
        12         next PARAGRAF;
        13       } else {
        14         $paragraf .= $linia;
        15         $pararef = $lref unless(length($pararef));
        16       }
        17     }
        18     return; # No tenim una línia definida? Final del fitxer d'entrada.
        19   }
        20 }

       A la línia 6, trobem <p> per segona vegada. Això vol dir que comença el següent paràgraf.
       Llavors tornem la línia que acabem d'obtenir cap al document original (línia 7) i enviar
       el paràgraf que hem construït fins al moment cap a les sortides. Després d'eliminar-ne el
       <p> a la línia 9, enviem la concatenació d'aquest tag amb la traducció de la resta del
       paràgraf.

       Aquesta funció translate() està molt bé. Insereix el seu paràmetre cap al fitxer PO de
       sortida (extracció) i en retorna la traducció que troba al fitxer PO d'entrada
       (traducció). Com que això s'utilitza com a part del paràmetre de pushline(), aquesta
       traducció va a parar al document de sortida.

       Com mola, no? Es pot escriure un mòdul complet de po4a en menys de 20 línies si el format
       és suficientment simple...

       Podeu aprendre més sobre això a Locale::Po4a::TransTractor(3pm).

   Gettextització: com funciona?
       La idea és agafar el document original i la seva traducció, i suposar que l'enèsima cadena
       extreta de la traducció, és la traducció de l'enèsima cadena de l'original. Perquè
       funcioni, ambdós fitxers han de compartir exactament la mateixa estructura. Per exemple,
       si els fitxers tenen la següent estructura, es molt poc probable que la quarta cadena de
       la traducció (del tipus 'capítol') sigui la traducció de la quarta cadena de l'original
       (del tipus 'paràgraf').

           Original         Traducció

         capítol            capítol
           paràgraf           paràgraf
           paràgraf           paràgraf
           paràgraf         capítol
         capítol              paràgraf
           paràgraf           paràgraf

       Per fer això, els analitzadors de po4a s'utilitzen en l'original i en la traducció per
       extreure fitxers PO, i després es construeix un tercer fitxer PO a partir d'aquests
       prenent les cadenes del segon com a traduccions de les cadenes del primer. Per tal de
       comprovar que les cadenes que ajuntem siguin realment traducció l'una de l'altra, els
       analitzadors de documents de po4a han de desar informació sobre el tipus sintàctic de les
       cadenes del document (tots els existents ho fan, el vostre també hauria de fer-ho).
       Després, aquesta informació s'utilitza per assegurar que ambdós documents tenen la mateixa
       sintaxi. A l'exemple anterior, això ens permetria detectar que la quarta cadena és un
       paràgraf en un cas, i un títol de capítol a l'altre cas, i podriem informar del problema.

       En teoria, seria possible detectar el problema, i resincronitzar el fitxer després (tal
       com fa diff). Però no està clar què hauriem de fer amb les cadenes d'abans de la
       dessincronització, i podria produir mals resultats a vegades. És per això que la
       implementació actual no intenta resincronitzar res i fallarà donant informació quan alguna
       cosa vagi malament, requerint la modificació manual dels fitxers per solventar el
       problema.

       Fins i tot amb aquestes precaucions, les coses poden empitjorar amb molta facilitat. És
       per això que totes les traduccions extretes d'aquesta forma es marquen com a difuses per
       assegurar que el traductor les repassi i les comprovi.

   Annexes: Com funciona?
       Bé, això és força simple. El document traduït no s'escriu directament al disc, sinó que es
       manté en memòria fins que s'han aplicat tots els annexes. L'algorisme involucrat és força
       simple. Busquem la línia que encaixa amb l'expressió regular de posició, i si hi havia el
       mode=before, insertem l'annexe abans. Sinó, busquem la següent línia que encaixi amb el
       boundary i insertem l'annexe després d'aquesta línia, si és un endboundary o abans, si és
       un beginboundary.

PMF

       Aquest capítol agrupa les Preguntes Més Freqüents. De fet, la majoria de preguntes actuals
       es poden formular d'aquesta manera: "Per què s'ha dissenyat d'aquesta forma i no d'una
       altra?" Si pensa que po4a no és la solució ideal per a la traducció de documentació,
       hauria de considerar llegir-se aquesta secció. Si no respon les seves preguntes, contacti
       amb nosaltres a la llista de correu <po4a-devel@lists.alioth.debian.org>. Volem saber la
       seva opinió.

   Perquè hem de traduir cada paràgraf per separat?
       Sí, a po4a, cada paràgraf s'ha de traduir per separat (de fet, cada mòdul ho decideix,
       però tots els existents ho fan, i els vostres també ho haurien de fer).  Aquest enfoc té
       dos avantatges principals:

       · Quan les parts tècniques del document s'amaguen, el traductor no s'hi pot embolicar. Com
         menys marques presentem al traductor, menys es pot equivocar.

       · Tallar el document ajuda a aïllar els canvis del document original. Quan l'original es
         modifiqui, aquest procés facilitarà la cerca de parts de la traducció que necessiten
         actualització.

       Tot i aquests avantatges, a alguna gent no li agrada la idea de traduir els paràgrafs per
       separat. Aquí hi ha algunes de les respostes que puc donar a les seves pors:

       · Aquest enfoc s'ha demostrat exitós al projecte KDE i ha permès a la seva gent produir la
         quantitat més gran de documentació traduïda i actualitzada que conec.

       · Els traductors encara poden utilitzar el context per traduir, ja que les cadenes del
         fitxer PO estan en el mateix ordre que en el document original. Una traducció seqüencial
         serà molt semblant tant si utilitzeu po4a com si no. I en qualsevol cas, la millor
         manera d'aconseguir el context segueix sent convertir el document a un format
         imprimible, ja que els formatats de text no són llegibles, en la meva opinió.

       · Aquest enfoc és el que utilitzen els traductors professionals. Estic d'acord que ells
         tenen uns objectius una mica diferents que els dels traductors de programari lliure. Per
         exemple, el manteniment és habitualment menys crític per ells ja que el contingut no és
         gaire variable.

   Perquè no partir a nivell de frase (o inferior)?
       Les eines de traducció professionals a vegades parteixen el document a nivell de frases
       per tal de maximitzar la reusabilitat de les traduccions prèvies i accelerar el procés.
       El problema és que la mateixa frase pot tenir diverses traduccions, depenent del context.

       Els paràgrafs són més llargs que les frases, per definició. Això pràcticament permet
       assegurar que un mateix paràgraf en dos documents tindrà el mateix significat (i
       traducció), a part del context de cada cas.

       Partir en parts més petites que frases seria molt dolent. Seria una mica llarg d'explicar
       el motiu aquí, però si li interessa el tema, consulti la pàgina de manual de
       Locale::Maketext::TPJ13(3pm) (que ve amb la documentació de Perl), per exemple. Per
       resumir, cada idioma té les seves pròpies regles de sintaxi, i no es poden construir
       frases annexant troços, i que funcioni per tots els llenguatges existents (ni tan sols per
       5 dels 10 més parlats, o fins i tot menys).

   Perquè no posem l'original com a comentari prop de la traducció (o d'alguna altra manera)?
       A primer cop d'ull, gettext no sembla estar adaptat a tot tipus de traduccions.  Per
       exemple, no semblava estar adaptat a debconf, la interfície que utilitzen els paquets de
       Debian per la seva interacció amb l'usuari durant la instal·lació. En aquest cas, els
       texts a traduir eren molt curts (una dotzena de línies per cada paquet), i era difícil
       posar les traduccions en un fitxer especialitzat, ja que ha d'estar disponible abans de la
       instal·lació del paquet.

       És per això que els desenvolupadors de debconf van decidir implementar una altra solució,
       on les traduccions es desaven en el mateix fitxer que l'original. Pot semblar atractiu.
       Algú podria voler-ho fer amb XML, per exemple. Tindria aquesta pinta:

        <section>
         <title lang="en">My title</title>
         <title lang="ca">El meu títol</title>

         <para>
          <text lang="en">My text.</text>
          <text lang="ca">El meu text.</text>
         </para>
        </section>

       Però això va ser tan problemàtic que ara es torna a utilitzar una solució basada en
       fitxers PO. Tan sols es pot editar l'original en el fitxer, i les traduccions s'han ded
       fer en fitxers PO extrets de la plantilla original (i es munta tot a l'hora de compilar el
       paquet). El sistema vell es va determinar obsolet per diversos motius:

       ·   problemes de manteniment

           Si diversos traductors proporcionen pegats alhora, es complica la feina de fusionar-
           los.

           Com detectareu canvis a l'original, que necessiten aplicar-se a les traduccions? Per
           tal d'utilitzar diff, heu de tenir en compte quina versió de l'original heu traduït.
           És a dir, necessiteu un fitxer PO al vostre fitxer ;)

       ·   problemes de codificació

           Aquesta solució és viable quan tan sols intervenen llengües europees, però la
           introducció del coreà, el rus i/o l'àrab compliquen la situació notablement.  Una
           solució podria ser utilitzar UTF, però encara hi ha alguns problemes amb això.

           A més, aquests problemes són difícils de detectar (per exemple, només els lectors
           coreans detectaran que la codificació del coreà és incorrecta [per culpa del traductor
           rus])

       gettext soluciona tots aquest problemes alhora.

   Però gettext no es va dissenyar per a aquest ús!
       És cert, però fins ara ningú ha trobat cap solució millor. L'única alternativa coneguda és
       la traducció manual, amb tots els problemes de manteniment.

   Què hi ha de les altres eines de traducció de documentació que utilitzen gettext?
       Pel què sé, tan sols n'hi ha dues:

       poxml
           Aquesta és l'eina desenvolupada per la gent de KDE per tractar DocBook XML. Si no vaig
           errat, aquest va ser el primer programa que extreia les cadenes a traduir de la
           documentació i en feia fitxers PO, i després de la traducció les injectava en el
           document.

           Tan sols pot tractar XML, i només un DTD particular. M'ha decepcionat una mica la
           forma que té de tractar les llistes, que acaba amb un msgid molt gran. Quan la llista
           creix, el bloc esdevé difícil de tractar.

       po-debiandoc
           Aquest programa fet per Denis Barbier és com un precursor del mòdul SGML de po4a, que
           més o menys el deixa obsolet. Com el nom diu, tan sols tracta el DTD de DebianDoc, que
           és més o menys un DTD obsolet.

       Els avantatges principals de po4a sobre aquests és la facilitat d'afegir contingut extra
       (que és encara pitjor allà) i l'habilitat d'aconseguir la gettextització.

   Educant els desenvolupadors sobre les traduccions
       When you try to translate documentation or programs, you face three kinds of problems;
       linguistics (not everybody speaks two languages), technical (that's why po4a exists) and
       relational/human. Not all developers understand the necessity of translating stuff. Even
       when good willed, they may ignore how to ease the work of translators. To help with that,
       po4a comes with lot of documentation which can be referred to.

       Un altre punt important és que cada fitxer traduït comença amb un breu comentari que
       indica què és el fitxer i com utilitzar-lo. Això hauria d'ajudar als pobres
       desenvolupadors inundats amb pilots de fitxers en diversos idiomes que no parlen, i els
       ajudarà a fer bé la seva feina.

       In the po4a project, translated documents are not source files anymore. Since SGML files
       are habitually source files, it's an easy mistake. That's why all files present this
       header:

        |       *****************************************************
        |       *           GENERATED FILE, DO NOT EDIT             *
        |       * THIS IS NO SOURCE FILE, BUT RESULT OF COMPILATION *
        |       *****************************************************
        |
        | This file was generated by po4a-translate(1). 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 source file:
        | If the PO gets lost, keeping this translation up-to-date will be harder ;)

       Likewise, gettext's regular PO files only need to be copied to the po/ directory. But this
       is not the case of the ones manipulated by po4a. The major risk here is that a developer
       erases the existing translation of his program with the translation of his documentation.
       (Both of them can't be stored in the same PO file, because the program needs to install
       its translation as an mo file while the documentation only uses its translation at compile
       time). That's why the PO files produced by the po-debiandoc module contain the following
       header:

        #
        #  ADVISES TO DEVELOPERS:
        #    - you do not need to manually edit POT or PO files.
        #    - this file contains the translation of your debconf templates.
        #      Do not replace the translation of your program with this !!
        #        (or your translators will get very upset)
        #
        #  ADVISES TO TRANSLATORS:
        #    If you are not familiar with the PO format, gettext documentation
        #     is worth reading, especially sections dedicated to this format.
        #    For example, run:
        #         info -n '(gettext)PO Files'
        #         info -n '(gettext)Header Entry'
        #
        #    Some information specific to po-debconf are available at
        #            /usr/share/doc/po-debconf/README-trans
        #         or http://www.debian.org/intl/l10n/po-debconf/README-trans
        #

   RESUM dels avantatges de l'enfoc basat en gettext
       · The translations are not stored along with the original, which makes it possible to
         detect if translations become out of date.

       · The translations are stored in separate files from each other, which prevents
         translators of different languages from interfering, both when submitting their patch
         and at the file encoding level.

       · Internament està basat en gettext (però po4a ofereix una interfície molt simple per tal
         que no necessiteu entendre el funcionament intern per tal d'utilitzar-lo).  Així no hem
         de reinventar la roda, i degut al seu ampli ús, podem pensar que són unes eines més o
         menys lliures d'errors.

       · Per l'usuari final no canvia res (a part que les traduccions es mantindran millor
         actualitzades :). El fitxer de documentació resultant distribuït és exactament el
         mateix.

       · No cal que els traductors aprenguin una nova sintaxi de fitxer, i podran treballar amb
         el seu editor de fitxers PO predilecte (com ara el mode PO d'emacs, Lokalize o
         Gtranslator).

       · gettext offers a simple way to get statistics about what is done, what should be
         reviewed and updated, and what is still to do. Some example can be found at those
         addresses:

          - http://kv-53.narod.ru/kaider1.png
          - http://www.debian.org/intl/l10n/

       Però no tot és bonic, i aquest enfoc també té alguns desavantatges que haureu de tenir en
       compte.

       · Els annexes són... estranys, a primer cop d'ull.

       · No podeu adaptar el text traduït al vostre gust, com ara partint paràgrafs per aquí, o
         ajuntant-ne dos per allà. Però vist d'una altra manera, si hi ha algun problema amb
         l'original, s'hauria d'informar com a error.

       · Encara que tingui una interfície fàcil, segueix sent una nova eina que la gent ha
         d'aprendre.

         Un dels meus somnis és que s'integrés po4a d'alguna manera amb Gtranslator o Lokalize.
         Quan s'obrís un document SGML, s'extraurien automàticament les cadenes.  Quan es
         guardés, es podria escriure un fitxer SGML traduït al disc. Si aconseguim fer un mòdul
         per a MS Word (TM) (o com a mínim RTF) fins i tot podrien utilitzar-lo traductors
         professionals.

AUTORS

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