NOM¶
po4a - marc de treball per traduir documentació i d'altre material
Introducció¶
L'objectiu del projecte po4a (PO per a tot) és facilitar la traducció
(i sobretot el manteniment de les traduccions) utilitzant les eines de gettext
en àrees on no eren d'esperar, com ara en la documentació.
Taula de continguts¶
Aquest document està organitzat d'aquesta forma:
- 1 Per què he d'utilitzar po4a? Per a què
serveix?
- Aquest capítol introductori explica la motivació
del projecte i la seva filosofia. Hauria de llegir-lo primer si està
en el procés d'avaluació de po4a per a les seves pròpies
traduccions.
- 2 Com fer servir po4a?
- Aquest capítol és com un manual de
referència on s'intenten contestar les preguntes dels usuaris, i
se'ls ofereix una idea general del procés. Això introdueix a la
forma de fer les coses amb po4a i serveix com a documentació
introductòria de les eines específiques.
- Com començar una nova traducció?
- Com es transforma la traducció de tornada a un arxiu
de documentació?
- Com actualitzar una traducció amb po4a?
- Com convertir una traducció pre-existent a po4a?
- Com afegir text extra a la traducció (com ara el nom
del traductor)?
- Com fer tot això en una sola invocació al
programa?
- HOWTO customize po4a?
- 3 Com funciona?
- Aquest capítol ofereix una breu explicació del
funcionament intern de po4a, de manera que es pugui sentir més segur
per ajudar-nos a mantenir-lo i a millorar-lo. També el pot ajudar a
entendre perquè no fa el què esperava, i com solucionar
problemes.
- 4 PMF
- Aquest capítol agrupa les Preguntes Més
Freqüents. De fet, la majoria de preguntes actuals es poden formular
d'aquesta manera: "Per què s'ha dissenyat d'aquesta forma i no
d'una altra?" Si pensa que po4a no és la solució ideal per
a la traducció de documentació, hauria de considerar llegir-se
aquesta secció. Si no respon les seves preguntes, contacti amb
nosaltres a la llista de correu
<po4a-devel@lists.alioth.debian.org>. Volem saber la seva
opinió.
- 5 Notes específiques dels mòduls
- Aquest capítol presenta els punts específics de
cada mòdul ja sigui des del punt de vista del traductor com des del
de l'autor original. Llegeixi això per aprendre la sintaxi que es
trobarà quan tradueixi textos amb un mòdul, o les regles que ha
de seguir en el document original per facilitar la vida del traductor.
Actualment, aquesta secció no forma part d'aquest document. En
realitat, això es troba a la documentació de cada mòdul.
Així s'ajuda a assegurar que la informació estigui actualitzada
al mantenir la documentació i el codi junts.
Per què he d'utilitzar po4a? Per a què serveix?¶
M'agrada la idea del programari de codi obert, cosa que fa possible que tot el
món pugui accedir al programari i al seu propi codi font. Però al
ser Francès, sóc ben conscient que la llicència no és la
única restricció de la llibertat del programari: Els programes
lliures no traduïts són inservibles per als qui no són de parla
anglesa, i encara queda força feina per fer-los disponibles a tothom.
La percepció d'aquesta situació pels responsables del programari
lliure ha millorat dràsticament recentment. Nosaltres, com a traductors,
hem guanyat la primera batalla i hem convençut a tot al món de la
importància de les traduccions. Però per desgràcia, aquesta era
la part fàcil. Ara hem de posar-nos en marxa i començar a traduir.
Actualment el programari lliure es beneficia d'un nivell decent de
traducció, gràcies al meravellós paquet d'eines gettext. Aquest
pot extreure les cadenes a traduir d'un programa, presentar-les en un format
uniforme als traductors, i després utilitzar el resultat del seu treball
en temps d'execució per mostrar els missatges traduïts a l'usuari.
Però la situació és bastant diferent pel que fa a la
documentació. Molt sovint, la documentació traduïda no és
suficientment visible (no es distribueix com a part del programa), només
parcialment, o no està actualitzada. La darrera situació és la
pitjor de totes. Per als usuaris, les traduccions antiquades poden ser pitjors
que si no existís la traducció, si descriuen vells comportaments del
programa que ja no s'utilitzen.
El problema a solucionar¶
Traduir documentació per sí sola no és molt difícil. Els
textos són bastant més llargs que els missatges de programa, i per
tant, tarden més a traduir-se. De tota manera, no es necessiten
coneixements tècnics fer fer-ho. La part més difícil arriba
quan la feina s'ha de mantenir. Detectar quines parts han canviat i necessiten
ser actualitzades és molt difícil, ja que comporta errors
desagradables. Crec que això explica per què tantes de les
traduccions que hi ha escampades pel món estan antiquades.
Les respostes de po4a¶
Per tant, l'objectiu de po4a es fer
mantenible la traducció de la
documentació. La idea és reutilitzar la metodologia de gettext en
aquest nou camp. Com en gettext, s'extreuen els textos del lloc original per
tal de presentar-los als traductors en un format uniforme. Les eines
clàssiques de gettext ajuden a mantenir la feina actualitzada quan surt
una nova versió de l'original. Però a diferència del model
clàssic de gettext, les traduccions es re-injecten a l'estructura del
document original, de forma que poden ser processades i distribuïdes
igual que la versió anglesa.
Gràcies a això, és més fàcil descobrir quines parts del
document han canviat i necessiten ser actualitzades. Un altre punt fort
és que les eines faran pràcticament tota la feina quan l'estructura
del document original es torni a organitzar i quan alguns capítols es
moguin, s'ajuntin o se separin. Al extreure el text a traduir de l'estructura
del document, també el manté lluny de la complexitat del formateig
de text i redueix les oportunitats de danyar el document (encara que no li
impedeixin completament de fer-ho).
Si us plau, llegeixi també les
PMF més avall en aquest document
per a una llista més completa d'avantatges i desavantatges d'aquesta
solució.
Actualment, s'ha implementat satisfactòriament aquesta aproximació en
alguns formats de text:
man
The good old manual pages' format, used by so much programs out there. The po4a
support is very welcome here since this format is somewhat difficult to use
and not really friendly to the newbies. The
Locale::Po4a::Man(3pm)
module also supports the mdoc format, used by the BSD man pages (they are also
quite common on Linux).
pod
Aquest és el format de Documentació Online de Perl. El llenguatge i
les seves mateixes extensions estan documentades així, igual que la
majoria de guions de Perl. Al barrejar-lo en el mateix fitxer és més
fàcil mantenir la documentació propera al codi actual. Facilita la
vida del programador, però per desgràcia, no la del traductor.
sgml
Encara que avui en dia gairebé hagi estat substituït per XML, aquest
format encara s'utilitza habitualment per documents més extensos que
algunes pantalles. Aquest permet fer llibres complets. Actualitzar una
traducció de documents tan llargs pot ser realment un malson. Sovint
diff es torna inservible quan s'ha reindentat el text original
després de l'actualització. Afortunadament, po4a el pot ajudar en
aquest procés.
Actualment, només suporta els DTD de DebianDoc i de DocBook, però
és realment fàcil afegir suport per alguns de nous. Fins i tot,
és possible utilitzar po4a en un DTD desconegut de SGML sense canviar el
codi, passant la informació necessària a la línia de comandes.
Consulti <
Locale::Po4a::Sgml(3pm)> per a més detalls.
TeX / LaTeX
The LaTeX format is a major documentation format used in the Free Software world
and for publications. The
Locale::Po4a::LaTeX(3pm) module was tested
with the Python documentation, a book and some presentations.
texinfo
All the GNU documentation is written in this format (that's even one of the
requirement to become an official GNU project). The support for
Locale::Po4a::Texinfo(3pm) in po4a is still at the beginning. Please
report bugs and feature requests.
xml
The XML format is a base format for many documentation formats.
Currently, the DocBook DTD is supported by po4a. See
Locale::Po4a::Docbook(3pm) for details.
altres
Po4a també pot tractar algus formats estranys o específics, de la
mateixa manera que la documentació de les opcions de compilació del
kernel 2.4.x o els diagrames produïts per l'eina dia. Afegir-ne un de nou
sol ser una tasca molt fàcil i la tasca principal és aconseguir un
analitzador pel seu format. Consulti
Locale::Po4a::TransTractor(3pm)
per més informació.
Unfortunately, po4a still lacks support for several documentation formats.
There is a whole bunch of other formats we would like to support in po4a, and
not only documentation ones. Indeed, we aim at plugging all "market
holes" left by the classical gettext tools. It encompass package
descriptions (deb and rpm), package installation scripts questions, package
changelogs, and all specialized file formats used by the programs such as game
scenarios or wine resource files.
Com fer servir po4a?¶
Aquest capítol és com un manual de referència on s'intenten
contestar les preguntes dels usuaris, i se'ls ofereix una idea general del
procés. Això introdueix a la forma de fer les coses amb po4a i
serveix com a documentació introductòria de les eines
específiques.
Visió esquemàtica¶
The following schema gives an overview of the process of translating
documentation using po4a. Do not be afraid by its apparent complexity, it
comes from the fact that the
whole process is represented here. Once
you converted your project to po4a, only the right part of the graphic is
relevant.
Note that
master.doc is taken as an example for the documentation to be
translated and
translation.doc is the corresponding translated text.
The suffix could be
.pod,
.xml, or
.sgml depending on its
format. Each part of the picture will be detailed in the next sections.
master.doc
|
V
+<-----<----+<-----<-----<--------+------->-------->-------+
: | | :
{translation} | { update of master.doc } :
: | | :
XX.doc | V V
(optional) | master.doc ->-------->------>+
: | (new) |
V V | |
[po4a-gettextize] doc.XX.po--->+ | |
| (old) | | |
| ^ V V |
| | [po4a-updatepo] |
V | | V
translation.pot ^ V |
| | doc.XX.po |
| | (fuzzy) |
{ translation } | | |
| ^ V V
| | {manual editing} |
| | | |
V | V V
doc.XX.po --->---->+<---<---- doc.XX.po addendum master.doc
(initial) (up-to-date) (optional) (up-to-date)
: | | |
: V | |
+----->----->----->------> + | |
| | |
V V V
+------>-----+------<------+
|
V
[po4a-translate]
|
V
XX.doc
(up-to-date)
A la part esquerra s'hi mostra la conversió d'una traducció que no
utilitza po4a a aquest sistema. A dalt de la part dreta s'hi representa
l'acció de l'autor original (actualitzar la documentació). Al mig de
la part dreta s'hi simbolitzen les accions automàtiques de po4a. S'extrau
el nou material i es compara amb la traducció existent. Es troben les
parts que no han canviat, i es fa servir la traducció prèvia. Les
parts parcialment modificades també es connecten a la traducció
anterior, però se li afegeix un marcador indicant que la traducció
s'ha d'actualitzar. La part de baix de la figura mostra com es construeix el
document formatejat.
Actualment, com a traductor, la única operació manual que hauria de
fer-se és la part marcada {edició manual}. Sí, ho sento,
però po4a ajuda a traduir. No tradueix res sol...
Com començar una nova traducció?¶
Aquesta secció presenta els passos necessaris per començar una nova
traducció amb po4a. Els refinaments involucrats a la conversió d'un
projecte existent al d'aquest sistema es detallen a la secció pertinent.
Per començar una nova traducció utilitzant po4a, ha de seguir els
següents passos:
- -
- Extract the text which have to be translated from the
original < master.doc> document into a new translation
template < translation.pot> file (the gettext format). For
that, use the po4a-gettextize program this way:
$ po4a-gettextize -f <format> -m <principal.doc> -p <traducció.pot>
< format> is naturally the format used in the master.doc
document. As expected, the output goes into translation.pot. Please
refer to po4a-gettextize(1) for more details about the existing
options.
- -
- Ara toca traduir el que toca. Per això, canviï el
nom del fitxer POT a doc. XX.po, per exemple (on XX és
el codi ISO639 de l'idioma al que estigui traduint, per exemple fr
pel francès), i editi el fitxer resultant. Sovint és bona idea
no anomenar el fitxer XX.po per evitar confusions amb la
traducció dels missatges de programa però això és cosa
seva. No s'oblidi d'actualitzar les capçaleres dels fitxers PO,
són importants.
The actual translation can be done using the Emacs' or Vi's PO mode,
Lokalize (KDE based), Gtranslator (GNOME based) or whichever program you
prefer to use for them (e.g. Virtaal).
Si desitja aprendre més, definitivament ha de consultar la
documentació de gettext, disponible en el paquet
gettext-doc.
Un cop hagi acabat la traducció, voldrà obtenir la documentació
traduïda i distribuir-la als usuaris junt amb l'original. Per fer-ho,
utilitzi el programa
po4a-translate(1) així (on
XX és
el codi de l'idioma):
$ po4a-translate -f <format> -m <principal.doc> -p <doc-XX.po> -l <XX.doc>
Igual que abans, <
format> és el format utilitzat en el
principal.doc. Però aquest cop el fitxer PO passat amb el
paràmetre
-p és part de l'entrada. Aquesta és la seva
traducció. La sortida va a
XX.doc.
Consulti
po4a-translate(1) per més detalls.
Com actualitzar una traducció amb po4a?¶
To update your translation when the original
master.doc file has changed,
use the
po4a-updatepo(1) program like that:
$ po4a-updatepo -f <format> -m <nou_original.doc> -p <existent.XX.po>
(Consulti
po4a-updatepo(1) per més detalls)
Naturalment, el nou paràgraf del document no es traduirà
màgicament al fitxer PO amb aquesta operació, i necessitarà
actualitzar l'arxiu PO manualment. Tanmateix, pot haver de refer les
traduccions dels paràgrafs que s'hagin modificat una mica. Per assegurar
que no s'oblidi de cap, es marquen com a "difuses" durant el
procés, i s'haurà de treure la marca abans que pugui utilitzar la
traducció a
po4a-translate. De la mateixa manera que per a la
traducció inicial, aquí és millor fer servir el seu editor PO
preferit.
Un cop el seu fitxer PO estigui altra vegada actualitzat, sense cap cadena per
traduir ni cadenes difuses, pot generar el fitxer de documentació
traduït, tal i com s'ha explicat a la secció anterior.
Com convertir una traducció pre-existent a po4a?¶
Often, you used to translate manually the document happily until a major
reorganization of the original
master.doc document happened. Then,
after some unpleasant tries with
diff or similar tools, you want to
convert to po4a. But of course, you don't want to loose your existing
translation in the process. Don't worry, this case is also handled by po4a
tools and is called gettextization.
La gràcia està en que tant el document traduït com l'original
tinguin la mateixa estructura de manera que les eines puguin encaixar els
continguts correctament.
Si està de sort (és a dir, si les estructures dels documents encaixen
a la perfecció), tot funcionarà correctament i haurà acabat en
pocs segons. En cas contrari, haurà d'entendre per què aquest
procés té un nom tan espantós, i hauria d'estar preparat per a
una mica de feina de grunyits. De totes maneres, recordi que aquest és el
preu que ha de pagar per aconseguir després la comoditat de po4a. I la
part bona és que només haurà de fer-ho una vegada.
No puc emfatitzar-ho més. Per facilitar el procés, és important
trobar la versió exacta que es va utilitzar a la traducció. La
millor situació és dóna quan es va anotar quina revisió
del VCS es va fer servir per a la traducció i no es va modificar durant
el procés de traducció, de manera que la pugui utilitzar.
No funcionarà bé si utilitza el text original actualitzat amb la
traducció antiga. És un procés possible, però més
difícil, i realment s'ha d'evitar sempre que sigui possible. De fet,
imagino que si no aconsegueix trobar el text original, la millor solució
és trobar a algú que faci la gettextització per vostè
(però jo no, si us plau ;).
Potser sóc massa catastrofista. Per molt que les coses vagin malament,
segueix sent molt més ràpid que traduir-ho tot altra vegada. Jo vaig
fer la gettextització de la traducció al francès existent de la
documentació de Perl en un dia, encara que les coses
van anar
malament. Eren més de dos megabytes de text, i una traducció nova
hagués pogut durar mesos com a mínim.
Let me explain the basis of the procedure first and I will come back on hints to
achieve it when the process goes wrong. To ease comprehension, let's use above
example once again.
Once you have the old
master.doc again which matches with the translation
XX.doc, the gettextization can be done directly to the PO file
doc.XX.po without manual translation of
translation.pot file:
$ po4a-gettextize -f <format> -m <old_master.doc> -l <XX.doc> -p <doc.XX.po>
Si està de sort, això és tot. Ha convertit la seva antiga
traducció a po4a i ja pot començar amb la tasca
d'actualització. Simplement segueixi el procés explicat unes
seccions abans per sincronitzar el seu arxiu PO amb el document original
més nou, i actualitzi la traducció segons convingui.
Tingui en compte que, encara que tot sembli haver anat bé, encara es poden
produir alguns errors en aquest procés. Això és degut a que
po4a no és capaç d'entendre el text per assegurar-se que la
traducció es refereix a l'original. És per això que les cadenes
es marquen com a "difuses" durant el procés. Haurà de
comprovar cuidadosament cada cadena abans d'eliminar la marca.
Sovint, les estructures dels documents no encaixen a la perfecció, impedint
a
po4a-gettextize realitzar la seva tasca. Arribat a aquest punt, tot
el joc es trasllada a la edició dels fitxers per fer encaixar les seves
maleïdes estructures.
El pot ajudar llegir la secció
Gettextització: com funciona? de
més avall. La comprensió del funcionament intern del procés
l'ajudarà a fer-lo funcionar. El milor és que
po4a-gettextize
dóna molta informació quan alguna cosa no ha anat bé. Primer,
apuntarà on s'ha trobat la discrepància d'estructures en els
documents. Després mostrarà les cadenes que no encaixen, la seva
posició en el text, i el tipus de cadascuna. A més a més, el
fitxer PO generat fins al moment es guardarà a
gettextization.failed.po.
- -
- Borreu totes les parts extres de les traduccions, com per
exemple la secció on s'especifiqui el nom del traductor, o els
agraïments de gent que ha col·laborat a la traducció. Els
apèndix, descrits a la següent secció, li permetran afegir
de nou aquests continguts.
- -
- No dubti a editar tant l'original com la traducció. El
més important és aconseguir el fitxer PO. Ja tindrà temps
d'actualitzar-lo més tard. Un cop dit això, és preferible
editar la traducció quan es puguin editar els dos, ja que això
facilita les coses un cop s'acabi la gettextització.
- -
- Si fa falta, si algunes parts no estaven traduïdes,
elimini-les de l'original. Quan més endavant sincronitzi el fitxer
PO, tornaran a apareixer per sí soles.
- -
- Si ha canviat una mica l'estructura (per ajuntar dos
paràgrafs, o partir-ne algun), desfaci els canvis. Si hi ha problemes
amb l'original, hauria d'informar l'autor original. Arreglar-ho a la
traducció només ho arregla per una part de la comunitat. I a
més, és impossible quan utilitza po4a ;)
- -
- A vegades el contingut del paràgraf encaixa, però
el seu tipus no. Arreglar això depèn molt del format. En POD i
man, a vegades és culpa de que una de les dues línies
comença amb espai i l'altra no. En aquests formats, aquest
paràgraf no podria justificar-se i es tornaria d'un tipus diferent.
Simplement elimini l'espai per solucionar-ho. També pot tractar-se
d'un error tipogràfic al nom del tag.
A més a més, dos paràgrafs poden ajuntar-se en el POD quan la
línea de separació conté alguns espais, o quan no hi ha una
línia de separació abans de la línia =item i del contingut
de l'element.
- -
- A vegades, hi ha una desincronització entre els
fitxers, i la traducció s'encaixa a un paràgraf original
equivocat. Aquest és un signe de que realment ja hi havia un problema
abans. Comprovi gettextization.failed.po per veure quan
comença la desincronització, i arreglar-ho allà.
- -
- A vegades li pot donar la impressió que po4a s'ha
menjat algunes parts del text, ja sigui de l'original o de la
traducció. gettextization.failed.po indica que ambdós
encaixaven correctament, i després ha fallat perquè intentava
encaixar un paràgraf amb l'anterior o el posterior al correcte, com
si el correcte hagués desaparegut. Maleeixi po4a com jo vaig fer el
primer cop que em va passar. Abundantment.
Aquesta situació és deguda a que el mateix paràgraf es
repeteix al llarg del document. En aquest cas, no es crea una nova entrada
al fitxer PO, sinó que se li afegeix una nova referència i la ja
existent.
Per tant, quan el mateix paràgraf apareix dos cops a l'original
però no està traduït exactament igual cada cop, tindrà
la sensació que ha desaparegut un paràgraf de l'original.
Simplement elimini la nova traducció. Si creu que la segona
traducció és millor, tregui-la d'on està, i substitueixi-la
a la primera.
En el cas contrari, si hi ha dos paràgrafs semblants però
diferents que es van traduir de la mateixa forma, li pot donar la
impressió que ha desaparegut un paràgraf de la traducció.
La solució és afegir una cadena estúpida al paràgraf
original (quelcom com "sóc diferent") per solucionar-ho. No
s'espanti. Aquestes coses desapareixeran durant la sincronització, i
quan el text afegit sigui suficientment curt, gettext encaixarà la
seva traducció amb el text existent (marcant-lo com a difús,
però no importa, ja que totes les cadenes es marquen com a difuses
durant la gettextització).
Amb una mica de sort, aquests trucs l'ajudaran a realitzar la seva
gettextització i a obtenir el seu estimat fitxer PO. Ara estarà
preparat per sincronitzar el seu fitxer i començar la traducció.
Tingui en compte, que en textos grans, la primera sincronització pot
tardar força temps.
Per exemple, el primer
po4a-updatepo de la traducció al francès
de la documentació de Perl (un fitxer PO de 5.5Mb) va tardar dos dies
aproximadament en una màquina G5 a 1Ghz. Sí, 48 hores, però les
següents vegades tan sols tardava una dotzena de segons al meu
portàtil vell. Això és perquè la primera vegada, la
majoria de msgids del fitxer PO no encaixen amb cap altre dels del fitxer POT.
Això obliga a gettext a buscar la cadena més semblant utilitzant un
costós algorisme de proximitat de cadenes.
Degut a l'ús de gettext, fer-ho amb po4a és torna més
difícil que abans, ja que simplement s'editava el nou fitxer
paral·lelament a l'original. Però segueix sent possible gràcies
als anomenats
apèndixs.
Per ajudar a la comprensió, consideri els apèndix com uns pegats
aplicats al document traduït després del procés. Són
bastant diferents que els pegats originals (només tenen una línia de
context, que pot incloure una expressió regular de Perl, i únicament
pot afegir text, sense eliminar res), però les funcionalitats són
les mateixes.
El seu objectiu és permetre al traductor afegir contingut extra al
document, que no és traducció del document original. L'ús
més habitual és afegir una secció sobre la traducció en si
mateixa, llistant els col·laboradors i explicant com informar dels errors
de la traducció.
Els apèndixs s'han de proporcionar com fitxers a part. La primera
línia forma una capçalera que indica el lloc del document resultant
on s'ha de col·locar. La resta del fitxer d'apèndix s'afegirà
sense modificacions a la posició determinada del document resultant.
La capçalera té una sintaxi molt rígida: ha de començar amb
la cadena
PO4A-HEADER:, seguida per una llista de camps
clau= valor separats per punt i coma (
;). Els
espais en blanc SÓN importants. Tingui en compte que no pot usar el
caracter punt i coma (
;) en els valors, i que les cometes no ajuden.
Una vegada més, sona espantós, però els exemples de més
endavant haurien d'ajudar-lo a trobar la forma d'escriure la línia de
capçalera que necessiti. Per a il·lustrar la discussió, suposi
que vol afegir una secció anomenada "Sobre aquesta
traducció" després de l'anomenada "Sobre aquest
document".
Aquí hi ha les possibles claus de capçalera:
- position (obligatòria)
- una expressió regular. Es col·locarà
l'apèndix prop de la línia que encaixi amb aquesta
expressió regular. Tingui en compte que estem parlant del document
traduït, no l'original. Si hi ha més d'una línia que
encaixi (o cap), l'addició fallarà. Sempre és millor donar
un error que inserir l'apèndix en el lloc equivocat.
Aquesta línia es diu punt de posició a partir d'ara. El
punt on s'inserirà l'apèndix es diu punt d'inserció.
Aquests dos punts són molt propers, però no iguals. Per exemple,
si desitja inserir una nova secció, és més fàcil posar
el punt de posició en el títol de la secció
anterior, i explicar-li a po4 on acaba la secció (recordi que el
punt de posició ve donat per l'expressió regular, que ha
d'encaixar una única línia).
La localizació del punt d'inserció respecte el punt de
posició està controlat pels camps mode,
beginboundary i endboundary, que s'expliquen a
continuació.
En el nostre cas tindríem:
position=<title>Sobre aquest document</title>
- mode (obligatori)
- Pot valdre les cadenes before (abans) o after
(després), especificant la posició de l'apèndix, relativa
al l<punt de posició>.
Com volem que la nostra nova secció se situï sota de la que hem
encaixat, tenim:
mode=after
- beginboundary (utilitzada només quan
mode=after, i obligatòriament en aquest cas)
- endboundary (idem)
- L'expressió regular que encaixi el final de la
secció després de la qual va l'apèndix.
Quan el mode=after, el punt d'inserció està
després del punt de posició, però no
justament després! Està situat al final de la secció que
comença en el punt de posició, és a dir, abans o
després de la línia encaixada pel paràmetre
???boundary, depenent de si s'ha fet servir
beginboundary o endboundary.
En el nostre cas, podem decidir-nos per indicar el final de la secció
que encaixem afegint:
endboundary=</section>
o indicar el principi de la següent secció indicant:
beginboundary=<section>
En ambdós casos, es col·locarà el nostre apèndix
després de </section> i abans de <section>.
La primera opció és millor perquè funcionarà encara
que re-organitzem el document.
Ambdues formes existeixen degut a que els formats de documentació
són diferents. Alguns tenen maneres de marcar el final d'una
secció (com ara el </section> que acabem de veure),
mentre altres no indiquen explícitament el final de secció (com
passa en man). En el primer cas, interessarà fer un boundary
que encaixi amb el final d'una secció, de forma que el punt
d'inserció vingui just després. En el segon cas, haurem de
fer un boundary que encaixi amb el principi de la següent
secció, de forma que el punt d'inserció vingui just
abans.
Pot semblar obscur, però amb una mica de sort, els següents exemples
l'il·luminaran.
- Seguint amb l'exemple que hem utilitzat fins ara, per tal
d'afegir una secció anomenada "Sobre la traducció"
després de la secció "Sobre aquest document" en un
document SGML, podeu utilitzar qualsevol d'aquestes línies de
capçalera:
-
PO4A-HEADER: mode=after; position=Sobre aquest document; endboundary=</section>
PO4A-HEADER: mode=after; position=Sobre aquest document; beginboundary=<section>
- Si voleu afegir quelcom després de la següent
secció de nroff:
-
.SH "AUTORS"
haureu d'utilitzar un position que encaixi amb aquesta línia, i
un beginboundary que encaixi amb el principi de la següent
secció (com ara ^\.SH). Llavors l'annex s'afegirà
després del punt de posició i immediatament
abans de la primera línia que encaixi amb el
beginboundary. És a dir:
PO4A-HEADER:mode=after;position=AUTORS;beginboundary=\.SH
- Si voleu afegir quelcom a una secció (com ara
després de "Copyright Big Dude") en lloc d'afegir una
secció completa, proporcioneu una position que encaixi amb
aquesta línia, i doneu un beginboundary que encaixi qualsevol
línia.
-
PO4A-HEADER:mode=after;position=Copyright Big Dude, 2004;beginboundary=^
- Si voleu afegir quelcom al final del document, utilitzeu
una position que encaixi amb qualsevol línia del document
(però només una línia. Po4a no seguirà si no és
única), i doneu un endboundary que no encaixi amb res. No
utilitzeu cadenes simples aquí, com ara "EOF",
sinó cadenes que tinguin menys probabilitats de sortir en el vostre
document.
-
PO4A-HEADER:mode=after;position=<title>Quant a</title>;beginboundary=FakePo4aBoundary
En qualsevol cas, recordeu que això són expressions regulars. Per
exemple, si voleu encaixar el final d'una secció de nroff que acabi amb
aquesta línia
.fi
no utilitzeu
.fi com a
endboundary, perquè encaixarà amb
"el[ fi]txer", que obviament no és el què s'esperava. L'
endboundary correcte en aquest cas és:
^\.fi$.
Si l'annexe no es col·loca on esperàveu, proveu de passar el
paràmetre
-vv a les eines, de forma que explicarà què fa
per col·locar l'annexe.
Exemple més detallat
Document original (en format POD):
|=head1 NAME
|
|dummy - a dummy program
|
|=head1 AUTHOR
|
|me
Llavors, el següent annexe s'assegurarà de que s'afegeix una
secció (en català) sobre el traductor al final del fitxer.
|PO4A-HEADER:mode=after;position=AUTOR;beginboundary=^=head
|
|=head1 TRADUCTOR
|
|jo
Per tal de posar l'annexe abans d'AUTHOR, utilitzeu la següent
capçalera:
PO4A-HEADER:mode=after;position=NOM;beginboundary=^=head1
Això funciona perquè la següent línia que encaixa el
beginboundary /^=head1/ després de la secció "NAME"
(traduït com a "NOM" en català), és la que declara
els autors. Per tant, l'annexe es col·locarà entre ambdues seccions.
Com fer tot això en una sola invocació al
programa?¶
La utilització de po4a ha demostrat ser una mica confusa per als usuaris,
ja que s'han de cridar dos programes diferents, en l'ordre adequat (
po4a-updatepo i després
po4a-translate), on cadascun d'ells
necessita més de 3 paràmetres. A més, amb aquest sistema era
difícil utilitzar un únic fitxer PO per tots els documents quan
s'utilitzava més d'un format.
El programa
po4a(1) va ser dissenyat per solucionar aquestes dificultats.
Una vegada heu convertit el vostre projecte a aquest sistema, escriviu un
fitxer simple de configuració, explicant on són els fitxers de
traducció (PO i POT), on són els documents originals, els seus
formats, i on s'han de col·locar les traduccions.
Després, una crida a
po4a(1) sobre aquest fitxer assegura que els
fitxers PO se sincronitzen amb el document original, i que el document
traduït es genera correctament. Per suposat, segurament voldreu cridar
aquest programa dues vegades: una abans d'editar el fitxer PO per
actualitzar-lo, i una altra després, per obtenir els documents
traduïts completament actualitzats. Però únicament haureu de
recordar una línia de comandes.
HOWTO customize po4a?¶
po4a modules have options (specified with the
-o option) that can be used
to change the module behavior.
It is also possible to customize a module or new / derivative / modified modules
by putting a module in
lib/Locale/Po4a/, and adding
lib to the
paths specified by the PERLLIB or PERL5LIB environment. For example:
PERLLIB=$PWD/lib po4a --previous po4a/po4a.cfg
Note: the actual name of the lib directory is not important.
Com funciona?¶
Aquest capítol ofereix una breu explicació del funcionament intern de
po4a, de manera que es pugui sentir més segur per ajudar-nos a
mantenir-lo i a millorar-lo. També el pot ajudar a entendre perquè
no fa el què esperava, i com solucionar problemes.
Visió general¶
L'arquitectura de po4a és orientada a objectes (en Perl. No és
estupend?). L'avantpassat comú de totes les classes dels analitzadors
s'anomena TransTractor. Aquest nom tan estrany ve del fet que s'encarrega
simultàniament de traduir el document i d'extreure les cadenes.
Més formalment, rep com a entrada un document a traduir junt amb un fitxer
PO que conté les traduccions a utilitzar, i produeix dues sortides
separades: un altre fitxer PO (resultant de l'extracció de les cadenes
traduïbles del document d'entrada), i un document traduït (amb la
mateixa estructura que el d'entrada, però amb les cadenes traduïbles
canviades pel contingut del PO d'entrada). Aquí hi ha una
representació gràfica:
Document d'entrada -\ /---> Document de sortida
\ TransTractor:: / (traduït)
+-->- parse() ------+
/ \
PO d'entrada -------/ \---> PO de sortida
(extret)
Aquest petit eix és el nucli de tota l'arquitectura de po4a. Si s'omet el
PO d'entrada i el document de sortida, s'obté
po4a-gettextize. Si
proporcioneu ambdues entrades i ometeu el fitxer PO de sortida, obteniu
po4a-translate.
TransTractor::parse() és una funció virtual implementada per
cada mòdul. Aquí hi ha un petit exemple per mostrar com funciona.
Aquest analitza una llista de paràgrafs, on cadascun comença amb
<p>.
1 sub parse {
2 PARAGRAF: while (1) {
3 $my ($paragraf,$pararef,$linia,$lref)=("","","","");
4 $my $primer=1;
5 while (($linia,$lref)=$document->shiftline() && defined($linia)) {
6 if ($linia =~ m/<p>/ && !$primer--; ) {
7 $document->unshiftline($linia,$lref);
8
9 $paragraf =~ s/^<p>//s;
10 $document->pushline("<p>".$document->translate($paragraf,$pararef));
11
12 next PARAGRAF;
13 } else {
14 $paragraf .= $linia;
15 $pararef = $lref unless(length($pararef));
16 }
17 }
18 return; # No tenim una línia definida? Final del fitxer d'entrada.
19 }
20 }
A la línia 6, trobem
<p> per segona vegada. Això vol dir
que comença el següent paràgraf. Llavors tornem la línia
que acabem d'obtenir cap al document original (línia 7) i enviar el
paràgraf que hem construït fins al moment cap a les sortides.
Després d'eliminar-ne el
<p> a la línia 9, enviem la
concatenació d'aquest tag amb la traducció de la resta del
paràgraf.
Aquesta funció
translate() està molt bé. Insereix el seu
paràmetre cap al fitxer PO de sortida (extracció) i en retorna la
traducció que troba al fitxer PO d'entrada (traducció). Com que
això s'utilitza com a part del paràmetre de
pushline(),
aquesta traducció va a parar al document de sortida.
Com mola, no? Es pot escriure un mòdul complet de po4a en menys de 20
línies si el format és suficientment simple...
Podeu aprendre més sobre això a
Locale::Po4a::TransTractor(3pm).
Gettextització: com funciona?¶
La idea és agafar el document original i la seva traducció, i suposar
que l'enèsima cadena extreta de la traducció, és la
traducció de l'enèsima cadena de l'original. Perquè funcioni,
ambdós fitxers han de compartir exactament la mateixa estructura. Per
exemple, si els fitxers tenen la següent estructura, es molt poc probable
que la quarta cadena de la traducció (del tipus 'capítol') sigui la
traducció de la quarta cadena de l'original (del tipus 'paràgraf').
Original Traducció
capítol capítol
paràgraf paràgraf
paràgraf paràgraf
paràgraf capítol
capítol paràgraf
paràgraf paràgraf
Per fer això, els analitzadors de po4a s'utilitzen en l'original i en la
traducció per extreure fitxers PO, i després es construeix un tercer
fitxer PO a partir d'aquests prenent les cadenes del segon com a traduccions
de les cadenes del primer. Per tal de comprovar que les cadenes que ajuntem
siguin realment traducció l'una de l'altra, els analitzadors de documents
de po4a han de desar informació sobre el tipus sintàctic de les
cadenes del document (tots els existents ho fan, el vostre també hauria
de fer-ho). Després, aquesta informació s'utilitza per assegurar que
ambdós documents tenen la mateixa sintaxi. A l'exemple anterior,
això ens permetria detectar que la quarta cadena és un paràgraf
en un cas, i un títol de capítol a l'altre cas, i podriem informar
del problema.
En teoria, seria possible detectar el problema, i resincronitzar el fitxer
després (tal com fa
diff). Però no està clar què
hauriem de fer amb les cadenes d'abans de la dessincronització, i podria
produir mals resultats a vegades. És per això que la
implementació actual no intenta resincronitzar res i fallarà donant
informació quan alguna cosa vagi malament, requerint la modificació
manual dels fitxers per solventar el problema.
Fins i tot amb aquestes precaucions, les coses poden empitjorar amb molta
facilitat. És per això que totes les traduccions extretes d'aquesta
forma es marquen com a difuses per assegurar que el traductor les repassi i
les comprovi.
Annexes: Com funciona?¶
Bé, això és força simple. El document traduït no
s'escriu directament al disc, sinó que es manté en memòria fins
que s'han aplicat tots els annexes. L'algorisme involucrat és força
simple. Busquem la línia que encaixa amb l'expressió regular de
posició, i si hi havia el
mode=before, insertem l'annexe abans.
Sinó, busquem la següent línia que encaixi amb el boundary i
insertem l'annexe després d'aquesta línia, si és un
endboundary o abans, si és un
beginboundary.
PMF¶
Aquest capítol agrupa les Preguntes Més Freqüents. De fet, la
majoria de preguntes actuals es poden formular d'aquesta manera: "Per
què s'ha dissenyat d'aquesta forma i no d'una altra?" Si pensa que
po4a no és la solució ideal per a la traducció de
documentació, hauria de considerar llegir-se aquesta secció. Si no
respon les seves preguntes, contacti amb nosaltres a la llista de correu
<po4a-devel@lists.alioth.debian.org>. Volem saber la seva opinió.
Perquè hem de traduir cada paràgraf per separat?¶
Sí, a po4a, cada paràgraf s'ha de traduir per separat (de fet, cada
mòdul ho decideix, però tots els existents ho fan, i els vostres
també ho haurien de fer). Aquest enfoc té dos avantatges principals:
- •
- Quan les parts tècniques del document s'amaguen, el
traductor no s'hi pot embolicar. Com menys marques presentem al traductor,
menys es pot equivocar.
- •
- Tallar el document ajuda a aïllar els canvis del
document original. Quan l'original es modifiqui, aquest procés
facilitarà la cerca de parts de la traducció que necessiten
actualització.
Tot i aquests avantatges, a alguna gent no li agrada la idea de traduir els
paràgrafs per separat. Aquí hi ha algunes de les respostes que puc
donar a les seves pors:
- •
- Aquest enfoc s'ha demostrat exitós al projecte KDE i
ha permès a la seva gent produir la quantitat més gran de
documentació traduïda i actualitzada que conec.
- •
- Els traductors encara poden utilitzar el context per
traduir, ja que les cadenes del fitxer PO estan en el mateix ordre que en
el document original. Una traducció seqüencial serà molt
semblant tant si utilitzeu po4a com si no. I en qualsevol cas, la millor
manera d'aconseguir el context segueix sent convertir el document a un
format imprimible, ja que els formatats de text no són llegibles, en
la meva opinió.
- •
- Aquest enfoc és el que utilitzen els traductors
professionals. Estic d'acord que ells tenen uns objectius una mica
diferents que els dels traductors de programari lliure. Per exemple, el
manteniment és habitualment menys crític per ells ja que el
contingut no és gaire variable.
Perquè no partir a nivell de frase (o inferior)?¶
Les eines de traducció professionals a vegades parteixen el document a
nivell de frases per tal de maximitzar la reusabilitat de les traduccions
prèvies i accelerar el procés. El problema és que la mateixa
frase pot tenir diverses traduccions, depenent del context.
Els paràgrafs són més llargs que les frases, per definició.
Això pràcticament permet assegurar que un mateix paràgraf en
dos documents tindrà el mateix significat (i traducció), a part del
context de cada cas.
Partir en parts més petites que frases seria
molt dolent. Seria una
mica llarg d'explicar el motiu aquí, però si li interessa el tema,
consulti la pàgina de manual de
Locale::Maketext::TPJ13(3pm) (que
ve amb la documentació de Perl), per exemple. Per resumir, cada idioma
té les seves pròpies regles de sintaxi, i no es poden construir
frases annexant troços, i que funcioni per tots els llenguatges existents
(ni tan sols per 5 dels 10 més parlats, o fins i tot menys).
Perquè no posem l'original com a comentari prop de la
traducció (o d'alguna altra manera)?¶
A primer cop d'ull, gettext no sembla estar adaptat a tot tipus de traduccions.
Per exemple, no semblava estar adaptat a debconf, la interfície que
utilitzen els paquets de Debian per la seva interacció amb l'usuari
durant la instal·lació. En aquest cas, els texts a traduir eren molt
curts (una dotzena de línies per cada paquet), i era difícil posar
les traduccions en un fitxer especialitzat, ja que ha d'estar disponible abans
de la instal·lació del paquet.
És per això que els desenvolupadors de debconf van decidir implementar
una altra solució, on les traduccions es desaven en el mateix fitxer que
l'original. Pot semblar atractiu. Algú podria voler-ho fer amb XML, per
exemple. Tindria aquesta pinta:
<section>
<title lang="en">My title</title>
<title lang="ca">El meu títol</title>
<para>
<text lang="en">My text.</text>
<text lang="ca">El meu text.</text>
</para>
</section>
Però això va ser tan problemàtic que ara es torna a utilitzar una
solució basada en fitxers PO. Tan sols es pot editar l'original en el
fitxer, i les traduccions s'han ded fer en fitxers PO extrets de la plantilla
original (i es munta tot a l'hora de compilar el paquet). El sistema vell es
va determinar obsolet per diversos motius:
- •
- problemes de manteniment
Si diversos traductors proporcionen pegats alhora, es complica la feina de
fusionar-los.
Com detectareu canvis a l'original, que necessiten aplicar-se a les
traduccions? Per tal d'utilitzar diff, heu de tenir en compte quina
versió de l'original heu traduït. És a dir, necessiteu un
fitxer PO al vostre fitxer ;)
- •
- problemes de codificació
Aquesta solució és viable quan tan sols intervenen llengües
europees, però la introducció del coreà, el rus i/o
l'àrab compliquen la situació notablement. Una solució
podria ser utilitzar UTF, però encara hi ha alguns problemes amb
això.
A més, aquests problemes són difícils de detectar (per
exemple, només els lectors coreans detectaran que la codificació
del coreà és incorrecta [per culpa del traductor rus])
gettext soluciona tots aquest problemes alhora.
Però gettext no es va dissenyar per a aquest ús!¶
És cert, però fins ara ningú ha trobat cap solució millor.
L'única alternativa coneguda és la traducció manual, amb tots
els problemes de manteniment.
Què hi ha de les altres eines de traducció de
documentació que utilitzen gettext?¶
Pel què sé, tan sols n'hi ha dues:
- poxml
- Aquesta és l'eina desenvolupada per la gent de KDE per
tractar DocBook XML. Si no vaig errat, aquest va ser el primer programa
que extreia les cadenes a traduir de la documentació i en feia
fitxers PO, i després de la traducció les injectava en el
document.
Tan sols pot tractar XML, i només un DTD particular. M'ha decepcionat
una mica la forma que té de tractar les llistes, que acaba amb un
msgid molt gran. Quan la llista creix, el bloc esdevé difícil de
tractar.
- po-debiandoc
- Aquest programa fet per Denis Barbier és com un
precursor del mòdul SGML de po4a, que més o menys el deixa
obsolet. Com el nom diu, tan sols tracta el DTD de DebianDoc, que és
més o menys un DTD obsolet.
Els avantatges principals de po4a sobre aquests és la facilitat d'afegir
contingut extra (que és encara pitjor allà) i l'habilitat
d'aconseguir la gettextització.
Educant els desenvolupadors sobre les traduccions¶
When you try to translate documentation or programs, you face three kinds of
problems; linguistics (not everybody speaks two languages), technical (that's
why po4a exists) and relational/human. Not all developers understand the
necessity of translating stuff. Even when good willed, they may ignore how to
ease the work of translators. To help with that, po4a comes with lot of
documentation which can be referred to.
Un altre punt important és que cada fitxer traduït comença amb un
breu comentari que indica què és el fitxer i com utilitzar-lo.
Això hauria d'ajudar als pobres desenvolupadors inundats amb pilots de
fitxers en diversos idiomes que no parlen, i els ajudarà a fer bé la
seva feina.
In the po4a project, translated documents are not source files anymore. Since
SGML files are habitually source files, it's an easy mistake. That's why all
files present this header:
| *****************************************************
| * GENERATED FILE, DO NOT EDIT *
| * THIS IS NO SOURCE FILE, BUT RESULT OF COMPILATION *
| *****************************************************
|
| This file was generated by po4a-translate(1). Do not store it (in VCS,
| for example), but store the PO file used as source file by po4a-translate.
|
| In fact, consider this as a binary, and the PO file as a regular source file:
| If the PO gets lost, keeping this translation up-to-date will be harder ;)
Likewise, gettext's regular PO files only need to be copied to the
po/
directory. But
this is not the case of the ones manipulated by po4a.
The major risk here is that a developer erases the existing translation of his
program with the translation of his documentation. (Both of them can't be
stored in the same PO file, because the program needs to install its
translation as an mo file while the documentation only uses its translation at
compile time). That's why the PO files produced by the po-debiandoc module
contain the following header:
#
# ADVISES TO DEVELOPERS:
# - you do not need to manually edit POT or PO files.
# - this file contains the translation of your debconf templates.
# Do not replace the translation of your program with this !!
# (or your translators will get very upset)
#
# ADVISES TO TRANSLATORS:
# If you are not familiar with the PO format, gettext documentation
# is worth reading, especially sections dedicated to this format.
# For example, run:
# info -n '(gettext)PO Files'
# info -n '(gettext)Header Entry'
#
# Some information specific to po-debconf are available at
# /usr/share/doc/po-debconf/README-trans
# or http://www.debian.org/intl/l10n/po-debconf/README-trans
#
RESUM dels avantatges de l'enfoc basat en gettext¶
- •
- The translations are not stored along with the original,
which makes it possible to detect if translations become out of date.
- •
- The translations are stored in separate files from each
other, which prevents translators of different languages from interfering,
both when submitting their patch and at the file encoding level.
- •
- Internament està basat en gettext (però
po4a ofereix una interfície molt simple per tal que no
necessiteu entendre el funcionament intern per tal d'utilitzar-lo).
Així no hem de reinventar la roda, i degut al seu ampli ús,
podem pensar que són unes eines més o menys lliures
d'errors.
- •
- Per l'usuari final no canvia res (a part que les
traduccions es mantindran millor actualitzades :). El fitxer de
documentació resultant distribuït és exactament el
mateix.
- •
- No cal que els traductors aprenguin una nova sintaxi de
fitxer, i podran treballar amb el seu editor de fitxers PO predilecte (com
ara el mode PO d'emacs, Lokalize o Gtranslator).
- •
- gettext offers a simple way to get statistics about what is
done, what should be reviewed and updated, and what is still to do. Some
example can be found at those addresses:
- http://kv-53.narod.ru/kaider1.png
- http://www.debian.org/intl/l10n/
Però no tot és bonic, i aquest enfoc també té alguns
desavantatges que haureu de tenir en compte.
- •
- Els annexes són... estranys, a primer cop d'ull.
- •
- No podeu adaptar el text traduït al vostre gust, com
ara partint paràgrafs per aquí, o ajuntant-ne dos per allà.
Però vist d'una altra manera, si hi ha algun problema amb l'original,
s'hauria d'informar com a error.
- •
- Encara que tingui una interfície fàcil, segueix
sent una nova eina que la gent ha d'aprendre.
Un dels meus somnis és que s'integrés po4a d'alguna manera amb
Gtranslator o Lokalize. Quan s'obrís un document SGML, s'extraurien
automàticament les cadenes. Quan es guardés, es podria escriure
un fitxer SGML traduït al disc. Si aconseguim fer un mòdul per a
MS Word (TM) (o com a mínim RTF) fins i tot podrien utilitzar-lo
traductors professionals.
AUTORS¶
Denis Barbier <barbier,linuxfr.org>
Martin Quinson (mquinson#debian.org)