PO4A.7(7)

NOM
po4a - marc de treball per traduir documentacio i d'altre material

Introduccio
L'objectiu del projecte po4a (po per a tot) es facilitar la traduccio (i sobretot el manteniment de les traduccions) utilitzant les eines de gettext en arees on no eren d'esperar, com ara en la documentacio.

Taula de continguts
Aquest document esta organitzat d'aquesta forma:

1 Per que he d'utilitzar po4a? Per a que serveix?
    Aquest capitol introductori explica la motivacio del projecte i la seva filosofia. Hauria de llegir-lo primer si esta en el proces d'avaluacio de po4a per a les seves propies traduccions.

2 Com fer servir po4a?
    Aquest capitol es com un manual de referencia on s'intenten contestar les preguntes dels usuaris, i se'ls ofereix una idea general del proces. Aixo introdueix a la forma de fer les coses amb po4a i serveix com a documentacio introductoria de les eines especifiques.

    Com comencar una nova traduccio?
    Com es transforma la traduccio de tornada a un arxiu de documentacio?
    Com actualitzar una traduccio amb po4a?
    Com convertir una traduccio pre-existent a po4a?
    Com afegir text extra a la traduccio (com ara el nom del traductor)?
    Com fer tot aixo en una sola invocacio al programa?
3 Com funciona?
    Aquest capitol ofereix una breu explicacio del funcionament intern de po4a, de manera que es pugui sentir mes segur per ajudar-nos a mantenir-lo i a millorar-lo. Tambe el pot ajudar a entendre perque no fa el que esperava, i com solucionar problemes.

4 PMF
    Aquest capitol agrupa les Preguntes Mes Frequeents. De fet, la majoria de preguntes actuals es poden formular d'aquesta manera: "Per que s'ha dissenyat d'aquesta forma i no d'una altra?" Si pensa que po4a no es la solucio ideal per a la traduccio de documentacio, hauria de considerar llegir-se aquesta seccio. Si no respon les seves preguntes, contacti amb nosaltres a la llista de correu <po4a-devel@lists.alioth.debian.org>. Volem saber la seva opinio.

5 Notes especifiques dels moduls
    Aquest capitol presenta els punts especifics de cada modul ja sigui des del punt de vista del traductor com des del de l'autor original. Llegeixi aixo per aprendre la sintaxi que es trobara quan tradueixi textos amb un modul, o les regles que ha de seguir en el document original per facilitar la vida del traductor.

    Actualment, aquesta seccio no forma part d'aquest document. En realitat, aixo es troba a la documentacio de cada modul. Aixi s'ajuda a assegurar que la informacio estigui actualitzada al mantenir la documentacio i el codi junts.

6 Errors coneguts i caracteristiques solXlicitades
    Uns quants encara :(

Per que he d'utilitzar po4a? Per a que serveix?
M'agrada la idea del programari de codi obert, cosa que fa possible que tot el mon pugui accedir al programari i al seu propi codi font. Pero al ser Frances, soc ben conscient que la llicencia no es la unica restriccio de la llibertat del programari: Els programes lliures no traduiets son inservibles per als qui no son de parla anglesa, i encara queda forca feina per fer-los disponibles a tothom.

La percepcio d'aquesta situacio pels responsables del programari lliure ha millorat drasticament recentment. Nosaltres, com a traductors, hem guanyat la primera batalla i hem convencut a tot al mon de la importancia de les traduccions. Pero per desgracia, aquesta era la part facil. Ara hem de posar-nos en marxa i comencar a traduir.

Actualment el programari lliure es beneficia d'un nivell decent de traduccio, gracies al meravellos paquet d'eines gettext. Aquest pot extreure les cadenes a traduir d'un programa, presentar-les en un format uniforme als traductors, i despres utilitzar el resultat del seu treball en temps d'execucio per mostrar els missatges traduiets a l'usuari.

Pero la situacio es bastant diferent pel que fa a la documentacio. Molt sovint, la documentacio traduieda no es suficientment visible (no es distribueix com a part del programa), nomes parcialment, o no esta actualitzada. La darrera situacio es la pitjor de totes. Per als usuaris, les traduccions antiquades poden ser pitjors que si no existis la traduccio, si descriuen vells comportaments del programa que ja no s'utilitzen.

  El problema a solucionar
Traduir documentacio per si sola no es molt dificil. Els textos son bastant mes llargs que els missatges de programa, i per tant, tarden mes a traduir-se. De tota manera, no es necessiten coneixements tecnics fer fer-ho. La part mes dificil arriba quan la feina s'ha de mantenir. Detectar quines parts han canviat i necessiten ser actualitzades es molt dificil, ja que comporta errors desagradables. Crec que aixo explica per que tantes de les traduccions que hi ha escampades pel mon estan antiquades.

  Les respostes de po4a
Per tant, l'objectiu de po4a es fer mantenible la traduccio de la documentacio. La idea es 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 classiques de gettext ajuden a mantenir la feina actualitzada quan surt una nova versio de l'original. Pero a diferencia del model classic de gettext, les traduccions es re-injecten a l'estructura del document original, de forma que poden ser processades i distribuiedes igual que la versio anglesa.

Gracies a aixo, es mes facil descobrir quines parts del document han canviat i necessiten ser actualitzades. Un altre punt fort es que les eines faran practicament tota la feina quan l'estructura del document original es torni a organitzar i quan alguns capitols es moguin, s'ajuntin o se separin. Al extreure el text a traduir de l'estructura del document, tambe el mante 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 tambe les PMF mes avall en aquest document per a una llista mes completa d'avantatges i desavantatges d'aquesta solucio.

  Formats suportats
Actualment, s'ha implementat satisfactoriament aquesta aproximacio en alguns formats de text:

nroff

El classic format de les pagines de manual, utilitzades per un munt de programes. El suport de po4a es d'agrair, ja que el formateig es una mica dificil d'utilitzar, i no molt amistos per als principiants.

pod

Aquest es el format de Documentacio Online de Perl. El llenguatge i les seves mateixes extensions estan documentades aixi, igual que la majoria de guions de Perl. Al barrejar-lo en el mateix fitxer es mes facil mantenir la documentacio propera al codi actual. Facilita la vida del programador, pero per desgracia, no la del traductor.

sgml

Encara que avui en dia gairebe hagi estat substituiet per XML, aquest format encara s'utilitza habitualment per documents mes extensos que algunes pantalles. Aquest permet fer llibres complets. Actualitzar una traduccio de documents tan llargs pot ser realment un malson. Sovint diff es torna inservible quan s'ha reindentat el text original despres de l'actualitzacio. Afortunadament, po4a el pot ajudar en aquest proces.

Actualment, nomes suporta els DTD de debiandoc i de docbook, pero es realment facil afegir suport per alguns de nous. Fins i tot, es possible utilitzar po4a en un dtd desconegut de sgml sense canviar el codi, passant la informacio necessaria a la linia de comandes. Consulti <Locale::Po4a::Sgml(3pm)> per a mes detalls.

altres

Po4a tambe pot tractar algus formats estranys o especifics, de la mateixa manera que la documentacio de les opcions de compilacio del kernel 2.4.x o els diagrames produiets per l'eina dia. Afegir-ne un de nou sol ser una tasca molt facil i la tasca principal es aconseguir un analitzador pel seu format. Consulti Locale::Po4a::TransTractor(3pm) per mes informacio.

  Formats no suportats
Per desgracia, a po4a encara li manca suport per alguns dels formats de documentacio mes importants. El mes destacat pot ser XML, ja que cada vegada s'utilitza mes en la documentacio de projectes de codi obert. El modul sgml conte un suport limitat per a ell (principalment quan el document no fa servir una sintaxis especifica de XML ;), Estem treballant en un suport millor, i les coses poden canviar en un futur proxim. Mentrestant, si po4a no cobreix les seves necessitats, pot provar el projecte poxml. Es similar al po4a i tracta decentment la documentacio en docbook xml. Per desgracia, ara per ara no pot tractar amb cap altre format. I per suposat, no mola tant com po4a ;)

TeXinfo es un altre dels formats que avui en dia es troben a faltar a po4a. Tota la documentacio GNU esta escrita en aquest format (fins i tot es un dels requisits per arribar a ser un projecte oficial de GNU). La manca de suport a po4a deixa sols als traductors de GNU davant les adversitats del mon. Ens agradaria aconseguir una solucio, pero aquest format es tant potent/complexe que no anem tan de pressa com ens agradaria. Si vol ajudar, naturalment que la seva ajuda sera benvinguda ;)

A part d'aquests dos grans formats, n'hi ha molts altres que ens agradaria suportar a po4a, i no nomes de documentacio. De fet, volem cobrir tots els "forats" deixats per les eines classiques de gettext. Aixo inclou la documentacio de python, descripcions de paquets (deb y rpm), preguntes dels guions de instalXlacio de paquets, registres de canvis dels paquets, i tots els formats especifics utilitzats per programes com escenaris de jocs o els fitxers de recursos de wine.

Com fer servir po4a?
Aquest capitol es com un manual de referencia on s'intenten contestar les preguntes dels usuaris, i se'ls ofereix una idea general del proces. Aixo introdueix a la forma de fer les coses amb po4a i serveix com a documentacio introductoria de les eines especifiques.

  Visio esquematica
L'esquema segueent li dona una visio global del proces de traduccio de documentacio fent servir po4a. No s'espanti per la seva aparent complexitat, aixo es degut a que aqui es representa el proces |<complet>. Un cop hagi convertit el seu projecte a po4a, nomes es rellevant la part dreta del grafic. Aquest exemple tracta de sgml, pero es aplicable a tots els moduls. Cada part del dibuix es detallara a les proximes seccions.

  fr.sgml  original.sgml ---->--------+------>----------->-------+
     |         |                      |                          |
     V         V       { actualitzacio de l'original }           |
     |         |                      |                          |
     +--<---<--+                      V                          |
     |         |              original.new.sgml----->------->----+
     V         V                      |                          |
  [po4a-gettextize]      +--->---->---+                          |
     |         |         |            V                          |
     |         |         |     [po4a-updatepo]                   |
     |         V         ^            |                          V
     V    original.pot   |            V                          |
     |         |         |          fr.po                        |
     |         |         |        ( difus )                      |
     |   { traduccio }   |            |                          |
     |         |         ^            V                          V
     |         |         |     {edicio manual}                   |
     V         V         |            |                          |
     |         |         |            V                          V
     |         |         +--<---    fr.po       apendix    original.sgml
     +---->----+---->------->---> (al dia)    (opcional)     (al dia)
                                      |            |             |
                                      v            v             v
                                      +------>-----+------<------+
                                                   |
                                                   v
                                           [po4a-translate]
                                                   |
                                                   V
                                                fr.sgml
                                               (al dia)

A la part esquerra s'hi mostra la conversio d'una traduccio que no utilitza po4a a aquest sistema. A dalt de la part dreta s'hi representa l'accio de l'autor original (actualitzar la documentacio). Al mig de la part dreta s'hi simbolitzen les accions automatiques de po4a. S'extrau el nou material i es compara amb la traduccio existent. Es troben les parts que no han canviat, i es fa servir la traduccio previa. Les parts parcialment modificades tambe es connecten a la traduccio anterior, pero se li afegeix un marcador indicant que la traduccio s'ha d'actualitzar. La part de baix de la figura mostra com es construeix el document formatejat.

Actualment, com a traductor, la unica operacio manual que hauria de fer-se es la part marcada {edicio manual}. Si, ho sento, pero po4a ajuda a traduir. No tradueix res sol...

  Com comencar una nova traduccio?
Aquesta seccio presenta els passos necessaris per comencar una nova traduccio amb po4a. Els refinaments involucrats a la conversio d'un projecte existent al d'aquest sistema es detallen a la seccio pertinent.

Per comencar una nova traduccio utilitzant po4a, ha de seguir els segueents passos:

-   Extreu el text que s'ha de traduir des del document original a un nou fitxer pot (el format gettext). Per fer-ho pot fer servir el programa po4a-gettextize aixi:

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

    <format> es naturalment el format utilitzat en el document <principal.doc>. Tal com era d'esperar, la sortida va a <traduccio.pot>. Consulti po4a-gettextize(1) per mes detalls sobre les opcions existents.

-   Ara toca traduir el que toca. Per aixo, canviie el nom del fitxer pot a doc.XX.po, per exemple (on XX es el codi ISO639 de l'idioma al que estigui traduint, per exemple "fr" pel frances), i editi el fitxer resultant. Sovint es bona idea no anomenar el fitxer XX.po per evitar confusions amb la traduccio dels missatges de programa pero aixo es cosa seva. No s'oblidi d'actualitzar les capcaleres dels fitxers po, son importants.

    La traduccio en queestio es pot fer amb el mode po d'Emacs o kbabek (basat en KDE) o granslator (basat en GNOME), o qualsevol programa que prefereixi. Fins i tot el classic vi pot servir, encara que no tingui un mode especialitzat per aquesta tasca.

    Si desitja aprendre mes, definitivament ha de consultar la documentacio de gettext, disponible en el paquet gettext-doc.

  Com es transforma la traduccio de tornada a un arxiu de documentacio?
Un cop hagi acabat la traduccio, voldra obtenir la documentacio traduieda i distribuir-la als usuaris junt amb l'original. Per fer-ho, utilitzi el programa po4a-translate(1) aixi (on XX es el codi de l'idioma):

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

Igual que abans, <format> es el format utilitzat en el <principal.doc>. Pero aquest cop el fitxer po passat amb el parametre -p es part de l'entrada. Aquesta es la seva traduccio. La sortida va a <XX.doc>.

Consulti po4a-translate(1) per mes detalls.

  Com actualitzar una traduccio amb po4a?
Per actualitzar la seva traduccio quan el fitxer original canviie, utilitzi el programa po4a-updatepo(1) aixi:

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

(Consulti po4a-updatepo(1) per mes detalls)

Naturalment, el nou paragraf del document no es traduira magicament al fitxer "po" amb aquesta operacio, i necessitara actualitzar l'arxiu "po" manualment. Tanmateix, pot haver de refer les traduccions dels paragrafs que s'hagin modificat una mica. Per assegurar que no s'oblidi de cap, es marquen com a "difuses" durant el proces, i s'haura de treure la marca abans que pugui utilitzar la traduccio a po4a-translate. De la mateixa manera que per a la traduccio inicial, aqui es 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 documentacio traduiet, tal i com s'ha explicat a la seccio anterior.

  Com convertir una traduccio pre-existent a po4a?
Segurament, voste acostumava a traduir manualment el document felicment fins que va arribar una reorganitzacio del document original. Llavors, despres d'intentar-ho diverses vegades sense exit amb diff o eines similars, vol convertir-lo a po4a. Pero per suposat, no vol perdre el seu proces de traduccio. No es preocupi, les eines de po4a tambe tenen en compte aquest cas, i s'anomena gettextitzacio.

La gracia esta en que tant el document traduiet com l'original tinguin la mateixa estructura de manera que les eines puguin encaixar els continguts correctament.

Si esta de sort (es a dir, si les estructures dels documents encaixen a la perfeccio), tot funcionara correctament i haura acabat en pocs segons. En cas contrari, haura d'entendre per que aquest proces te un nom tan espantos, i hauria d'estar preparat per a una mica de feina de grunyits. De totes maneres, recordi que aquest es el preu que ha de pagar per aconseguir despres la comoditat de po4a. I la part bona es que nomes haura de fer-ho una vegada.

No puc emfatitzar-ho mes. Per facilitar el proces, es important trobar la versio exacta que es va utilitzar a la traduccio. La millor situacio es dona quan es va anotar quina revisio del cvs es va fer servir per a la traduccio i no es va modificar durant el proces de traduccio, de manera que la pugui utilitzar.

No funcionara be si utilitza el text original actualitzat amb la traduccio antiga. Es un proces possible, pero mes dificil, i realment s'ha d'evitar sempre que sigui possible. De fet, imagino que si no aconsegueix trobar el text original, la millor solucio es trobar a algu que faci la gettextitzacio per voste (pero jo no, si us plau ;).

Potser soc massa catastrofista. Per molt que les coses vagin malament, segueix sent molt mes rapid que traduir-ho tot altra vegada. Jo vaig fer la gettextitzacio de la traduccio al frances existent de la documentacio de Perl en un dia, encara que les coses van anar malament. Eren mes de dos megabytes de text, i una traduccio nova hagues pogut durar mesos com a minim.

Permeti'm explicar primer les bases del proces, i despres els trucs per aconseguir-ho quan el proces vagi malament. Per facilitar la comprensio, altra vegada s'agafa com a exemple el modul sgml, pero no importa el format que es faci servir.

Un cop hagi aconseguit l'original antic, la gettextitzacio pot ser tan facil com:

 $ po4a-gettextize -f <format> -m <antic.original> -l <antiga.traduccio> -p <doc-XX.po>

Si esta de sort, aixo es tot. Ha convertit la seva antiga traduccio a po4a i ja pot comencar amb la tasca d'actualitzacio. Simplement segueixi el proces explicat unes seccions abans per sincronitzar el seu arxiu po amb el document original mes nou, i actualitzi la traduccio segons convingui.

Tingui en compte que, encara que tot sembli haver anat be, encara es poden produir alguns errors en aquest proces. Aixo es degut a que po4a no es capac d'entendre el text per assegurar-se que la traduccio es refereix a l'original. Es per aixo que les cadenes es marquen com a "difuses" durant el proces. Haura de comprovar cuidadosament cada cadena abans d'eliminar la marca.

Sovint, les estructures dels documents no encaixen a la perfeccio, impedint a po4a-gettextize realitzar la seva tasca. Arribat a aquest punt, tot el joc es trasllada a la edicio dels fitxers per fer encaixar les seves maleiedes estructures.

El pot ajudar llegir la seccio "Gettextitzacio: com funciona?" de mes avall. La comprensio del funcionament intern del proces l'ajudara a fer-lo funcionar. El milor es que po4a-gettextize dona molta informacio quan alguna cosa no ha anat be. Primer, apuntara on s'ha trobat la discrepancia d'estructures en els documents. Despres mostrara les cadenes que no encaixen, la seva posicio en el text, i el tipus de cadascuna. A mes a mes, el fitxer po generat fins al moment es guardara a /tmp/gettextization.failed.po.

-   Borreu totes les parts extres de les traduccions, com per exemple la seccio on s'especifiqui el nom del traductor, o els agraiements de gent que ha colXlaborat a la traduccio. Els apendix, descrits a la segueent seccio, li permetran afegir de nou aquests continguts.

-   No dubti a editar tant l'original com la traduccio. El mes important es aconseguir el fitxer po. Ja tindra temps d'actualitzar-lo mes tard. Un cop dit aixo, es preferible editar la traduccio quan es puguin editar els dos, ja que aixo facilita les coses un cop s'acabi la gettextitzacio.

-   Si fa falta, si algunes parts no estaven traduiedes, elimini-les de l'original. Quan mes endavant sincronitzi el fitxer po, tornaran a apareixer per si soles.

-   Si ha canviat una mica l'estructura (per ajuntar dos paragrafs, o partir-ne algun), desfaci els canvis. Si hi ha problemes amb l'original, hauria d'informar l'autor original. Arreglar-ho a la traduccio nomes ho arregla per una part de la comunitat. I a mes, es impossible quan utilitza po4a ;)

-   A vegades el contingut del paragraf encaixa, pero el seu tipus no. Arreglar aixo depen molt del format. En pod i nroff, a vegades es culpa de que una de les dues linies comenca amb espai i l'altra no. En aquests formats, aquest paragraf no podria justificar-se i es tornaria d'un tipus diferent. Simplement elimini l'espai per solucionar-ho. Tambe pot tractar-se d'un error tipografic al nom del tag.

    A mes a mes, dos paragrafs poden ajuntar-se en el pot quan la linea de separacio conte alguns espais, o quan no hi ha una linia de separacio abans de la linia =item i del contingut de l'element.

-   A vegades, hi ha una desincronitzacio entre els fitxers, i la traduccio s'encaixa a un paragraf original equivocat. Aquest es un signe de que realment ja hi havia un problema abans. Comprovi /tmp/gettextization.failed.po per veure quan comenca la desincronitzacio, i arreglar-ho alla.

-   A vegades li pot donar la impressio que po4a s'ha menjat algunes parts del text, ja sigui de l'original o de la traduccio. /tmp/gettextizacio.failed.po indica que ambdos encaixaven correctament, i despres ha fallat perque intentava encaixar un paragraf amb l'anterior o el posterior al correcte, com si el correcte hagues desaparegut. Maleeixi po4a com jo vaig fer el primer cop que em va passar. Abundantment.

    Aquesta situacio es deguda a que el mateix paragraf es repeteix al llarg del document. En aquest cas, no es crea una nova entrada al fitxer po, sino que se li afegeix una nova referencia i la ja existent.

    Per tant, quan el mateix paragraf apareix dos cops a l'original pero no esta traduiet exactament igual cada cop, tindra la sensacio que ha desaparegut un paragraf de l'original. Simplement elimini la nova traduccio. Si creu que la segona traduccio es millor, tregui-la d'on esta, i substitueixi-la a la primera.

    En el cas contrari, si hi ha dos paragrafs semblants pero diferents que es van traduir de la mateixa forma, li pot donar la impressio que ha desaparegut un paragraf de la traduccio. La solucio es afegir una cadena estupida al paragraf original (quelcom com "soc diferent") per solucionar-ho. No s'espanti. Aquestes coses desapareixeran durant la sincronitzacio, i quan el text afegit sigui suficientment curt, gettext encaixara la seva traduccio amb el text existent (marcant-lo com a difus, pero no importa, ja que totes les cadenes es marquen com a difuses durant la gettextitzacio).

Amb una mica de sort, aquests trucs l'ajudaran a realitzar la seva gettextitzacio i a obtenir el seu estimat fitxer po. Ara estara preparat per sincronitzar el seu fitxer i comencar la traduccio. Tingui en compte, que en textos grans, la primera sincronitzacio pot tardar forca temps.

Per exemple, el primer po4a-updatepo de la traduccio al frances de la documentacio de Perl (un fitxer po de 5.5Mb) va tardar dos dies aproximadament en una maquina G5 a 1Ghz. Si, 48 hores, pero les segueents vegades tan sols tardava una dotzena de segons al meu portatil vell. Aixo es perque la primera vegada, la majoria de msgids del fitxer po no encaixen amb cap altre dels del fitxer pot. Aixo obliga a gettext a buscar la cadena mes semblant utilitzant un costos algorisme de proximitat de cadenes.

  Com afegir text extra a la traduccio (com ara el nom del traductor)?
Degut a l'us de gettext, fer-ho amb po4a es torna mes dificil que abans, ja que simplement s'editava el nou fitxer paralXlelament a l'original. Pero segueix sent possible gracies als anomenats apendixs.

Per ajudar a la comprensio, consideri els apendix com uns pegats aplicats al document traduiet despres del proces. Son bastant diferents que els pegats originals (nomes tenen una linia de context, que pot incloure una expressio regular de perl, i unicament pot afegir text, sense eliminar res), pero les funcionalitats son les mateixes.

El seu objectiu es permetre al traductor afegir contingut extra al document, que no es traduccio del document original. L'us mes habitual es afegir una seccio sobre la traduccio en si mateixa, llistant els colXlaboradors i explicant com informar dels errors de la traduccio.

Els apendixs s'han de proporcionar com fitxers a part. La primera linia forma una capcalera que indica el lloc del document resultant on s'ha de colXlocar. La resta del fitxer d'apendix s'afegira sense modificacions a la posicio determinada del document resultant.

La capcalera te una sintaxi molt rigida: ha de comencar amb la cadena "PO4A-HEADER:", seguida per una llista de camps "clau=valor" separats per punt i coma (;). Els espais en blanc SON importants. Tingui en compte que no pot usar el caracter punt i coma (;) en els valors, i que les cometes no ajuden.

Una vegada mes, sona espantos, pero els exemples de mes endavant haurien d'ajudar-lo a trobar la forma d'escriure la linia de capcalera que necessiti. Per a ilXlustrar la discussio, suposi que vol afegir una seccio anomenada "Sobre aquesta traduccio" despres de l'anomenada "Sobre aquest document".

Aqui hi ha les possibles claus de capcalera:

position (obligatoria)
    una expressio regular. Es colXlocara l'apendix prop de la linia que encaixi amb aquesta expressio regular. Tingui en compte que estem parlant del document traduiet, no l'original. Si hi ha mes d'una linia que encaixi (o cap), l'addicio fallara. Sempre es millor donar un error que inserir l'apendix en el lloc equivocat.

    Aquesta linia es diu punt de posicio a partir d'ara. El punt on s'inserira l'apendix es diu punt d'insercio. Aquests dos punts son molt propers, pero no iguals. Per exemple, si desitja inserir una nova seccio, es mes facil posar el punt de posicio en el titol de la seccio anterior, i explicar-li a po4 on acaba la seccio (recordi que el punt de posicio ve donat per l'expressio regular, que ha d'encaixar una unica linia).

    La localizacio del punt d'insercio respecte el punt de posicio esta controlat pels camps "mode", "beginboundary" i "endboundary", que s'expliquen a continuacio.

    En el nostre cas tindriem:

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

mode (obligatori)
    Pot valdre les cadenes "before" (abans) o "after" (despres), especificant la posicio de l'apendix, relativa al l<punt de posicio>.

    Com volem que la nostra nova seccio se situie sota de la que hem encaixat, tenim:

         mode=after

beginboundary (utilitzada nomes quan mode=after, i obligatoriament en aquest cas)
endboundary (idem)
    L'expressio regular que encaixi el final de la seccio despres de la qual va l'apendix.

    Quan el mode=after, el punt d'insercio esta despres del punt de posicio, pero no justament despres! Esta situat al final de la seccio que comenca en el punt de posicio, es a dir, abans o despres de la linia encaixada pel parametre "???boundary", depenent de si s'ha fet servir "beginboundary" o "endboundary".

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

       endboundary=</section>

    o indicar el principi de la segueent seccio indicant:

       beginboundary=<section>

    En ambdos casos, es colXlocara el nostre apendix despres de </section> i abans de <section>. La primera opcio es millor perque funcionara encara que re-organitzem el document.

    Ambdues formes existeixen degut a que els formats de documentacio son diferents. Alguns tenen maneres de marcar el final d'una seccio (com ara el "</section>" que acabem de veure), mentre altres no indiquen explicitament el final de seccio (com passa en nroff). En el primer cas, interessara fer un boundary que encaixi amb el final d'una seccio, de forma que el punt d'insercio vingui just despres. En el segon cas, haurem de fer un boundary que encaixi amb el principi de la segueent seccio, de forma que el punt d'insercio vingui just abans.

Pot semblar obscur, pero amb una mica de sort, els segueents exemples l'ilXluminaran.

Seguint amb l'exemple que hem utilitzat fins ara, per tal d'afegir una seccio anomenada "Sobre la traduccio" despres de la seccio "Sobre aquest document" en un document sgml, podeu utilitzar qualsevol d'aquestes linies de capcalera:
     PO4A-HEADER: mode=after; position=Sobre aquest document; endboundary=</section>
     PO4A-HEADER: mode=after; position=Sobre aquest document; beginboundary=<section>

Si voleu afegir quelcom despres de la segueent seccio de nroff:
      .SH "AUTORS"

    haureu d'utilitzar un "position" que encaixi amb aquesta linia, i un "beginboundary" que encaixi amb el principi de la segueent seccio (com ara "^\.SH"). Llavors l'annex s'afegira despres del punt de posicio i immediatament abans de la primera linia que encaixi amb el "beginboundary". Es a dir:

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

Si voleu afegir quelcom a una seccio (com ara despres de "Copyright Big Dude")  en lloc d'afegir una seccio completa, proporcioneu una "position" que encaixi amb aquesta linia, i doneu un "beginboundary" que encaixi qualsevol linia.
     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 linia del document (pero nomes una linia. Po4a no seguira si no es unica), i doneu un "endboundary" que no encaixi amb res. No utilitzeu cadenes simples aqui, com ara ""EOF"", sino 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 aixo son expressions regulars. Per exemple, si voleu encaixar el final d'una seccio de nroff que acabi amb aquesta linia

  .fi

no utilitzeu ".fi" com a endboundary, perque encaixara amb "el[ fi]txer", que obviament no es el que s'esperava. L'endboundary correcte en aquest cas es: "^\.fi$".

Si l'annexe no es colXloca on esperaveu, proveu de passar el parametre -vv a les eines, de forma que explicara que fa per colXlocar l'annexe.

Exemple mes detallat

Document original (en format pod):

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

Llavors, el segueent annexe s'assegurara de que s'afegeix una seccio (en catala) 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 segueent capcalera:

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

Aixo funciona perque la segueent linia que encaixa el beginboundary /^head1/ despres de la seccio "NAME" (traduiet com a "NOM" en catala), es la que declara els autors. Per tant, l'annexe es colXlocara entre ambdues seccions.

  Com fer tot aixo en una sola invocacio al programa?
La utilitzacio 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 despres po4a-translate), on cadascun d'ells necessita mes de 3 parametres. A mes, amb aquest sistema era dificil utilitzar un unic fitxer po per tots els documents quan s'utilitzava mes 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 configuracio, explicant on son els fitxers de traduccio (po i pot), on son els documents originals, els seus formats, i on s'han de colXlocar les traduccions.

Despres, una crida a po4a(1) sobre aquest fitxer assegura que els fitxers po se sincronitzen amb el document original, i que el document traduiet 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 despres, per obtenir els documents traduiets completament actualitzats. Pero unicament haureu de recordar una linia de comandes.

Com funciona?
Aquest capitol ofereix una breu explicacio del funcionament intern de po4a, de manera que es pugui sentir mes segur per ajudar-nos a mantenir-lo i a millorar-lo. Tambe el pot ajudar a entendre perque no fa el que esperava, i com solucionar problemes.

  Visio general
L'arquitectura de po4a es orientada a objectes (en Perl. No es estupend?). L'avantpassat comu de totes les classes dels analitzadors s'anomena TransTractor. Aquest nom tan estrany ve del fet que s'encarrega simultaniament de traduir el document i d'extreure les cadenes.

Mes formalment, rep com a entrada un document a traduir junt amb un fitxer po que conte les traduccions a utilitzar, i produeix dues sortides separades: un altre fitxer po (resultant de l'extraccio de les cadenes traduiebles del document d'entrada), i un document traduiet (amb la mateixa estructura que el d'entrada, pero amb les cadenes traduiebles canviades pel contingut del po d'entrada). Aqui hi ha una representacio grafica:

   Document d'entrada -\                          /---> Document de sortida
                        \     TransTractor::     /           (traduiet)
                         +-->-   parse()  ------+
                        /                        \
   po d'entrada -------/                          \---> po de sortida
                                                            (extret)

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

TransTractor::parse() es una funcio virtual implementada per cada modul. Aqui hi ha un petit exemple per mostrar com funciona. Aquest analitza una llista de paragrafs, on cadascun comenca 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 linia definida? Final del fitxer d'entrada.
 19   }
 20 }

A la linia 6, trobem <p> per segona vegada. Aixo vol dir que comenca el segueent paragraf. Llavors tornem la linia que acabem d'obtenir cap al document original (linia 7) i enviar el paragraf que hem construiet fins al moment cap a les sortides. Despres d'eliminar-ne el <p> a la linia 9, enviem la concatenacio d'aquest tag amb la traduccio de la resta del paragraf.

Aquesta funcio translate() esta molt be. Insereix el seu parametre cap al fitxer po de sortida (extraccio) i en retorna la traduccio que troba al fitxer po d'entrada (traduccio). Com que aixo s'utilitza com a part del parametre de pushline(), aquesta traduccio va a parar al document de sortida.

Com mola, no? Es pot escriure un modul complet de po4a en menys de 20 linies si el format es suficientment simple...

Podeu aprendre mes sobre aixo a Locale::Po4a::TransTractor(3pm).

  Gettextitzacio: com funciona?
La idea es agafar el document original i la seva traduccio, i suposar que l'enesima cadena extreta de la traduccio, es la traduccio de l'enesima cadena de l'original. Perque funcioni, ambdos fitxers han de compartir exactament la mateixa estructura. Per exemple, si els fitxers tenen la segueent estructura, es molt poc probable que la quarta cadena de la traduccio (del tipus 'capitol') sigui la traduccio de la quarta cadena de l'original (del tipus 'paragraf').

    Original         Traduccio

  capitol            capitol
    paragraf           paragraf
    paragraf           paragraf
    paragraf         capitol
  capitol              paragraf
    paragraf           paragraf

Per fer aixo, els analitzadors de po4a s'utilitzen en l'original i en la traduccio per extreure fitxers po, i despres 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 traduccio l'una de l'altra, els analitzadors de documents de po4a han de desar informacio sobre el tipus sintactic de les cadenes del document (tots els existents ho fan, el vostre tambe hauria de fer-ho). Despres, aquesta informacio s'utilitza per assegurar que ambdos documents tenen la mateixa sintaxi. A l'exemple anterior, aixo ens permetria detectar que la quarta cadena es un paragraf en un cas, i un titol de capitol a l'altre cas, i podriem informar del problema.

En teoria, seria possible detectar el problema, i resincronitzar el fitxer despres (tal com fa diff). Pero no esta clar que hauriem de fer amb les cadenes d'abans de la dessincronitzacio, i podria produir mals resultats a vegades. Es per aixo que la implementacio actual no intenta resincronitzar res i fallara donant informacio quan alguna cosa vagi malament, requerint la modificacio manual dels fitxers per solventar el problema.

Fins i tot amb aquestes precaucions, les coses poden empitjorar amb molta facilitat. Es per aixo 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?
Be, aixo es forca simple. El document traduiet no s'escriu directament al disc, sino que es mante en memoria fins que s'han aplicat tots els annexes. L'algorisme involucrat es forca simple. Busquem la linia que encaixa amb l'expressio regular de posicio, i si hi havia el mode=before, insertem l'annexe abans. Sino, busquem la segueent linia que encaixi amb el boundary i insertem l'annexe despres d'aquesta linia, si es un "endboundary" o abans, si es un "beginboundary".

PMF
Aquest capitol agrupa les Preguntes Mes Frequeents. De fet, la majoria de preguntes actuals es poden formular d'aquesta manera: "Per que s'ha dissenyat d'aquesta forma i no d'una altra?" Si pensa que po4a no es la solucio ideal per a la traduccio de documentacio, hauria de considerar llegir-se aquesta seccio. Si no respon les seves preguntes, contacti amb nosaltres a la llista de correu <po4a-devel@lists.alioth.debian.org>. Volem saber la seva opinio.

  Perque hem de traduir cada paragraf per separat?
Si, a po4a, cada paragraf s'ha de traduir per separat (de fet, cada modul ho decideix, pero tots els existents ho fan, i els vostres tambe ho haurien de fer). Aquest enfoc te dos avantatges principals:

•   Quan les parts tecniques 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 aiellar els canvis del document original. Quan l'original es modifiqui, aquest proces facilitara la cerca de parts de la traduccio que necessiten actualitzacio.

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

•   Aquest enfoc s'ha demostrat exitos al projecte KDE i ha permes a la seva gent produir la quantitat mes gran de documentacio traduieda 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 traduccio sequeencial sera 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 son llegibles, en la meva opinio.

•   Aquest enfoc es 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 es habitualment menys critic per ells ja que el contingut no es gaire variable.

  Perque no partir a nivell de frase (o inferior)?
Les eines de traduccio professionals a vegades parteixen el document a nivell de frases per tal de maximitzar la reusabilitat de les traduccions previes i accelerar el proces. El problema es que la mateixa frase pot tenir diverses traduccions, depenent del context.

Els paragrafs son mes llargs que les frases, per definicio. Aixo practicament permet assegurar que un mateix paragraf en dos documents tindra el mateix significat (i traduccio), a part del context de cada cas.

Partir en parts mes petites que frases seria molt dolent. Seria una mica llarg d'explicar el motiu aqui, pero si li interessa el tema, consulti la pagina de manual de Locale::Maketext::TPJ13(3pm) (que ve amb la documentacio de Perl), per exemple. Per resumir, cada idioma te les seves propies regles de sintaxi, i no es poden construir frases annexant trocos, i que funcioni per tots els llenguatges existents (ni tan sols per 5 dels 10 mes parlats, o fins i tot menys).

  Perque no posem l'original com a comentari prop de la traduccio (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 interficie que utilitzen els paquets de Debian per la seva interaccio amb l'usuari durant la instalXlacio. En aquest cas, els texts a traduir eren molt curts (una dotzena de linies per cada paquet), i era dificil posar les traduccions en un fitxer especialitzat, ja que ha d'estar disponible abans de la instalXlacio del paquet.

Es per aixo que els desenvolupadors de debconf van decidir implementar una altra solucio, on les traduccions es desaven en el mateix fitxer que l'original. Pot semblar atractiu. Algu podria voler-ho fer amb xml, per exemple. Tindria aquesta pinta:

 <section>
  <title lang="en">My title</title>
  <title lang="ca">El meu titol</title>

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

Pero aixo va ser tan problematic que ara es torna a utilitzar una solucio 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 versio de l'original heu traduiet. Es a dir, necessiteu un fitxer po al vostre fitxer ;)

•   problemes de codificacio

    Aquesta solucio es viable quan tan sols intervenen llenguees europees, pero la introduccio del corea, el rus i/o l'arab compliquen la situacio notablement. Una solucio podria ser utilitzar UTF, pero encara hi ha alguns problemes amb aixo.

    A mes, aquests problemes son dificils de detectar (per exemple, nomes els lectors coreans detectaran que la codificacio del corea es incorrecta [per culpa del traductor rus])

gettext soluciona tots aquest problemes alhora.

  Pero gettext no es va dissenyar per a aquest us!
Es cert, pero fins ara ningu ha trobat cap solucio millor. L'unica alternativa coneguda es la traduccio manual, amb tots els problemes de manteniment.

  Que hi ha de les altres eines de traduccio de documentacio que utilitzen gettext?
Pel que se, tan sols n'hi ha dues:

poxml
    Aquesta es 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 documentacio i en feia fitxers po, i despres de la traduccio les injectava en el document.

    Tan sols pot tractar XML, i nomes un DTD particular. M'ha decepcionat una mica la forma que te de tractar les llistes, que acaba amb un msgid molt gran. Quan la llista creix, el bloc esdeve dificil de tractar.

po-debiandoc
    Aquest programa fet per Denis Barbier es com un precursor del modul sgml de po4a, que mes o menys el deixa obsolet. Com el nom diu, tan sols tracta el dtd de debiandoc, que es mes o menys un dtd obsolet.

Els avantatges principals de po4a sobre aquests es la facilitat d'afegir contingut extra (que es encara pitjor alla) i l'habilitat d'aconseguir la gettextitzacio.

  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 es que cada fitxer traduiet comenca amb un breu comentari que indica que es el fitxer i com utilitzar-lo. Aixo hauria d'ajudar als pobres desenvolupadors inundats amb pilots de fitxers en diversos idiomes que no parlen, i els ajudara a fer be 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 cvs,
 | 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 esta basat en "gettext" (pero "po4a" ofereix una interficie molt simple per tal que no necessiteu entendre el funcionament intern per tal d'utilitzar-lo). Aixi no hem de reinventar la roda, i degut al seu ampli us, podem pensar que son unes eines mes o menys lliures d'errors.

•   Per l'usuari final no canvia res (a part que les traduccions es mantindran millor actualitzades :). El fitxer de documentacio resultant distribuiet es 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, kbabel 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://i18n.kde.org/tools/kbabel/img/previewKonq.png
     - http://www.debian.org/intl/l10n

Pero no tot es bonic, i aquest enfoc tambe te alguns desavantatges que haureu de tenir en compte.

•   Els annexes son... estranys, a primer cop d'ull.

•   No podeu adaptar el text traduiet al vostre gust, com ara partint paragrafs per aqui, o ajuntant-ne dos per alla. Pero vist d'una altra manera, si hi ha algun problema amb l'original, s'hauria d'informar com a error.

•   Encara que tingui una interficie facil, segueix sent una nova eina que la gent ha d'aprendre.

    Un dels meus somnis es que s'integres po4a d'alguna manera amb gtranslator o kbabel. Quan s'obris un document sgml, s'extraurien automaticament les cadenes. Quan es guardes, es podria escriure un fitxer sgml traduiet al disc. Si aconseguim fer un modul per a MS Word (TM) (o com a minim RTF) fins i tot podrien utilitzar-lo traductors professionals.

Errors coneguts i caracteristiques solXlicitades
L'assumpte mes important (a part dels moduls faltants) es el tractament de codificacions. S'hauria d'afegir el pragma UTF8 de perl i despres recodificar les cadenes a la sortida, pero encara no esta fet.

We would also like to factorise some code (about file insertion) of the sgml module back into the TransTractor so that all modules can benefit from this, but this is not user visible.

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

TRADUCCIO
 Carme Cirera <menxu@hotmail.com>
 Jordi Vilalta <jvprat@gmail.com>

POD ERRORS
Hey! The above document had some coding errors, which are explained below:

Around line 15:
    Non-ASCII character seen before =encoding in 'documentacio'. Assuming ISO8859-1