Provided by:
po4a_0.33.3-1_all 
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?
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.
6 Errors coneguts i caracterÃstiques sol·licitades
Uns quants encara :(
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:
nroff
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
L’esquema següent li dóna una visió global del procés de traducció de
documentació fent servir po4a. No s’espanti per la seva aparent
complexitat, això es degut a que aquà es representa el procés
|<complet>. Un cop hagi convertit el seu projecte a po4a, només és
rellevant la part dreta del grà fic. Aquest exemple tracta de sgml, però
és aplicable a tots els mòduls. Cada part del dibuix es detallarà a les
pròximes seccions.
fr.sgml original.sgml ---->--------+------>----------->-------+
| | | |
V V { actualització de l'original } |
| | | |
+--<---<--+ V |
| | original.new.sgml----->------->----+
V V | |
[po4a-gettextize] +--->---->---+ |
| | | V |
| | | [po4a-updatepo] |
| V ^ | V
V original.pot | V |
| | | fr.po |
| | | ( difús ) |
| { traducció } | | |
| | ^ V V
| | | {edició manual} |
V V | | |
| | | V V
| | +--<--- fr.po apèndix 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 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:
- 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 aixÃ:
$ po4a-gettextize -f <format> -m <principal.doc> -p <traducció.pot>
<format> és naturalment el format utilitzat en el document
<principal.doc>. Tal com era d’esperar, la sortida va a
<traducció.pot>. Consulti po4a-gettextize(1) per més detalls sobre
les opcions existents.
- 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 kbabek
(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 <master.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?
Per actualitzar la seva traducció quan el fitxer original canviï,
utilitzi el programa po4a-updatepo(1) aixÃ:
$ 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?
Segurament, vostè acostumava a traduir manualment el document feliçment
fins que va arribar una reorganització del document original. Llavors,
després d’intentar-ho diverses vegades sense èxit amb diff o eines
similars, vol convertir-lo a po4a. Però per suposat, no vol perdre el
seu procés de traducció. No es preocupi, les eines de po4a també tenen
en compte aquest cas, i s’anomena gettextització.
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 cvs 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.
Permeti’m explicar primer les bases del procés, i després els trucs per
aconseguir-ho quan el procés vagi malament. Per facilitar la
comprensió, altra vegada s’agafa com a exemple el mòdul sgml, però no
importa el format que es faci servir.
Un cop hagi aconseguit l’original antic, la gettextització pot ser tan
fà cil com:
$ po4a-gettextize -f <format> -m <old.original> -l <old.translation> -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 nroff, 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 pot 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 nroff). 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.
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 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 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, 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://kbabel.kde.org/img/previewKonq.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 kbabel. 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.
Errors coneguts i caracterÃstiques sol·licitades
L’assumpte més important (a part dels mòduls faltants) és el tractament
de codificacions. S’hauria d’afegir el pragma UTF8 de perl i després
recodificar les cadenes a la sortida, però encara no està 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)
TRADUCCIÓ
Carme Cirera <menxu@hotmail.com>
Jordi Vilalta <jvprat@gmail.com>
