PO4A.7(1) User Contributed Perl Documentation PO4A.7(1) NOMBRE po4a - Un marco de trabajo para traducir documentacion y otro material Introduccion po4a (PO para todo) facilita el mantenimiento de traduccion de documentacion utilizando las clasicas herramientas gettext. La caracteristica de po4a principal es que desacopla la traduccion del contenido desde su estructura documental. Este documento sirve como una introduccion para el proyecto po4a con un enfoque en usuarios potenciales considerando si utiliza esta herramienta y en la curioso deseo de entender por que las cosas son de la manera que son. ?Por que po4a? La filosofia de Free Software , es hacer que la tecnologia esta disponible a cada uno. Pero la licencia no es la unica consideracion: el software libre no traducido es inutil para los hablantes no ingleses. Por lo tanto, aun hay tarea que hacer para crear software disponible para todos. Esta situacion es bien entendida por muchos proyectos y cada uno ahora esta convencido de la necesidad de traducir todo. Aun, las traducciones actuales representan un enorme esfuerzo de muchos individuales, heridos por pequenas dificultades tecnicas. Agradecidamente, el software libre se beneficia de un nivel decente de traduccion gracias al maravilloso conjunto de herramientas gettext. Este 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 ejecucion para mostrar los mensajes traducidos al usuario. En cuanto a la documentacion, sin embargo, la situacion sigue siendo un tanto decepcionante. Al principio, traducir documentacion puede parecer mas facil que traducir un programa, ya que parece que basta con copiar el archivo fuente de la documentacion y empezar a traducir el contenido. Sin embargo, cuando se modifica la documentacion original, hacer un seguimiento de las modificaciones se convierte rapidamente 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 traduccion. Los usuarios finales pueden ser enganados por documentacion que describe un comportamiento antiguo del programa. Ademas, no pueden interactuar directamente con los mantenedores porque no hablan ingles. Asimismo, el mantenedor no puede solucionar el problema porque no conoce todos los idiomas a los que se traduce su documentacion. Estas dificultades, a menudo causadas por herramientas deficientes, pueden minar la motivacion de los traductores voluntarios, lo que agrava aun mas el problema. La ambicion del proyecto po4a es facilitar el trabajo de los traductores de la documentacion. En particular, crea traducciones de documentacion 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 catalogos de traduccion PO. Los traductores pueden aprovechar las herramientas clasicas de gettext para controlar el trabajo a realizar, colaborar y organizarse como equipos. po4a inyecta entonces las traducciones directamente en la estructura de la documentacion para producir archivos fuente traducidos que pueden procesarse y distribuirse igual que los archivos en ingles. Cualquier parrafo que no se traduzca se deja en ingles en el documento resultante, asegurando que los usuarios finales nunca vean una traduccion obsoleta en la documentacion. Esto automatiza la mayor parte del trabajo de mantenimiento de la traduccion. Descubrir los parrafos que necesitan una actualizacion resulta muy facil, y el proceso se automatiza por completo cuando los elementos se reordenan sin mas modificaciones. La verificacion especifica tambien puede utilizarse para reducir la posibilidad de errores de formato que darian lugar a un documento roto. Por favor, lea tambien las Preguntas frecuentes, mas abajo en este documento, para una lista mas completa de las ventajas y desventajas de este enfoque al problema. Formatos compatibles Actualmente se han implementado satisfactoriamente algunos tipos de formato de texto: man (interprete maduro) El clasico formato de las paginas de manual, usado por muchos programas fuera de alli. La compatibilidad con po4a es bienvenida ya que el formato es algo dificil de usar, y no muy amistoso para los principiantes. El modulo Locale::Po4a::Man(3pm) ademas admite el formato mdoc, utilizado por las paginas man BSD (no son muy comunes en Linux). AsciiDoc (interprete maduro) Este formato es un formato de margen ligero entendido para facilitar la autoria de documentacion. Es utilizado por ejemplo para documentacion del sistema git. Esas paginas man son traducidas utilizando po4a. Vea Locale::Po4a::AsciiDoc para detalles. pod (interprete maduro) Este es el formato <> (Documentacion en linea de Perl). El lenguaje y sus mismas extensiones estan documentados utilizando este formato junto la suma de muchos guiones Perl existentes. Hace muy facil mantener la documentacion cerca del codigo al integrarlos en el mismo fichero. Facilita la vida del programador, pero por desgracia, no la del traductor, hasta que utilice po4a. Vea Locale::Po4a::Pod para detalles. sgml (interprete maduro) Aunque hoy en dia XML lo haya sustituido, este formato aun se usa para documentos mas 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 diff se vuelve inutil cuando se ha sangrado (<>) otra vez el texto original tras una actualizacion. Afortunadamente, po4a le puede ayudar tras ese proceso. Actualmente, solo son compatibles los DTD de DebianDoc y de DocBook, pero anadir compatibilidad con uno nuevo es realmente facil. Incluso es posible usar po4a con un DTD desconocido de SGML sin cambiar el codigo introduciendo la informacion necesaria en la linea de ordenes. Consulte Locale::Po4a::Sgml(3pm) para mas detalles. TeX / LaTeX (interprete maduro) El formato LaTeX es un formato de documentacion usado principalmente en el mundo del Software Libre y para publicaciones. Se probo el modulo Locale::Po4a::LaTeX(3pm) con la documentacion de Python, un libro y algunas presentaciones. texto (interprete maduro) El formato Texto es el formato base para muchos formatos que incluyen bloques grandes de texto, incluyendo Markdown, fortunes, seccion matter de frente YAML, debian/changelog, y debian/control. Esto admite el formato comun utilizado en Generadores de Sitio Estatico, README, y otros sistemas de documentacion. Vea Locale::Po4a::Text(3pm) para detalles. xml y XHML (interprete probablemente maduro) El formato XML sirve de base para muchos formatos de documentacion. Actualmente, el formato DTD de DocBook (vea L>Locale::Po4a::DocBook(3pm)> para detalles) y XHTML estan admitidos por po4a. BibTex (interprete probablemente maduro) El formato BibTex es utilizado a lo largo de LaTeX para listados de formato de referencias (bibliograficos). Vea Locale::Po4a::BibTex para detalles. Docbook (interprete probablemente maduro) Un lenguaje anadido basado en XML que utiliza etiquetados semanticos para describir documentos. Vea Locale::Po4a:Docbook para detalles mayores. Guide XML (interprete probablemente maduro) Un formato de documentacion XML. Este modulo fue desarrollado especificamente para ayudar con apoyo y mantenimiento de traducciones de documentacion de Linux Gentoo hasta al menos en marzo de 2016 (basado en la Maquina Wayback). Gentoo desde entonces se ha migrado al formato XML DevBook. Vea Locale::Po4a:Guide para detalles mayores. Wml (probablemente interprete maduro) El XML (Web Markup Language), no mezcla WML con la materia WAP utilizada en celdas de telefonos. Este modulo depende del modulo XHTML, el mismo que dependo del modulo XML. Vease Locale::Po4a::Wml para mas detalles. Yaml (probablemente un analizador completo) Un superconjunto estricto de JSON. YAML se utiliza a menudo como sistemas o proyectos de configuracion. YAML esta en el nucleo de Ansible de Red Hat. Vea Locale::Po4a::Yaml para mas detalles. RubyDoc (probablemente analizador estable) El formato Ruby Document (RD), originalmente el formato de documentacion por defecto para Ruby y los proyectos Ruby antes de convertirse a RDoc en 2002. Aunque aparentemente la version japonesa del Manual de Referencia de Ruby todavia usa RD. Vease Locale::Po4a::RubyDoc para mas detalles. Halibut (analizador sintactico probablemente experimental) Un sistema de produccion de documentacion, con elementos similares a TeX, debiandoc-sgml, TeXinfo, y otros, desarrollados por Simon Tatham, el desarrollador de PuTTY. Vea Locale::Po4a:Halibut para detalles mayores. Ini (probablemente interprete experimental) Formado del archivo de configuracion popularizado por MS-DOS. Vea Locale::Po4a::Ini para detalles mas grandes. texinfo (interprete altamente experimental) Toda la documentacion de GNU esta escrita en este formato (es incluso un requisito para ser un proyecto oficial de GNU). La compatibilidad de Locale::Po4a::Texinfo(3pm) en po4a esta en sus inicios. Por favor, remita informes de fallo y peticiones de funcionalidades. gemtext (analizador sintactico muy experimental) El formato nativo de texto plano del protocolo Gemini. Se usa habitualmente la extension ".gmi". El soporte para este modulo en po4a aun esta en panales. Si encuentra algo, por favor envie un error o una peticion de funcionalidad. Otros formatos admitidos Po4a tambien puede tratar algunos formatos raros o especificos, tales como la documentacion de las opciones de compilacion de nucleos 2.4+ (Locale::Po4a::KernelHelp) o los diagramas producidos por la herramienta (Locale::Po4a:Dia). Anadir un formato nuevo es a menudo una tarea muy sencilla, y la tarea principal es conseguir un interprete para el formato escogido. Consulte Locale::Po4a::TransTractor(3pm) para mas informacion. Formatos no compatibles Desafortunadamente, po4a aun le falta compatibilidad para formatos de documentacion. Muchos de ellos serian sencillos de mantener en po4a. Esto incluye formatos no tan solo utilizados para documentacion, como descripciones de paquetes (deb y rpm), guiones de instalacion 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. Como utilizar po4a La forma mas sencilla de utilizar esta herramienta en su proyecto es escribir un fichero de configuracion para el programa po4a, e interactuar unicamente con este programa. Consulte su documentacion, en po4a(1). El resto de esta seccion proporciona mas detalles para los usuarios avanzados de po4a que quieran profundizar en su comprension. Esquema detallado del flujo de trabajo po4a Asegurese de leer po4a(1) antes de esta seccion excesivamente detallada para obtener una vision simplificada del flujo de trabajo de po4a. Vuelva aqui cuando quiera obtener la imagen completa que asusta, con casi todos los detalles. En el siguiente esquema, master.doc es un nombre de ejemplo para la documentacion a traducir; XX.doc es el mismo documento traducido al idioma XX mientras que doc.XX.po es el catalogo de traduccion para ese documento en el idioma XX. Los autores de la documentacion se ocuparan principalmente de master.doc (que puede ser una pagina de manual, un documento XML, un fichero AsciidDoc, etc); los traductores se ocuparan principalmente del fichero PO, mientras que los usuarios finales solo veran el fichero XX.doc. Las transiciones con corchetes como "[po4a updates po]" representan la ejecucion de una herramienta po4a mientras que las transiciones con corchetes como "{update of master.doc}" representan una modificacion 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 adendos 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 po4a(1) para obtener una vision simplificada. La parte izquierda muestra como se puede usar po4a-gettextize(1) para convertir un proyecto de traduccion existente a la infraestructura po4a. Este script toma un documento original y su contrapartida traducida, e intenta construir el archivo PO correspondiente. Esta conversion manual es bastante engorrosa (consulte la documentacion de po4a-gettextize(1) para mas detalles), pero solo es necesaria una vez para convertir sus traducciones existentes. Si no tiene ninguna traduccion que convertir, puede olvidarse de esto y centrarse en la parte derecha del esquema. En la parte superior derecha se representa la accion del autor original, que actualiza la documentacion. La parte central derecha muestra la actualizacion automatica de los archivos de traduccion: se extrae el nuevo material y se compara con la traduccion existente. La traduccion anterior se utiliza para las partes que no han cambiado, mientras que las partes parcialmente modificadas se conectan a la traduccion anterior con un marcador "difuso" que indica que la traduccion debe actualizarse. El material nuevo o muy modificado se deja sin traducir. A continuacion, el bloque edicion manual representa la accion de los traductores, que modifican los ficheros PO para proporcionar traducciones a cada cadena y parrafo originales. Esto se puede hacer usando un editor especifico como el GNOME Translation Editor, Lokalize o poedit de KDE, o usando una plataforma de localizacion online como weblate o pootle. El resultado de la traduccion es un conjunto de ficheros PO, uno por idioma. Por favor, consulte la documentacion de gettext para mas detalles. La parte inferior de la figura muestra como po4a crea un documento fuente traducido a partir del documento original master.doc y el catalogo de traduccion doc.XX.po actualizado por los traductores. La estructura del documento se reutiliza, mientras que el contenido original se sustituye por su homologo traducido. Opcionalmente, se puede utilizar un apendice para anadir texto adicional a la traduccion. Suele utilizarse para anadir el nombre del traductor al documento final. Para mas detalles, vease mas abajo. Al invocarlo, po4a actualiza automaticamente tanto los archivos de traduccion como los archivos de documentacion traducidos. Iniciar un nuevo proyecto de traduccion Si empieza desde cero, solo tiene que escribir un fichero de configuracion para po4a, y listo. Se crearan las plantillas relevantes para los ficheros que falten, permitiendo a sus colaboradores traducir su proyecto a su idioma. Por favor, consulte po4a(1) para un tutorial de inicio rapido y para todos los detalles. Si tiene una traduccion existente, es decir, un fichero de documentacion que se tradujo manualmente, puede integrar su contenido en su flujo de trabajo po4a usando po4a-gettextize. Esta tarea es un poco engorrosa (como se describe en la pagina de manual de la herramienta), pero una vez que su proyecto se convierta al flujo de trabajo po4a, todo se actualizara automaticamente. Actualizacion de traducciones y documentos Una vez configurado, basta con invocar po4a para actualizar tanto los ficheros PO de traduccion como los documentos traducidos. Puede pasar "--no-translations" a po4a para no actualizar las traducciones (actualizando asi solo los ficheros PO) o "--no-update" para no actualizar los ficheros PO (actualizando asi solo las traducciones). Esto corresponde aproximadamente a los scripts individuales po4a-updatepo y po4a-translate que ahora estan obsoletos (vea "Por que estan obsoletos los scripts individuales" en las FAQ mas abajo). Al utilizar adenda para agregar texto adicional para traducciones Agregando texto nuevo para la traduccion es probablemente la unica cosa que es mas facil en la direccion larga cuando traduzca archivos manualmente :). Esto ocurre cuando desea anadir una seccion adicional para el documento traducido, no correspondiente a ningun contenido dentro del documento original. La utilizacion clasica de caso es dar reconocimientos al equipo de traduccion, y para indicar como informar problemas especificos de traduccion. Con po4a, tiene que especificar archivos anexos, que pueden verse conceptualmente como parches aplicados al documento localizado despues de procesarlo. Cada anexo debe proporcionarse como un archivo separado, cuyo formato es, sin embargo, muy diferente de los parches clasicos. La primera linea es una linea de encabezamiento, que define el punto de insercion del anexo (con una sintaxis desafortunadamente criptica -- ver mas abajo) mientras que el resto del archivo se anade textualmente en la posicion determinada. La linea de encabezado debe comenzar con la cadena PO4A-HEADER:, seguida de una lista de campos clave=valor separados por punto y coma. Por ejemplo, el siguiente encabezamiento declara un anexo que debe colocarse al final de la traduccion. PO4A-HEADER: mode=eof Las cosas se complican cuando desea anadir su contenido adicional en medio del documento. La siguiente cabecera declara un anexo que debe colocarse despues de la seccion XML que contiene la cadena "Acerca de este documento" en la traduccion. PO4A-HEADER: position=Acerca de este documento; mode=after; endboundary= En la practica, al intentar aplicar un anexo, po4a busca la primera linea que coincida con el argumento de "posicion" (puede ser una regexp). No olvide que po4a considera aqui el documento traducido. Esta documentacion esta en ingles, pero su linea probablemente deberia decir lo siguiente si pretende que su anexo se aplique a la traduccion francesa del documento. PO4A-HEADER: position=A propos de ce document; mode=after; endboundary= Una vez encontrada la "posicion" en el documento destino, po4a busca la siguiente linea despues de la "posicion" que coincida con el "endboundary" proporcionado. El anexo se anade justo despues de esa linea (porque proporcionamos un endboundary, es decir, un limite que termina la seccion actual). Se podria obtener exactamente el mismo efecto con la siguiente cabecera, que es equivalente: PO4A-HEADER: position=Acerca de este documento; mode=after; beginboundary=
A continuacion, el bloque edicion manual representa la accion de los traductores, que modifican los ficheros PO para proporcionar traducciones a cada cadena y parrafo originales. Esto puede hacerse usando un editor especifico como el GNOME Translation Editor, B o B para KDE, o usando una plataforma de localizacion online como weblate o pootle. El resultado de la traduccion es un conjunto de ficheros PO, uno por idioma. Consulte la documentacion de gettext para mas detalles. Tambien se puede asignar a la insercion mode el valor "before", con una semantica similar: si se combina "mode=before" con un "endboundary", el apendice se situara justo after del limite coincidente, es decir, la ultima linea limite potencial antes de la "position". Si se combina "mode=before" con "beginboundary", el apendice se situara justo before del limite coincidente, es decir, la ultima linea limite potencial antes de "position". Modo | Tipo limite | Limite usado | Punto de insercion relativo al limite ========|===============|========================|========================================= 'before'| 'endboundary' | ultimo antes de 'position' | Justo tras el limite seleccionado 'before'|'beginboundary'| ultimo antes de 'position' | Justo antes del limite seleccionado 'after' | 'endboundary' | primero tras 'position' | Justo tras el limite seleccionado 'after' |'beginboundary'| primero tras 'position' | Justo antes del limite seleccionado 'eof' | (ninguno) | n/a | Fin del archivo Consejos y trucos sobre los anexos o Recuerde que se trata de regexp. Por ejemplo, si quiere que coincida con el final de una seccion nroff que termina con la linea ".fi", no utilice ".fi" como endboundary, porque esto coincidira con "el[ fi]chero", que obviamente no es lo que espera. El endboundary correcto en este caso seria: "^\.fi$". o Los espacios en blanco SI son importantes en el contenido de "position" y los limites. Asi que las dos lineas siguientes son diferentes. La segunda solo se encontrara si hay suficientes espacios finales en el documento traducido. PO4A-HEADER: position=Acerca de este documento; mode=after; beginboundary=
PO4A-HEADER: position=Acerca de este documento; mode=after; beginboundary=
o Aunque se puede considerar que esta busqueda de contexto funciona basicamente en cada linea del documento 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 parrafo de varias lineas, o una etiqueta XML individual. El punto de insercion preciso del apendice se debe encontrar antes o despues de la cadena de datos interna, y no puede encontrarse dentro de la cadena de datos interna. o Pase el argumento "-vv" a po4a para entender como se anaden las adendas a la traduccion. Tambien puede ayudar ejecutar po4a en modo depuracion para ver la cadena de datos interna real cuando no se aplica su adenda. Ejemplos de anexos o Si desea anadir algo despues de la siguiente seccion de nroff: .SH "AUTORES" Debe seleccionar un enfoque de dos pasos estableciendo mode=after. A continuacion, debe limitar la busqueda a la linea posterior a AUTHORS con el argumento regex position. A continuacion, debe hacer coincidir el comienzo de la siguiente seccion (es decir, ^\.SH) con el argumento regex beginboundary. Es decir: PO4A-HEADER:mode=after;position=AUTORES;beginboundary=\.SH o Si desea anadir algo justo despues de una linea concreta (por ejemplo despues de <>) utilice un "position" que encaje con esta linea, mode=after e introduzca un beginboundary que encaje con cualquier linea. PO4A-HEADER:mode=after;position=Copyright Big Dude, 2004;beginboundary=^ o Si desea anadir algo al final del documento, especifique un position que encaje con cualquier linea del documento (pero solo una linea. po4a no procedera si no es unica), y ponga un endboundary que no encaje con nada. No utilice cadenas simples como "EOF", sino las que tengan menos probabilidad de salir en el documento. PO4A-HEADER:mode=after;position=Acerca de este documento;beginboundary=FakePo4aBoundary Ejemplo mas detallado Documento original (en formato POD): |=head1 NOMBRE | |relleno - un programa de relleno | |=head1 AUTOR | |yo Luego, el siguiente apendice asegurara que se anade una seccion (en espanol) sobre el traductor al final del fichero. |PO4A-HEADER:mode=after;position=AUTOR;beginboundary=^=head | |=head1 TRADUCTOR | |yo | Para poner su anexo antes del AUTOR, utilice la siguiente cabecera: PO4A-HEADER:mode=after;position=NOMBRE;beginboundary=^=head1 Esto funciona porque la siguiente linea que coincide con la beginboundary "/^=head1/" despues de la seccion "NAME" (traducido a "NOM" en frances), es la que declara los autores. Asi pues, el addendum se colocara entre ambas secciones. Tenga en cuenta que si mas tarde se anade otra seccion entre las secciones NOMBRE y AUTOR, po4a pondra erroneamente la adenda antes de la nueva seccion. Para evitarlo, puede lograr el mismo efecto utilizando mode=before: PO4A-HEADER:mode=before;position=^=head1 AUTHOR ?Como funciona? Este capitulo le da una breve vision general del funcionamiento interno de po4a, para que se sienta mas seguro a la hora de ayudarnos a mantenerlo y mejorarlo. Tambien puede ayudarle a entender por que no hace lo que esperaba, y como resolver sus problemas. TransTractors y arquitectura de proyectos En el nucleo del proyecto po4a, la clase Locale::Po4a::TransTractor(3pm) es el ancestro comun de todos los analizadores sintacticos de po4a. Este extrano nombre proviene del hecho de que se encarga al mismo tiempo de traducir el documento y de extraer las cadenas. Mas formalmente, toma un documento para traducir mas un fichero PO que contiene las traducciones para utilizarlo como entrada, al tiempo que produce dos salidas separadas: Otro fichero PO (resultante de la extraccion 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 aqui una representacion grafica de esto: Documento de entrada --\ /---> Documento de salida \ TransTractor:: / (traducido) +-->-- parse() --------+ / \ PO de entrada --------/ \---> PO de salida (extraido) Este pequeno hueso es el nucleo de toda la arquitectura po4a. Si proporciona ambos PO de entrada y no tiene en cuenta el PO de salida, obtiene po4a-translate. Si no tiene en cuenta el documento de salida, obtiene po4a-updatepo. po4a utiliza un primer TransTractor para obtener un fichero POT de salida actualizado (sin tener en cuenta los documentos de salida), llama a msgmerge -U para actualizar los ficheros PO de traduccion en disco, y construye un segundo TransTractor con estos ficheros PO actualizados para actualizar los documentos de salida. En resumen, po4a proporciona una solucion unica para actualizar lo que sea necesario, utilizando un unico archivo de configuracion. po4a-gettextize tambien 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 po4a-gettextize(1). Analizadores sintacticos de formatos especificos Todos los analizadores de formato po4a se implementan sobre el TransTractor. Algunos son muy simples, como los de Text, Markdown y AsciiDoc. Cargan las lineas una a una usando TransTractor::shiftline(), acumulan el contenido de los parrafos o lo que sea. Una vez que una cadena esta completamente analizada, el analizador usa TransTractor::translate() para (1) anadir esta cadena al fichero PO de salida y (2) obtener la traduccion del fichero PO de entrada. El parseador entonces empuja el resultado al fichero de salida usando TransTractor::pushline(). Algunos otros analizadores sintacticos son mas complejos porque dependen de un analizador sintactico externo para analizar el documento de entrada. Los analizadores sintacticos Xml, HTML, SGML y Pod estan construidos sobre analizadores sintacticos SAX. Declaran retrollamadas a eventos como "He encontrado un nuevo titulo cuyo contenido es el siguiente" para actualizar el documento de salida y los archivos POT de salida segun el contenido de entrada utilizando TransTractor::translate() y TransTractor::pushline(). El analizador Yaml es similar pero diferente: serializa una estructura de datos producida por el analizador YAML::Tiny. Esta es la razon por la que el modulo Yaml de po4a no declara las lineas de referencia: la localizacion de cada cadena en el fichero de entrada no la guarda el analizador, por lo que solo podemos proporcionar "$nombredefichero:1" como localizacion de la cadena. Los analizadores sintacticos orientados a SAX usan globales y otros trucos para guardar el nombre del fichero y los numeros de linea de las referencias. Un problema especifico surge de las codificaciones de archivos y los marcadores BOM. Los analizadores sintacticos simples pueden olvidarse de este problema, que es manejado por TransTractor::read() (usado internamente para obtener las lineas de un documento de entrada), pero los modulos que dependen de un analizador sintactico externo deben asegurarse de que todos los ficheros se leen con una capa de decodificacion PerlIO apropiada. Lo mas facil es abrir el fichero tu mismo, y proporcionar un filehandle o directamente la cadena completa a tu parser externo. Mira en Pod::read() y Pod::parse() para ver un ejemplo. El contenido leido por el TransTractor se ignora, pero se pasa un nuevo filehandle al analizador externo. La parte importante es el modo "<:encoding($charset)" que se pasa a la funcion perl open(). Objetos Po La clase Locale::Po4a::Po(3pm) se encarga de cargar y usar ficheros PO y POT. Basicamente, puede leer un fichero, anadir entradas, obtener traducciones con el metodo gettext(), escribir el PO en un fichero. Funciones mas avanzadas como fusionar un fichero PO con un fichero POT o validar un fichero se delegan en msgmerge y msgfmt respectivamente. Contribuir a po4a Incluso si nunca ha contribuido a ningun proyecto de codigo abierto en el pasado, es bienvenido: estamos dispuestos a ayudarle y guiarle. po4a es mejor mantenido por sus usuarios hoy en dia. Como nos falta mano de obra, intentamos hacer el proyecto acogedor mejorando la documentacion y las pruebas automaticas para que tenga confianza en contribuir al proyecto. Por favor, consulte el archivo CONTRIBUTING.md para mas detalles. Proyectos de codigo abierto que utilizan po4a Aqui hay una lista muy parcial de proyectos que usan po4a en produccion para su documentacion. Si desea anadir su proyecto a la lista, envienos un correo electronico (o una Merge Request). o adduser (man): herramienta de gestion de usuarios y grupos. o apt (man, docbook): Gestor de paquetes Debian. o aptitude (docbook, svg): gestor de paquetes basado en la terminal para Debian o F-Droid website (markdown): catalogo instalable de aplicaciones FOSS (Software libre y de codigo abierto) para la plataforma Android. o git (asciidoc): sistema distribuido de control de versiones para el seguimiento de cambios en el codigo fuente. o Linux manpages (man) Este proyecto proporciona una infraestructura para traducir muchas paginas de manual a diferentes idiomas, listas para su integracion en varias de las principales distribuciones (Arch Linux, Debian y derivados, Fedora). o Stellarium (HTML): un planetario libre de codigo abierto para su ordenador. po4a se utiliza para traducir las descripciones de la cultura celeste. o Jamulus (markdown, yaml, HTML): una aplicacion FOSS para interferir en linea en tiempo real. La documentacion del sitio web se mantiene en varios idiomas utilizando po4a. o Otro tema a solucionar: Preguntas frecuentes ?Como se pronuncia po4a? Yo personalmente lo pronuncio como pouah , que es una onomatopeya francesa que usamos en lugar de puaj :) Puede que tenga un extrano sentido del humor :) ?Por que estan obsoletos los scripts individuales? De hecho, po4a-updatepo y po4a-translate quedan obsoletos en favor de po4a. La razon es que, aunque po4a puede utilizarse como sustituto de estos scripts, hay mucha duplicacion de codigo. Los scripts individuales tienen alrededor de 150 lineas de codigo mientras que el programa po4a tiene 1200 lineas, por lo que hacen mucho ademas de las funciones internas comunes. La duplicacion de codigo resulta en errores que ocurren en ambas versiones y necesitan dos correcciones. Un ejemplo de tal duplicacion son los errores #1022216 en Debian y el problema #442 en GitHub que tenian exactamente la misma solucion, pero uno en po4a y el otro po4a-updatepo. A largo plazo, me gustaria abandonar los scripts individuales y mantener solo una version de este codigo. Lo seguro es que los scripts individuales no se mejoraran mas, por lo que solo po4a obtendra las nuevas caracteristicas. Dicho esto, no hay urgencia de desaprobacion. Planeo mantener los scripts individuales tanto como sea posible, y al menos hasta 2030. Si tu proyecto todavia utiliza po4a-updatepo y po4a-translate en 2030, puede que tengas un problema. Tambien es posible que en algun momento eliminemos la desaprobacion de estos scripts, si una refactorizacion reduce a cero la duplicacion de codigo. Si tienes una idea (o mejor: un parche), tu ayuda sera bienvenida. ?Que hay de las otras herramientas de traduccion de documentacion que usan gettext? Hay unas cuantas. Esta es una lista posiblemente incompleta, y mas herramientas se asoman por el horizonte. 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 documentacion a ficheros PO, e inyectarlas de vuelta despues de la traduccion. Unicamente puede tratar XML, y solo un DTD en particular. Estoy bastante insatisfecho con el tratamiento que hacen de las listas, que terminan en un unico msgid. Cuando la lista crece, el bloque se hace dificil de tratar. po-debiandoc Este programa hecho por Denis Barbier es un tipo de precursor del modulo SGML de po4a, que mas o menos lo deja obsoleto. Como su nombre indica, unicamente trata el DTD de DebianDoc, que es mas o menos un DTD anticuado. xml2po.py Utilizado por el Equipo de Documentacion de GIMP desde 2004, funciona bastante bien aunque, como su nombre indica, solo con archivos XML y necesita makefiles especialmente configurados. Sphinx El Proyecto de Documentacion Sphinx tambien utiliza gettext extensivamente para gestionar sus traducciones. Por desgracia, solo funciona para unos pocos formatos de texto, rest y markdown, aunque quiza sea la unica herramienta que lo hace gestionando todo el proceso de traduccion. Las principales ventajas de po4a sobre ellos son la facilidad de adicion de contenidos extra (que es aun peor ahi) y la habilidad de realizar la gettextizacion. RESUMEN de las ventajas de la metodologia basada en gettext o Las traducciones no se guardan junto con el original, lo que hace posible la deteccion de traducciones anticuadas. o 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 codificacion de ficheros. o Esta basado internamente en gettext (pero 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 estan mas o menos libres de fallos. o Para el usuario final nada ha cambiado (aparte de que, probablemente, las traducciones estarian mejor actualizadas :). El fichero de documentacion resultante es exactamente el mismo. o 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) serviran a la perfeccion. o gettext ofrece una manera simple de conseguir estadisticas sobre que esta hecho, que se deberia 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/ Pero no todo es bonito, y este enfoque tambien tiene algunas desventajas con las que debemos lidiar. o Los apendices son algo extranos a primera vista. o No puede adaptar el texto traducido a su gusto, como dividir parrafos por aqui, y juntar esos dos alli. Pero por supuesto, si hay algun problema con el original deberia remitir un informe de fallo. o Incluso con una interfaz facil, sigue siendo una nueva herramienta que la gente debe aprender. Uno de mis suenos es integrar de alguna forma po4a con Gtranslator o Lokalize. Cuando se abra un fichero, se extraen las cadenas automaticamente, y se puede escribir en el disco un fichero traducido y un fichero PO. Si consiguieramos hacer un modulo para MS Word (TM) (o al menos RTF) incluso podrian usarlo traductores profesionales. VEASE TAMBIEN o La documentacion de la herramienta todo en uno que debes utilizar: po4a(1). o La documentacion del script individual po4a: po4a-gettextize(1), po4a-updatepo(1), po4a-translate(1), po4a-normalize(1). o Los scripts de ayuda adicionales: msguntypot(1), po4a-display-man(1), po4a-display-pod(1). o Loa analizadores de cada formato, en particular para ver las opciones aceptadas por cada uno de ellos: Locale::Po4a::AsciiDoc(3pm) Locale::Po4a::Dia(3pm), Locale::Po4a::Guide(3pm), Locale::Po4a::Ini(3pm), Locale::Po4a::KernelHelp(3pm), Locale::Po4a::Man(3pm), Locale::Po4a::RubyDoc(3pm), Locale::Po4a::Texinfo(3pm), Locale::Po4a::Text(3pm), Locale::Po4a::Xhtml(3pm), Locale::Po4a::Yaml(3pm), Locale::Po4a::BibTeX(3pm), Locale::Po4a::Docbook(3pm), Locale::Po4a::Halibut(3pm), Locale::Po4a::LaTeX(3pm), Locale::Po4a::Pod(3pm), Locale::Po4a::Sgml(3pm), Locale::Po4a::TeX(3pm), Locale::Po4a::Wml(3pm), Locale::Po4a::Xml(3pm). o La implementacion de la infraestructura central: Locale::Po4a::TransTractor(3pm) (particularmente importante para entender la organizacion del codigo), Locale::Po4a::Chooser(3pm), Locale::Po4a::Po(3pm), Locale::Po4a::Common(3pm). Consulte tambien el archivo CONTRIBUTING.md en el codigo fuente. AUTORES Denis Barbier Martin Quinson (mquinson#debian.org) TRADUCCION Jordi Vilalta Omar Campagne POD ERRORS Hey! The above document had some coding errors, which are explained below: Around line 263: Unknown E content in E perl v5.38.2 2024-06-26 PO4A.7(1)