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

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

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

=encoding UTF-8

=head1 NOMBRE

po4a - Un marco de trabajo para traducir documentación y otro material

=head1 Introducción

po4a (PO para todo) facilita el mantenimiento de traducción de documentación
utilizando las clásicas herramientas gettext. La característica de po4a
principal es que desacopla la traducción del contenido desde su estructura
documental.

Este documento sirve como una introducción para el proyecto po4a con un
enfoque en usuarios potenciales considerando si utiliza esta herramienta y
en la curioso deseo de entender por qué las cosas son de la manera que son.

=head1 ¿Por qué po4a?

La filosofía de Free Software , es hacer que la tecnología está disponible a
cada uno. Pero la licencia no es la única consideración: el software libre
no traducido es inútil para los hablantes no ingleses. Por lo tanto, aún hay
tarea que hacer para crear software disponible para todos.

Esta situación es bien entendida por muchos proyectos y cada uno ahora está
convencido de la necesidad de traducir todo. Aún, las traducciones actuales
representan un enorme esfuerzo de muchos individuales, heridos por pequeñas
dificultades técnicas.

Agradecidamente, el software libre se beneficia de un nivel decente de
traducción gracias al maravilloso conjunto de herramientas gettext. Éste
puede extraer las cadenas a traducir de un programa, presentarlas en un
formato uniforme a los traductores, y luego usar el resultado de su trabajo
durante la ejecución para mostrar los mensajes traducidos al usuario.

En cuanto a la documentación, sin embargo, la situación sigue siendo un
tanto decepcionante.  Al principio, traducir documentación puede parecer más
fácil que traducir un programa, ya que parece que basta con copiar el
archivo fuente de la documentación y empezar a traducir el contenido. Sin
embargo, cuando se modifica la documentación original, hacer un seguimiento
de las modificaciones se convierte rápidamente en una pesadilla para los
traductores. Si se hace manualmente, esta tarea es desagradable y propensa a
errores.

Las traducciones obsoletas suelen ser peores que la ausencia de
traducción. Los usuarios finales pueden ser engañados por documentación que
describe un comportamiento antiguo del programa. Además, no pueden
interactuar directamente con los mantenedores porque no hablan
inglés. Asimismo, el mantenedor no puede solucionar el problema porque no
conoce todos los idiomas a los que se traduce su documentación. Estas
dificultades, a menudo causadas por herramientas deficientes, pueden minar
la motivación de los traductores voluntarios, lo que agrava aún más el
problema.

B<La ambición del proyecto po4a es facilitar el trabajo de los traductores
de la documentación>.  En particular, crea traducciones de documentación
I<mantenibles>.

La idea es reutilizar y adaptar el enfoque de gettext a este campo. Al igual
que con gettext, los textos se extraen de sus ubicaciones originales y se
presentan a los traductores como catálogos de traducción PO. Los traductores
pueden aprovechar las herramientas clásicas de gettext para controlar el
trabajo a realizar, colaborar y organizarse como equipos. po4a inyecta
entonces las traducciones directamente en la estructura de la documentación
para producir archivos fuente traducidos que pueden procesarse y
distribuirse igual que los archivos en inglés. Cualquier párrafo que no se
traduzca se deja en inglés en el documento resultante, asegurando que los
usuarios finales nunca vean una traducción obsoleta en la documentación.

Esto automatiza la mayor parte del trabajo de mantenimiento de la
traducción. Descubrir los párrafos que necesitan una actualización resulta
muy fácil, y el proceso se automatiza por completo cuando los elementos se
reordenan sin más modificaciones. La verificación específica también puede
utilizarse para reducir la posibilidad de errores de formato que darían
lugar a un documento roto.

Por favor, lea también las B<Preguntas frecuentes>, más abajo en éste
documento, para una lista más completa de las ventajas y desventajas de este
enfoque al problema.

=head2 Formatos compatibles

Actualmente se han implementado satisfactoriamente algunos tipos de formato
de texto:

=over

=item man (intérprete maduro)

El clásico formato de las páginas de manual, usado por muchos programas
fuera de allí. La compatibilidad con po4a es bienvenida ya que el formato es
algo difícil de usar, y no muy amistoso para los principiantes.

El módulo L<Locale::Po4a::Man(3pm)|Man> además admite el formato mdoc,
utilizado por las páginas man BSD (no son muy comunes en Linux).

=item AsciiDoc (intérprete maduro)

Este formato es un formato de margen ligero entendido para facilitar la
autoría de documentación. Es utilizado por ejemplo para documentación del
sistema git. Esas páginas man son traducidas utilizando po4a.

Vea L<Locale::Po4a::AsciiDoc> para detalles.

=item pod (intérprete maduro)

Este es el formato «Perl Online Documentation» (Documentación en línea de
Perl). El lenguaje y sus mismas extensiones están documentados utilizando
este formato junto la suma de muchos guiones Perl existentes. Hace muy fácil
mantener la documentación cerca del código al integrarlos en el mismo
fichero. Facilita la vida del programador, pero por desgracia, no la del
traductor, hasta que utilice po4a.

Vea L<Locale::Po4a::Pod> para detalles.

=item sgml (intérprete maduro)

Aunque hoy en día XML lo haya sustituido, este formato aún se usa para
documentos más extensos que unas pocas pantallas. Incluso se puede utilizar
para libros completos. Actualizar documentos de esta longitud puede
convertirse en un reto enorme. A menudo B<diff> se vuelve inútil cuando se
ha sangrado («indented») otra vez el texto original tras una
actualización. Afortunadamente, po4a le puede ayudar tras ese proceso.

Actualmente, sólo son compatibles los DTD de DebianDoc y de DocBook, pero
añadir compatibilidad con uno nuevo es realmente fácil. Incluso es posible
usar po4a con un DTD desconocido de SGML sin cambiar el código introduciendo
la información necesaria en la línea de órdenes. Consulte
L<Locale::Po4a::Sgml(3pm)> para más detalles.

=item TeX / LaTeX (intérprete maduro)

El formato LaTeX es un formato de documentación usado principalmente en el
mundo del Software Libre y para publicaciones.

Se probó el módulo L<Locale::Po4a::LaTeX(3pm)|LaTeX> con la documentación de
Python, un libro y algunas presentaciones.

=item texto (intérprete maduro)

El formato Texto es el formato base para muchos formatos que incluyen
bloques grandes de texto, incluyendo Markdown, fortunes, sección matter de
frente YAML, debian/changelog, y debian/control.

Esto admite el formato común utilizado en Generadores de Sitio Estático,
README, y otros sistemas de documentación. Vea
L<Locale::Po4a::Text(3pm)|Text> para detalles.

=item xml y XHML (intérprete probablemente maduro)

El formato XML sirve de base para muchos formatos de documentación.

Actualmente, el formato DTD de DocBook (vea L<Locale::Po4a::Docbook(3pm)>
para detalles) y XHTML están admitidos por po4a.

=item BibTex (intérprete probablemente maduro)

El formato BibTex es utilizado a lo largo de LaTeX para listados de formato
de referencias (bibliográficos).

Vea L<Locale::Po4a::BibTex> para detalles.

=item Docbook (intérprete probablemente maduro)

Un lenguaje añadido basado en XML que utiliza etiquetados semánticos para
describir documentos.

Vea L<Locale::Po4a:Docbook> para detalles mayores.

=item Guide XML (intérprete probablemente maduro)

Un formato de documentación XML. Este módulo fue desarrollado
específicamente para ayudar con apoyo y mantenimiento de traducciones de
documentación de Linux Gentoo hasta al menos en marzo de 2016 (basado en la
Máquina Wayback). Gentoo desde entonces se ha migrado al formato XML
DevBook.

Vea L<Locale::Po4a:Guide> para detalles mayores.

=item Wml (probablemente intérprete maduro)

El XML (Web Markup Language), no mezcla WML con la materia WAP utilizada en
celdas de teléfonos.  Este módulo depende del módulo XHTML, el mismo que
dependo del módulo XML.

Véase L<Locale::Po4a::Wml> para más detalles.

=item Yaml (probablemente un analizador completo)

Un superconjunto estricto de JSON. YAML se utiliza a menudo como sistemas o
proyectos de configuración.  YAML está en el núcleo de Ansible de Red Hat.

Vea L<Locale::Po4a::Yaml> para más detalles.

=item RubyDoc (probablemente analizador estable)

El formato Ruby Document (RD), originalmente el formato de documentación por
defecto para Ruby y los proyectos Ruby antes de convertirse a RDoc en
2002. Aunque aparentemente la versión japonesa del Manual de Referencia de
Ruby todavía usa RD.

Véase L<Locale::Po4a::RubyDoc> para más detalles.

=item Halibut (analizador sintáctico probablemente experimental)

Un sistema de producción de documentación, con elementos similares a TeX,
debiandoc-sgml, TeXinfo, y otros, desarrollados por Simon Tatham, el
desarrollador de PuTTY.

Vea L<Locale::Po4a:Halibut> para detalles mayores.

=item Ini (probablemente intérprete experimental)

Formado del archivo de configuración popularizado por MS-DOS.

Vea L<Locale::Po4a::Ini> para detalles más grandes.

=item texinfo (intérprete altamente experimental)

Toda la documentación de GNU está escrita en este formato (es incluso un
requisito para ser un proyecto oficial de GNU). La compatibilidad de
L<Locale::Po4a::Texinfo(3pm)|Texinfo> en po4a está en sus inicios. Por
favor, remita informes de fallo y peticiones de funcionalidades.

=item gemtext (analizador sintáctico muy experimental)

El formato nativo del texto plano del protocolo Gemini.  Se usa
habitualmente la extensión C<.gmi>.  El soporte para este módulo en po4a aún
está en pañales.  Si encuentra algo, por favor envíe un error o una petición
de funcionalidad.

=item org (analizador sintáctico muy experimental)

El formato de documento usado por el modo Org.  El soporte para este módulo
en po4a aún está en pañales.  Si encuentra algo, por favor envíe un error o
una petición de funcionalidad.

=item vimhelp (analizador altamente experimental)

El formato utilizado para los archivos de ayuda de Vim (y alguna
documentación de plugins de terceros).  El soporte para el formato en po4a
está todavía en sus inicios.  Si encuentra algo, por favor envíe un informe
de error o una solicitud de extracción.

=item simplepod (very highly experimental parser)

Similar to the previously mentioned I<pod>, this one adopts the new
L<Pod::Simple> as its parser.  Since it is newly created, some bugs are
expected.  If you notice any strange behavior, please let us know.
Eventually, this module will replace I<pod>.

=item Otros formatos admitidos

Po4a también puede tratar algunos formatos raros o específicos, tales como
la documentación de las opciones de compilación de núcleos 2.4+
(L<Locale::Po4a::KernelHelp>) o los diagramas producidos por la herramienta
(L<Locale::Po4a::Dia>). Añadir un formato nuevo es a menudo una tarea muy
sencilla, y la tarea principal es conseguir un intérprete para el formato
escogido. Consulta L<Locale::Po4a::TransTractor(3pm)> para más información.

=item Formatos no compatibles

Desafortunadamente, po4a aún le falta compatibilidad para formatos de
documentación. Muchos de ellos serían sencillos de mantener en po4a. Esto
incluye formatos no tan solo utilizados para documentación, como
descripciones de paquetes (deb y rpm), guiones de instalación de paquetes ,
boletines del paquete, y todos los formatos de archivos especializados
utilizados por los programas tales como escenarios de juegos o los archivos
de recursos de wine.

=back

=head1 Cómo utilizar po4a

La forma más sencilla de utilizar esta herramienta en su proyecto es
escribir un fichero de configuración para el programa B<po4a>, e interactuar
únicamente con este programa. Consulte su documentación, en L<po4a(1)>. El
resto de esta sección proporciona más detalles para los usuarios avanzados
de po4a que quieran profundizar en su comprensión.

=head2 Esquema detallado del flujo de trabajo po4a

Asegúrese de leer L<po4a(1)> antes de esta sección excesivamente detallada
para obtener una visión simplificada del flujo de trabajo de po4a. Vuelva
aquí cuando quiera obtener la imagen completa que asusta, con casi todos los
detalles.

En el siguiente esquema, F<master.doc> es un nombre de ejemplo para la
documentación a traducir; F<XX.doc> es el mismo documento traducido al
idioma XX mientras que F<doc.XX.po> es el catálogo de traducción para ese
documento en el idioma XX. Los autores de la documentación se ocuparán
principalmente de F<master.doc> (que puede ser una página de manual, un
documento XML, un fichero AsciiDoc, etc); los traductores se ocuparán
principalmente del fichero PO, mientras que los usuarios finales solo verán
el fichero F<XX.doc>.

Las transiciones con corchetes como C<[po4a updates po]> representan la
ejecución de una herramienta po4a mientras que las transiciones con
corchetes como C<{update of master.doc}> representan una modificación manual
de los archivos del proyecto.

                                   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 updates po]                  |
          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 updates translations]
                                                  |
                                                  V
                                                XX.doc
                                             (up-to-date)

De nuevo, este esquema es excesivamente complicado. Consulta L<po4a(1)> para
obtener una visión simplificada.

La parte izquierda muestra cómo se puede usar L<po4a-gettextize(1)> para
convertir un proyecto de traducción existente a la infraestructura
po4a. Este script toma un documento original y su contrapartida traducida, e
intenta construir el archivo PO correspondiente. Esta conversión manual es
bastante engorrosa (consulte la documentación de L<po4a-gettextize(1)> para
más detalles), pero solo es necesaria una vez para convertir sus
traducciones existentes. Si no tiene ninguna traducción que convertir, puede
olvidarse de esto y centrarse en la parte derecha del esquema.

En la parte superior derecha se representa la acción del autor original, que
actualiza la documentación.  La parte central derecha muestra la
actualización automática de los archivos de traducción: se extrae el nuevo
material y se compara con la traducción existente. La traducción anterior se
utiliza para las partes que no han cambiado, mientras que las partes
parcialmente modificadas se conectan a la traducción anterior con un
marcador "difuso" que indica que la traducción debe actualizarse. El
material nuevo o muy modificado se deja sin traducir.

A continuación, el bloque I<edición manual> representa la acción de los
traductores, que modifican los ficheros PO para proporcionar traducciones a
cada cadena y párrafo originales. Esto se puede hacer usando un editor
específico como el B<GNOME Translation Editor>, B<Lokalize> o B<poedit> de
KDE, o usando una plataforma de localización online como B<weblate> o
B<pootle>. El resultado de la traducción es un conjunto de ficheros PO, uno
por idioma. Por favor, consulte la documentación de gettext para más
detalles.

La parte inferior de la figura muestra cómo B<po4a> crea un documento fuente
traducido a partir del documento original F<master.doc> y el catálogo de
traducción F<doc.XX.po> actualizado por los traductores. La estructura del
documento se reutiliza, mientras que el contenido original se sustituye por
su homólogo traducido. Opcionalmente, se puede utilizar un apéndice para
añadir texto adicional a la traducción. Suele utilizarse para añadir el
nombre del traductor al documento final. Para más detalles, véase más abajo.

Al invocarlo, B<po4a> actualiza automáticamente tanto los archivos de
traducción como los archivos de documentación traducidos.

=head2 Iniciar un nuevo proyecto de traducción

Si empieza desde cero, sólo tiene que escribir un fichero de configuración
para po4a, y listo.  Se crearán las plantillas relevantes para los ficheros
que falten, permitiendo a sus colaboradores traducir su proyecto a su
idioma. Por favor, consulte L<po4a(1)> para un tutorial de inicio rápido y
para todos los detalles.

Si tiene una traducción existente, es decir, un fichero de documentación que
se tradujo manualmente, puede integrar su contenido en su flujo de trabajo
po4a usando B<po4a-gettextize>. Esta tarea es un poco engorrosa (como se
describe en la página de manual de la herramienta), pero una vez que su
proyecto se convierta al flujo de trabajo po4a, todo se actualizará
automáticamente.

=head2 Actualización de traducciones y documentos

Una vez configurado, basta con invocar B<po4a> para actualizar tanto los
ficheros PO de traducción como los documentos traducidos. Puede pasar
C<--no-translations> a B<po4a> para no actualizar las traducciones
(actualizando así sólo los ficheros PO) o C<--no-update> para no actualizar
los ficheros PO (actualizando así sólo las traducciones). Esto corresponde
aproximadamente a los scripts individuales B<po4a-updatepo> y
B<po4a-translate> que ahora están obsoletos (vea "Por qué están obsoletos
los scripts individuales" en las FAQ más abajo).

=head2 Al utilizar adenda para agregar texto adicional para traducciones

Agregando texto nuevo para la traducción es probablemente la única cosa que
es más fácil en la dirección larga cuando traduzca archivos manualmente
:). Esto ocurre cuando desea añadir una sección adicional para el documento
traducido, no correspondiente a ningún contenido dentro del documento
original. La utilización clásica de caso es dar reconocimientos al equipo de
traducción, y para indicar como informar problemas específicos de
traducción.

Con po4a, tiene que especificar archivos B<anexos>, que pueden verse
conceptualmente como parches aplicados al documento localizado después de
procesarlo. Cada anexo debe proporcionarse como un archivo separado, cuyo
formato es, sin embargo, muy diferente de los parches clásicos. La primera
línea es una I<línea de encabezamiento>, que define el punto de inserción
del anexo (con una sintaxis desafortunadamente críptica -- ver más abajo)
mientras que el resto del archivo se añade textualmente en la posición
determinada.

La línea de encabezado debe comenzar con la cadena B<PO4A-HEADER:>, seguida
de una lista de campos I<clave>B<=>I<valor> separados por punto y coma.

Por ejemplo, el siguiente encabezamiento declara un anexo que debe colocarse
al final de la traducción.

 PO4A-HEADER: mode=eof

Las cosas se complican cuando desea añadir su contenido adicional en medio
del documento. La siguiente cabecera declara un anexo que debe colocarse
después de la sección XML que contiene la cadena C<Acerca de este documento>
en la traducción.

 PO4A-HEADER: position=About this document; mode=after; endboundary=</section>

En la práctica, al intentar aplicar un anexo, po4a busca la primera línea
que coincida con el argumento de C<posición> (puede ser una regexp). No
olvide que po4a considera aquí el documento B<traducido>. Esta documentación
está en inglés, pero su línea probablemente debería decir lo siguiente si
pretende que su anexo se aplique a la traducción francesa del documento.

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

Una vez encontrada la C<posición> en el documento destino, po4a busca la
siguiente línea después de la C<posición> que coincida con el C<endboundary>
proporcionado. El anexo se añade justo B<después> de esa línea (porque
proporcionamos un I<endboundary>, es decir, un límite que termina la sección
actual).

Se podría obtener exactamente el mismo efecto con la siguiente cabecera, que
es equivalente:

 PO4A-HEADER: position=About this document; mode=after; beginboundary=<section>

A continuación, el bloque I<edición manual> representa la acción de los
traductores, que modifican los ficheros PO para proporcionar traducciones a
cada cadena y párrafo originales. Esto puede hacerse usando un editor
específico como el B<GNOME Translation Editor>, B o B para
KDE<Lokalize><poedit>, o usando una plataforma de localización online como
B<weblate> o B<pootle>. El resultado de la traducción es un conjunto de
ficheros PO, uno por idioma. Consulte la documentación de gettext para más
detalles.

También se puede asignar a la inserción I<mode> el valor C<before>, con una
semántica similar: si se combina C<mode=before> con un C<endboundary>, el
apéndice se situará justo B<after> del límite coincidente, es decir, la
última línea límite potencial antes de la C<position>. Si se combina
C<mode=before> con C<beginboundary>, el apéndice se situará justo B<before>
del límite coincidente, es decir, la última línea límite potencial antes de
C<position>.

  Mode   | Boundary kind |     Used boundary      | Insertion point compared to the boundary
 ========|===============|========================|=========================================
 'before'| 'endboundary' | last before 'position' | Right after the selected boundary
 'before'|'beginboundary'| last before 'position' | Right before the selected boundary
 'after' | 'endboundary' | first after 'position' | Right after the selected boundary
 'after' |'beginboundary'| first after 'position' | Right before the selected boundary
 'eof'   |   (none)      |  n/a                   | End of file

=head3 Consejos y trucos sobre los anexos

=over

=item

Recuerde que se trata de regexp. Por ejemplo, si quiere que coincida con el
final de una sección nroff que termina con la línea C<.fi>, no utilice
C<.fi> como B<endboundary>, porque esto coincidirá con C<el[ fi]chero>, que
obviamente no es lo que espera. El B<endboundary> correcto en este caso
sería: C<^\.fi$>.

=item

Los espacios en blanco SÍ son importantes en el contenido de C<position> y
los límites. Así que las dos líneas siguientes B<son diferentes>. La segunda
sólo se encontrará si hay suficientes espacios finales en el documento
traducido.

 PO4A-HEADER: position=About this document; mode=after; beginboundary=<section>
 PO4A-HEADER: position=About this document ; mode=after; beginboundary=<section>

=item

Aunque se puede considerar que esta búsqueda de contexto funciona
básicamente en cada línea del documento B<traducido>, en realidad funcionan
a partir de la cadena de datos interna del documento traducido. Esta cadena
de datos interna puede ser un texto que comprende un párrafo de varias
líneas, o una etiqueta XML individual. El I<punto de inserción> preciso del
apéndice se debe encontrar antes o después de la cadena de datos interna, y
no puede encontrarse dentro de la cadena de datos interna.

=item

Pase el argumento C<-vv> a B<po4a> para entender cómo se añaden las adendas
a la traducción. También puede ayudar ejecutar B<po4a> en modo depuración
para ver la cadena de datos interna real cuando no se aplica su adenda.

=back

=head3 Ejemplos de anexos

=over

=item

Si desea añadir algo después de la siguiente sección de nroff:

  .SH "AUTHORS"

Debe seleccionar un enfoque de dos pasos estableciendo B<mode=after>. A
continuación, debe limitar la búsqueda a la línea posterior a B<AUTHORS> con
el argumento regex B<position>. A continuación, debe hacer coincidir el
comienzo de la siguiente sección (es decir, B<^\.SH>) con el argumento regex
B<beginboundary>. Es decir:

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

=item

Si desea añadir algo justo después de una línea concreta (por ejemplo
después de «Copyright Big Dude») utilice un C<position> que encaje con esta
línea, B<mode=after> e introduzca un B<beginboundary> que encaje con
cualquier linea.

 PO4A-HEADER:mode=after;position=Copyright Big Dude, 2004;beginboundary=^

=item

Si desea añadir algo al final del documento, especifique un B<position> que
encaje con cualquier linea del documento (pero sólo una línea. po4a no
procederá si no es única), y ponga un B<endboundary> que no encaje con
nada. No utilice cadenas simples como B<"EOF">, sino las que tengan menos
probabilidad de salir en el documento.

 PO4A-HEADER:mode=after;position=About this document;beginboundary=FakePo4aBoundary

=back

=head3 Ejemplo más detallado

Documento original (en formato POD):

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

Luego, el siguiente apéndice asegurará que se añade una sección (en español)
sobre el traductor al final del fichero.

 |PO4A-HEADER:mode=after;position=AUTEUR;beginboundary=^=head
 |
 |=head1 TRADUCTEUR
 |
 |moi
 |

Para poner su anexo antes del AUTOR, utilice la siguiente cabecera:

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

Esto funciona porque la siguiente línea que coincide con la B<beginboundary>
C</^=head1/> después de la sección "NAME" (traducido a "NOM" en francés), es
la que declara los autores. Así pues, el addendum se colocará entre ambas
secciones. Tenga en cuenta que si más tarde se añade otra sección entre las
secciones NOMBRE y AUTOR, po4a pondrá erróneamente la adenda antes de la
nueva sección.

Para evitarlo, puede lograr el mismo efecto utilizando B<mode>=I<before>:

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

=head1 ¿Cómo funciona?

Este capítulo le da una breve visión general del funcionamiento interno de
po4a, para que se sienta más seguro a la hora de ayudarnos a mantenerlo y
mejorarlo. También puede ayudarle a entender por qué no hace lo que
esperaba, y cómo resolver sus problemas.

=head2 TransTractors y arquitectura de proyectos

En el núcleo del proyecto po4a, la clase
L<Locale::Po4a::TransTractor(3pm)|TransTractor> es el ancestro común de
todos los analizadores sintácticos de po4a. Este extraño nombre proviene del
hecho de que se encarga al mismo tiempo de traducir el documento y de
extraer las cadenas.

Más formalmente, toma un documento para traducir más un fichero PO que
contiene las traducciones para utilizarlo como entrada, al tiempo que
produce dos salidas separadas: Otro fichero PO (resultante de la extracción
de cadenas traducibles del documento de entrada), y un documento traducido
(con la misma estructura que el de entrada, pero con todas las cadenas
traducibles sustituidas por contenido del PO de entrada). He aquí una
representación gráfica de esto:

   Input document --\                             /---> Output document
                     \      TransTractor::       /       (translated)
                      +-->--   parse()  --------+
                     /                           \
   Input PO --------/                             \---> Output PO
                                                       (extracted)

Este pequeño hueso es el núcleo de toda la arquitectura po4a. Si proporciona
ambos PO de entrada y no tiene en cuenta el PO de salida, obtiene
B<po4a-translate>. Si no tiene en cuenta el documento de salida, obtiene
B<po4a-updatepo>. B<po4a> utiliza un primer TransTractor para obtener un
fichero POT de salida actualizado (sin tener en cuenta los documentos de
salida), llama a B<msgmerge -U> para actualizar los ficheros PO de
traducción en disco, y construye un segundo TransTractor con estos ficheros
PO actualizados para actualizar los documentos de salida. En resumen,
B<po4a> proporciona una solución única para actualizar lo que sea necesario,
utilizando un único archivo de configuración.

B<po4a-gettextize> también usa dos TransTractores, pero de otra forma:
Construye un TransTractor por idioma, y luego construye un nuevo fichero PO
usando los msgids del documento original como msgids, y los msgids del
documento traducido como msgstrs. Hay que tener mucho cuidado para
asegurarse de que las cadenas emparejadas de esta forma realmente coinciden,
como se describe en L<po4a-gettextize(1)>.

=head2 Analizadores sintácticos de formatos específicos

Todos los analizadores de formato po4a se implementan sobre el
TransTractor. Algunos son muy simples, como los de Text, Markdown y
AsciiDoc. Cargan las líneas una a una usando C<TransTractor::shiftline()>,
acumulan el contenido de los párrafos o lo que sea. Una vez que una cadena
está completamente analizada, el analizador usa C<TransTractor::translate()>
para (1) añadir esta cadena al fichero PO de salida y (2) obtener la
traducción del fichero PO de entrada. El parseador entonces empuja el
resultado al fichero de salida usando C<TransTractor::pushline()>.

Algunos otros analizadores sintácticos son más complejos porque dependen de
un analizador sintáctico externo para analizar el documento de entrada. Los
analizadores sintácticos Xml, HTML, SGML y Pod están construidos sobre
analizadores sintácticos SAX. Declaran retrollamadas a eventos como "He
encontrado un nuevo título cuyo contenido es el siguiente" para actualizar
el documento de salida y los archivos POT de salida según el contenido de
entrada utilizando C<TransTractor::translate()> y
C<TransTractor::pushline()>. El analizador Yaml es similar pero diferente:
serializa una estructura de datos producida por el analizador
YAML::Tiny. Esta es la razón por la que el módulo Yaml de po4a no declara
las líneas de referencia: la localización de cada cadena en el fichero de
entrada no la guarda el analizador, por lo que sólo podemos proporcionar
"$nombredefichero:1" como localización de la cadena. Los analizadores
sintácticos orientados a SAX usan globales y otros trucos para guardar el
nombre del fichero y los números de línea de las referencias.

Un problema específico surge de las codificaciones de archivos y los
marcadores BOM. Los analizadores sintácticos simples pueden olvidarse de
este problema, que es manejado por C<TransTractor::read()> (usado
internamente para obtener las líneas de un documento de entrada), pero los
módulos que dependen de un analizador sintáctico externo deben asegurarse de
que todos los ficheros se leen con una capa de decodificación PerlIO
apropiada. Lo más fácil es abrir el fichero tú mismo, y proporcionar un
filehandle o directamente la cadena completa a tu parser externo. Mira en
C<Pod::read()> y C<Pod::parse()> para ver un ejemplo. El contenido leído por
el TransTractor se ignora, pero se pasa un nuevo filehandle al analizador
externo. La parte importante es el modo C<< "<:encoding($charset)" >> que se
pasa a la función perl B<open()>.

=head2 Objetos Po

La clase L<Locale::Po4a::Po(3pm)|Po> se encarga de cargar y usar ficheros PO
y POT. Básicamente, puede leer un fichero, añadir entradas, obtener
traducciones con el método B<gettext()>, escribir el PO en un
fichero. Funciones más avanzadas como fusionar un fichero PO con un fichero
POT o validar un fichero se delegan en B<msgmerge> y B<msgfmt>
respectivamente.

=head2 Contribuir a po4a

Incluso si nunca ha contribuido a ningún proyecto de código abierto en el
pasado, es bienvenido: estamos dispuestos a ayudarle y guiarle. po4a es
mejor mantenido por sus usuarios hoy en día. Como nos falta mano de obra,
intentamos hacer el proyecto acogedor mejorando la documentación y las
pruebas automáticas para que tenga confianza en contribuir al proyecto. Por
favor, consulte el archivo CONTRIBUTING.md para más detalles.

=head1 Proyectos de código abierto que utilizan po4a

Aquí hay una lista muy parcial de proyectos que usan po4a en producción para
su documentación. Si desea añadir su proyecto a la lista, envíenos un correo
electrónico (o una Merge Request).

=over

=item

adduser (man): herramienta de gestión de usuarios y grupos.

=item

apt (man, docbook): Gestor de paquetes Debian.

=item

aptitude (docbook, svg): gestor de paquetes basado en la terminal para
Debian

=item

L<F-Droid website|https://gitlab.com/fdroid/fdroid-website> (markdown):
catálogo instalable de aplicaciones FOSS (Software libre y de código
abierto) para la plataforma Android.

=item

L<git|https://github.com/jnavila/git-manpages-l10n> (asciidoc): sistema
distribuido de control de versiones para el seguimiento de cambios en el
código fuente.

=item

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

Este proyecto proporciona una infraestructura para traducir muchas páginas
de manual a diferentes idiomas, listas para su integración en varias de las
principales distribuciones (Arch Linux, Debian y derivados, Fedora).

=item

L<Stellarium|https://github.com/Stellarium/stellarium> (HTML): un planetario
libre de código abierto para su ordenador. po4a se utiliza para traducir las
descripciones de la cultura celeste.

=item

L<Jamulus|https://jamulus.io/> (markdown, yaml, HTML): una aplicación FOSS
para interferir en línea en tiempo real. La documentación del sitio web se
mantiene en varios idiomas utilizando po4a.

=item

Otro tema a solucionar: L<https://gitlab.com/fdroid/fdroid-website/>
L<https://github.com/fsfe/reuse-docs/pull/61>

=back

=head1 Preguntas frecuentes

=head2 ¿Cómo se pronuncia po4a?

Yo personalmente lo pronuncio como
L<pouah|https://en.wiktionary.org/wiki/pouah>, que es una onomatopeya
francesa que usamos en lugar de puaj :) Puede que tenga un extraño sentido
del humor :)

=head2 ¿Por qué están obsoletos los scripts individuales?

De hecho, B<po4a-updatepo> y B<po4a-translate> quedan obsoletos en favor de
B<po4a>. La razón es que, aunque B<po4a> puede utilizarse como sustituto de
estos scripts, hay mucha duplicación de código. Los scripts individuales
tienen alrededor de 150 líneas de código mientras que el programa B<po4a>
tiene 1200 líneas, por lo que hacen mucho además de las funciones internas
comunes. La duplicación de código resulta en errores que ocurren en ambas
versiones y necesitan dos correcciones. Un ejemplo de tal duplicación son
los errores #1022216 en Debian y el problema #442 en GitHub que tenían
exactamente la misma solución, pero uno en B<po4a> y el otro
B<po4a-updatepo>.

A largo plazo, me gustaría abandonar los scripts individuales y mantener
sólo una versión de este código. Lo seguro es que los scripts individuales
no se mejorarán más, por lo que sólo B<po4a> obtendrá las nuevas
características. Dicho esto, no hay urgencia de desaprobación. Planeo
mantener los scripts individuales tanto como sea posible, y al menos hasta
2030. Si tu proyecto todavía utiliza B<po4a-updatepo> y B<po4a-translate> en
2030, puede que tengas un problema.

También es posible que en algún momento eliminemos la desaprobación de estos
scripts, si una refactorización reduce a cero la duplicación de código. Si
tienes una idea (o mejor: un parche), tu ayuda será bienvenida.

=head2 ¿Qué hay de las otras herramientas de traducción de documentación que usan
gettext?

Hay unas cuantas. Esta es una lista posiblemente incompleta, y más
herramientas se asoman por el horizonte.

=over

=item B<poxml>

Esta es la herramienta desarrollada por la gente de KDE para tratar DocBook
XML. Me parece que este fue el primer programa que extrajo cadenas de texto
a traducir desde la documentación a ficheros PO, e inyectarlas de vuelta
después de la traducción.

Únicamente puede tratar XML, y solo un DTD en particular. Estoy bastante
insatisfecho con el tratamiento que hacen de las listas, que terminan en un
único msgid. Cuando la lista crece, el bloque se hace difícil de tratar.

=item B<po-debiandoc>

Este programa hecho por Denis Barbier es un tipo de precursor del módulo
SGML de po4a, que más o menos lo deja obsoleto. Como su nombre indica,
únicamente trata el DTD de DebianDoc, que es más o menos un DTD anticuado.

=item B<xml2po.py>

Utilizado por el Equipo de Documentación de GIMP desde 2004, funciona
bastante bien aunque, como su nombre indica, sólo con archivos XML y
necesita makefiles especialmente configurados.

=item B<Sphinx>

El Proyecto de Documentación Sphinx también utiliza gettext extensivamente
para gestionar sus traducciones. Por desgracia, sólo funciona para unos
pocos formatos de texto, rest y markdown, aunque quizá sea la única
herramienta que lo hace gestionando todo el proceso de traducción.

=back

Las principales ventajas de po4a sobre ellos son la facilidad de adición de
contenidos extra (que es aún peor ahí) y la habilidad de realizar la
gettextización.

=head2 RESUMEN de las ventajas de la metodología basada en gettext

=over 2

=item

Las traducciones no se guardan junto con el original, lo que hace posible la
detección de traducciones anticuadas.

=item

Las traducciones se guardan en ficheros separados unos de otros, lo que
impide que traductores de diferentes idiomas interfieran en su trabajo tanto
al enviar parches, como a nivel de codificación de ficheros.

=item

Está basado internamente en B<gettext> (pero B<po4a> ofrece una interfaz muy
simple de forma que no necesita entender el funcionamiento interno para
usarlo). De esa forma no tenemos que reinventar la rueda, y debido a su uso
extendido podemos imaginar que estas herramientas están más o menos libres
de fallos.

=item

Para el usuario final nada ha cambiado (aparte de que, probablemente, las
traducciones estarían mejor actualizadas :). El fichero de documentación
resultante es exactamente el mismo.

=item

No hace falta que los traductores aprendan una nueva sintaxis de fichero, y
sus editores favoritos de ficheros PO (como el modo PO de Emacs, Lokalize o
Gtranslator) servirán a la perfección.

=item

gettext ofrece una manera simple de conseguir estadísticas sobre qué está
hecho, qué se debería repasar y actualizar, y lo que queda por hacer. Puede
encontrar algunos ejemplos en estas direcciones:

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

=back

Pero no todo es bonito, y este enfoque también tiene algunas desventajas con
las que debemos lidiar.

=over 2

=item

Los apéndices son algo extraños a primera vista.

=item

No puede adaptar el texto traducido a su gusto, como dividir párrafos por
aquí, y juntar esos dos allí. Pero por supuesto, si hay algún problema con
el original debería remitir un informe de fallo.

=item

Incluso con una interfaz fácil, sigue siendo una nueva herramienta que la
gente debe aprender.

Uno de mis sueños es integrar de alguna forma po4a con Gtranslator o
Lokalize. Cuando se abra un fichero, se extraen las cadenas automáticamente,
y se puede escribir en el disco un fichero traducido y un fichero PO. Si
consiguiéramos hacer un módulo para MS Word (TM) (o al menos RTF) incluso
podrían usarlo traductores profesionales.

=back

=head1 VÉASE TAMBIÉN

=over

=item

La documentación de la herramienta todo en uno que debes utilizar:
L<po4a(1)>.

=item

La documentación del script individual po4a: L<po4a-gettextize(1)>,
L<po4a-updatepo(1)>, L<po4a-translate(1)>, L<po4a-normalize(1)>.

=item

Los scripts de ayuda adicionales: L<msguntypot(1)>, L<po4a-display-man(1)>,
L<po4a-display-pod(1)>.

=item

The parsers of each formats, in particular to see the options accepted by
each of them: L<Locale::Po4a::AsciiDoc(3pm)> L<Locale::Po4a::Dia(3pm)>,
L<Locale::Po4a::Gemtext(3pm)>, L<Locale::Po4a::Guide(3pm)>,
L<Locale::Po4a::Ini(3pm)>, L<Locale::Po4a::KernelHelp(3pm)>,
L<Locale::Po4a::Man(3pm)>, L<Locale::Po4a::RubyDoc(3pm)>,
L<Locale::Po4a::Texinfo(3pm)>, L<Locale::Po4a::Text(3pm)>,
L<Locale::Po4a::Xhtml(3pm)>, L<Locale::Po4a::Yaml(3pm)>,
L<Locale::Po4a::BibTeX(3pm)>, L<Locale::Po4a::Docbook(3pm)>,
L<Locale::Po4a::Halibut(3pm)>, L<Locale::Po4a::LaTeX(3pm)>,
L<Locale::Po4a::Org(3pm)>, L<Locale::Po4a::Pod(3pm)>,
L<Locale::Po4a::SimplePod(3pm)>, L<Locale::Po4a::Sgml(3pm)>,
L<Locale::Po4a::TeX(3pm)>, L<Locale::Po4a::VimHelp>,
L<Locale::Po4a::Wml(3pm)>, L<Locale::Po4a::Xml(3pm)>.

=item

La implementación de la infraestructura central:
L<Locale::Po4a::TransTractor(3pm)> (particularmente importante para entender
la organización del código), L<Locale::Po4a::Chooser(3pm)>,
L<Locale::Po4a::Po(3pm)>, L<Locale::Po4a::Common(3pm)>. Consulte también el
archivo F<CONTRIBUTING.md> en el código fuente.

=back

=head1 AUTORES

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

=head1 TRADUCCION

 Jordi Vilalta <jvprat@gmail.com>
 Omar Campagne <ocampagne@gmail.com>

