PO4A

Section: Ferramentas do Po4a (7)
Updated: 2024-01-29
Index Return to Main Contents
 

NOME

po4a - framework para traduzir documentação e outros materiais  

Introdução

po4a (PO for anything) facilita a manutenção da tradução de documentação usando as ferramentas gettext clássicas. A principal característica do po4a é que ele dissocia a tradução do conteúdo de sua estrutura documental.

Este documento serve como uma introdução ao projeto po4a, com foco nos usuários em potencial, considerando a possibilidade de usar essa ferramenta e no desejo curioso de entender por que as coisas são do jeito que são.  

Por que o po4a?

A filosofia do software livre é tornar a tecnologia verdadeiramente disponível para todos. Mas o licenciamento não é a única consideração: o software livre não traduzido é inútil para quem não fala inglês. Portanto, ainda temos algum trabalho a fazer para disponibilizar o software para todos.

Essa situação é bem compreendida pela maioria dos projetos e agora todos estão convencidos da necessidade de traduzir tudo. No entanto, as traduções reais representam um enorme esforço de muitas pessoas, prejudicadas por pequenas dificuldades técnicas.

Felizmente, o software de código aberto é realmente muito bem traduzido usando o conjunto de ferramentas gettext. Essas ferramentas são usadas para extrair as strings a serem traduzidas de um programa e apresentar as strings em um formato padronizado (chamado de arquivos PO ou catálogos de tradução). Um ecossistema inteiro de ferramentas surgiu para ajudar os tradutores a traduzir esses arquivos PO. O resultado é usado pelo gettext no tempo de execução para exibir mensagens traduzidas para os usuários finais.

Regarding documentation, however, the situation still somewhat disappointing. At first translating documentation may seem to be easier than translating a program as it would seem that you just have to copy the documentation source file and start translating the content. However, when the original documentation is modified, keeping track of the modifications quickly turns into a nightmare for the translators. If done manually, this task is unpleasant and error-prone.

Traduções desatualizadas geralmente são piores do que nenhuma tradução. Os usuários finais podem ser enganados pela documentação que descreve um comportamento antigo do programa. Além disso, eles não podem interagir diretamente com os mantenedores, pois não falam inglês. Além disso, o mantenedor não pode resolver o problema, pois não conhece todos os idiomas em que sua documentação está traduzida. Essas dificuldades, muitas vezes causadas por ferramentas precárias, podem minar a motivação de tradutores voluntários, agravando ainda mais o problema.

O objetivo do projeto po4a é facilitar o trabalho dos tradutores de documentação. Em particular, ele torna possível manter traduções de documentações.

A ideia é reutilizar e adaptar a abordagem gettext a esse campo. Assim como o gettext, os textos são extraídos de seus locais originais e apresentados aos tradutores como catálogos de tradução de pedidos. Os tradutores podem aproveitar as ferramentas gettext clássicas para monitorar o trabalho a realizar, colaborar e organizar em equipe. O po4a injeta as traduções diretamente na estrutura da documentação para produzir arquivos de origem traduzidos que podem ser processados e distribuídos da mesma forma que os arquivos em inglês. Qualquer parágrafo que não seja traduzido é deixado em inglês no documento resultante, garantindo que os usuários finais nunca vejam uma tradução desatualizada na documentação.

Isso automatiza a maior parte do trabalho pesado da manutenção da tradução. A descoberta dos parágrafos que precisam de atualização se torna muito fácil e o processo é completamente automatizado quando os elementos são reordenados sem modificações adicionais. A verificação específica também pode ser usada para reduzir a chance de erros de formatação que resultariam em um documento quebrado.

Por favor, veja também o FAQ abaixo neste documento para uma lista mais completa de vantagens e desvantagens desta abordagem.  

Formatos suportados

Atualmente, essa abordagem tem sido implementada com sucesso em vários formatos de formatação de texto:
man (analisador maduro)
O bom e velho formato de páginas de manual, usado por muitos programas por aí. Suporte do po4a é muito bem-vindo, considerando que esse formato é de certa forma difícil de usar e não exatamente amigável para novatos.

O módulo Locale::Po4a::Man(3pm) também possui suporte ao formato mdoc usado pelas páginas man do BSD (elas também são bastante comuns no Linux).

AsciiDoc (analisador maduro)
Esse formato é um formato de marcação leve, destinado a facilitar a criação da documentação. Por exemplo, é usado para documentar o sistema git. Essas páginas man são traduzidas usando po4a.

Veja Locale::Po4a::AsciiDoc para detalhes.

pod (analisador maduro)
Esse é o formato da documentação online de Perl, ou Perl Online Documentation. A própria linguagem e extensões são documentadas usando este formato além da maioria dos scripts Perl existentes. Isso facilita a manter a documentação ferto do real código embutindo-os no mesmo arquivo. Isso torna a vida dos programadores mais fácil, mas infelizmente, não a do tradutor, até você usar o po4a.

Veja Locale::Po4a::Pod para detalhes.

sgml (analisador maduro)
Mesmo que substituído pelo XML hoje em dia, esse formato ainda é usado para documentos que têm mais de algumas telas. Pode até ser usado para livros completos. Documentos deste comprimento podem ser muito desafiadores para atualizar. diff muitas vezes revela inútil quando o texto original era recuado novamente após a atualização. Felizmente, po4a pode lhe ajudar depois desse processo.

Atualmente, há suporte apenas ao DebianDoc e o DocBook DTD, mas a adição de suporte a um novo é realmente fácil. É possível até mesmo usar po4a em um SGML DTD desconhecido sem alterar o código, desde que sejam fornecidas as informações necessárias na linha de comando. Veja Locale::Po4a::Sgml(3pm) para mais detalhes.

TeX / LaTeX (analisador maduro)
O formato LaTeX é um formato de documentação mais usado no mundo de software livre e para publicações.

O módulo Locale::Po4a::LaTeX(3pm) foi testado com a documentação do Python, um livro e algumas apresentações.

text (analisador maduro)
O formato Text é of formato base para muitos formatos que incluem longos blocos de texto, incluindo Markdown, fortunes, seção de página de rotos YAML, debian/changelog e debian/control.

Este possui suporte ao formato comum usado em geradores de sites estáticos, READMEs e outros sistemas de documentação. Consulte Locale::Po4a::Text(3pm) para detalhes.

xml e XHMTL (analisador provavelmente maduro)
O formato XML é um formato base para muitos formatos de documentação.

Atualmente, o DocBook DTD (veja Locale::Po4a::Docbook(3pm) para mais detalhes) e XHTML são suportados pelo po4a.

BibTex (analisador provavelmente maduro)
O formato BibTex é usado junto com o LaTex para formatar listas de referências (bibliografias).

Veja Locale::Po4a::BibTex para detalhes.

Docbook (analisador provavelmente maduro)
Uma linguagem de marcação baseada em XML que usa tags semânticas para descrever documentos.

Veja Locale::Po4a:Docbook para mais detalhes.

Guide XML (analisador provavelmente maduro)
Um formato de documentação XML. Este módulo foi desenvolvido especificamente para ajudar no suporte e manutenção de traduções da documentação do Gentoo Linux até pelo menos março de 2016 (baseado na máquina Wayback). Desde então, o Gentoo mudou para o formato DevBook XML.

Veja Locale::Po4a:Guide para mais detalhes.

Wml (analisador provavelmente maduro)
A Web Markup Language, não confunda WML com o material WAP usado em telefones celulares. Este módulo depende do módulo Xhtml, que por sua vez depende do módulo XmL.

Veja Locale::Po4a::Wml para mais detalhes.

Yaml (analisador provavelmente maduro)
Um superconjunto estrito de JSON. YAML é frequentemente usado como sistemas ou projetos de configuração. YAML está no cerne do Ansible da Red Hat.

Veja Locale::Po4a::Yaml para mais detalhes.

RubyDoc (analisador provavelmente maduro)
O formato Ruby Document (RD), originalmente o formato de documentação padrão para Ruby e projetos Ruby antes de ser convertido para RDoc em 2002. Embora aparentemente a versão japonesa do Manual de Referência Ruby ainda use RD.

Veja Locale::Po4a::RubyDoc para mais detalhes.

Halibut (analisador altamente experimental)
Um sistema de produção de documentação, com elementos semelhantes ao TeX, debiandoc-sgml, TeXinfo e outros, desenvolvido por Simon Tatham, o desenvolvedor do PuTTY.

Veja Locale::Po4a:Halibut para mais detalhes.

Ini (analisador altamente experimental)
Formato de arquivo de configuração popularizado pelo MS-DOS.

Veja Locale::Po4a::Ini para mais detalhes.

texinfo (analisador altamente experimental)
Toda a documentação do GNU é escrita neste formato (esse é até mesmo um dos requisitos para se tornar um projeto GNU oficial). O suporte a Locale::Po4a::Texinfo(3pm) no po4a ainda está nas fases iniciais. Por favor relate eventuais erros e requisição por recursos.
Outros formatos com suporte
Po4a também pode manipular alguns formatos mais raros ou especializados, como a documentação de opções de compilação dos kernels Linux 2.4+ (Locale::Po4a::KernelHelp) ou diagramas produzidos pela ferramenta Dia (Locale::Po4a:Dia). A adição de um novo formato é normalmente muito fácil e a tarefa principal é fazer um analisador para seu formato alvo. Veja Locale::Po4a::TransTractor(3pm) para mais informações sobre isso.
Formatos sem suporte
Infelizmente, po4a ainda carece de suporte para vários formatos de documentação. Muitos deles seriam fáceis de dar suporte no po4a. Isso inclui formatos não apenas usados para documentação, como, descrições de pacotes (deb e rpm), perguntas sobre scripts de instalação de pacotes, changelogs de pacotes e todos os formatos de arquivo especializados usados por programas como cenários de jogos ou arquivos de recursos de vinho.
 

Usando po4a

The easiest way to use this tool in your project is to write a configuration file for the po4a program, and only interact with this program. Please refer to its documentation, in po4a(1). The rest of this section provides more details for the advanced users of po4a wanting to deepen their understanding.  

Detailed schema of the po4a workflow

Make sure to read po4a(1) before this overly detailed section to get a simplified overview of the po4a workflow. Come back here when you want to get the full scary picture, with almost all details.

In the following schema, master.doc is an example name for the documentation to be translated; XX.doc is the same document translated in the language XX while doc.XX.po is the translation catalog for that document in the XX language. Documentation authors will mostly be concerned with master.doc (which can be a manpage, an XML document, an AsciidDoc file, etc); the translators will be mostly concerned with the PO file, while the end users will only see the XX.doc file.

Transitions with square brackets such as "[po4a updates po]" represent the execution of a po4a tool while transitions with curly brackets such as "{ update of master.doc }" represent a manual modification of the project's files.

                                   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)

Again, this schema is overly complicated. Check on po4a(1) for a simplified overview.

A parte esquerda mostra como po4a-gettextize(1) pode ser usado para converter um projeto de tradução existente para a infraestrutura do po4a. Este script pega um documento original e seu equivalente traduzido, e tenta construir o arquivo PO correspondente. Tal conversão manual é um pouco trabalhosa (veja a documentação po4a-gettextize(1) para mais detalhes), mas só é necessária uma vez para converter suas traduções existentes. Se você não tem nenhuma tradução para converter, você pode esquecer isso e focar na parte certa do esquema.

On the top right part, the action of the original author is depicted, updating the documentation. The middle right part depicts the automatic updates of translation files: the new material is extracted and compared against the exiting translation. The previous translation is used for the parts that didn't change, while partially modified parts are connected to the previous translation with a ``fuzzy'' marker indicating that the translation must be updated. New or heavily modified material is left untranslated.

Então, a edição manual relatada representa a ação dos tradutores, que modificam os arquivo PO para fornecer traduções para toda string e parágrafo originais. Isso pode ser feito usando um editor específico, como o Editor de Tradução do GNOME, o Lokalize do KDE ou poedit, ou usando uma plataforma de localização online como o weblate ou pootle. O resultado da tradução é um conjunto de arquivos PO, um por idioma. Consulte a documentação gettext para mais detalhes.

The bottom part of the figure shows how po4a creates a translated source document from the master.doc original document and the doc.XX.po translation catalog that was updated by the translators. The structure of the document is reused, while the original content is replaced by its translated counterpart. Optionally, an addendum can be used to add some extra text to the translation. This is often used to add the name of the translator to the final document. See below for details.

Upon invocation, po4a updates both the translation files and the translated documentation files automatically.  

Starting a new translation project

If you start from scratch, you just have to write a configuration file for po4a, and you are set. The relevant templates are created for the missing files, allowing your contributors to translate your project to their language. Please refer to po4a(1) for a quick start tutorial and for all details.

If you have an existing translation, i.e. a documentation file that was translated manually, you can integrate its content in your po4a workflow using po4a-gettextize. This task is a bit cumbersome (as described in the tool's manpage), but once your project is converted to po4a workflow, everything will be updated automatically.  

Updating the translations and documents

Once setup, invoking po4a is enough to update both the translation PO files and translated documents. You may pass the "--no-translations" to po4a to not update the translations (thus only updating the PO files) or "--no-update" to not update the PO files (thus only updating the translations). This roughly corresponds to the individual po4a-updatepo and po4a-translate scripts which are now deprecated (see ``Why are the individual scripts deprecated'' in the FAQ below).  

Usando adendos para adicionar texto extra às traduções

Adicionar novo texto à tradução é provavelmente a única coisa mais fácil a longo prazo quando você traduz arquivos manualmente :). Isso acontece quando você deseja adicionar uma seção extra ao documento traduzido, que não corresponde a nenhum conteúdo no documento original. O caso de uso clássico é dar créditos à equipe de tradução e indicar como relatar problemas específicos da tradução.

Com o po4a, é necessário especificar os arquivos addendum, que podem ser vistos conceitualmente como patches aplicados ao documento localizado após o processamento. Cada adendo deve ser fornecido como um arquivo separado, cujo formato é, no entanto, muito diferente dos patches clássicos. A primeira linha é uma linha de cabeçalho, definindo o ponto de inserção do adendo (com uma sintaxe infelizmente enigmática --- veja abaixo) enquanto o restante do arquivo é adicionado literalmente na posição determinada.

A linha do cabeçalho deve começar com a string PO4A-HEADER:, seguida por uma lista separada por ponto e vírgula dos campos chave=valor.

Por exemplo, o cabeçalho a seguir declara um adendo que deve ser colocado bem no final da tradução.

 PO4A-HEADER: mode=eof

As coisas ficam mais complexas quando você deseja adicionar seu conteúdo extra no meio do documento. O cabeçalho a seguir declara um adendo que deve ser colocado após a seção XML que contém a string "Sobre este documento" na tradução.

 PO4A-HEADER: position=Sobre este documento; mode=after; endboundary=</section>

Na prática, ao tentar aplicar um adendo, o po4a pesquisa a primeira linha correspondente ao argumento "position" (isso pode ser um regexp). Não esqueça que o po4a considera o documento translated aqui. Esta documentação está em inglês, mas sua linha provavelmente deve ser a seguinte, se você pretende que seu adendo se aplique à tradução em francês do documento.

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

Depois que a "position" é encontrada no documento de destino, o po4a procura a próxima linha após a "position" que corresponde ao "endboundary" fornecido. O adendo é adicionado à direita after essa linha (porque fornecemos um endboundary, ou seja, um limite que termina a seção atual).

O exato mesmo efeito pode ser obtido com o seguinte cabeçalho, que é equivalente:

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

Here, po4a searches for the first line matching "<section"> after the line matching "About this document" in the translation, and add the addendum before that line since we provided a beginboundary, i.e. a boundary marking the beginning of the next section. So this header line requires placing the addendum after the section containing "About this document", and instruct po4a that a section starts with a line containing the "<section"> tag. This is equivalent to the previous example because what you really want is to add this addendum either after "/section"> or before "<section">.

Você também pode definir a inserção modo como o valor "before", com uma semântica semelhante: a combinação de "mode=before" com um "endboundary" colocará o adendo apenas after o limite correspondente, que a última linha limite potencial antes da "position". Combinar "mode=before" com um "beginboundary" colocará o adendo apenas before do limite correspondente, que é a última linha limite potencial antes da "position".

  Modo   | Tipo de limite |       Limite usado         | Ponto de inserção am comparação ao limite
 ========|================|============================|==========================================
 'before'| 'endboundary'  | último antes de 'position' | Logo após o limite selecionado
 'before'|'beginboundary' | último antes de 'position' | Logo antes do limite selecionado
 'after' | 'endboundary'  |  primeiro após 'position'  | Logo após o limite selecionado
 'after' |'beginboundary' |  primeiro após 'position'  | Logo antes do limite selecionado
 'eof'   |   (none)       |  n/d                       | Fim do arquivo

Dicas e truques sobre adendos

Lembre-se de que estes são regexp. Por exemplo, se você deseja combinar o final de uma seção nroff que termina com a linha ".fi", não use ".fi" como endboundary porque ele vai corresponder a "the[ fi]le", o que obviamente não é o que está esperando. O endboundary correto neste caso é: "^\.fi$".
Espaços em branco SÃO importantes no conteúdo da "position" e limites. Portanto, as duas linhas seguintes são diferentes. O segundo só será encontrado se houver espaços à direita suficientes no documento traduzido.

 PO4A-HEADER: position=Sobre este documento; mode=after; beginboundary=<section>
 PO4A-HEADER: position=Sobre este documento; mode=after; beginboundary=<section>

Embora essa pesquisa de contexto possa ser considerada como operando aproximadamente em cada linha do documento traduzido, ela realmente opera na cadeia de dados interna do documento traduzido. Essa cadeia de dados interna pode ser um texto abrangendo um parágrafo contendo várias linhas ou pode ser uma tag XML sozinha. O exato ponto de inserção do adendo deve ser anterior ou posterior à sequência de dados interna e não pode estar dentro da cadeia de dados interna.
Passe o argumento -vv para po4a para entender como os adendos são adicionados à tradução. Também pode ajudar a executar po4a no modo de depuração para ver a string de dados interna real quando o seu adendo não se aplica.

Exemplos de adendos

Se você quiser adicionar alguma coisa após a seção nroff a seguir:

  .SH "AUTHORS"

You should select a two-step approach by setting mode=after. Then you should narrow down search to the line after AUTHORS with the position argument regex. Then, you should match the beginning of the next section (i.e., ^\.SH) with the beginboundary argument regex. That is to say:

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

Se você quiser adicionar alguma coisa após a linha dada (ex,. após a linha ``Copyright Grande Cara'') use um position correspondendo a esta linha, mode=after e forneça um beginboundary correspondendo a qualquer linha.

 PO4A-HEADER:mode=after;position=Copyright Grande Cara, 2004;beginboundary=^

Se você quiser adicionar alguma coisa ao final do documento, forneça um position correspondendo a qualquer linha do seu documento (mas apenas uma linha. Po4a não vai proceder se ela não for única), e forneça um endboundary correspondendo a nada. Não use strings simples aqui como ``EOF'', e sim prefira aquelas que possuem menos chance de estar no seu documento.

 PO4A-HEADER:mode=after;position=Sobre este documento;beginboundary=FakePo4aBoundary

Exemplo mais detalhado

Documento original (formatado em POD):

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

Então, o adendo a seguir vai assegurar que a seção (em Francês) sobre o tradutor seja adicionado ao final do arquivo (em Francês, ``TRADUCTEUR'' significa ``TRADUTOR'', e ``moi'' significa ``eu'').

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

Para colocar seu adendo antes do AUTHOR, use o seguinte cabeçalho:

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

Isso funciona porque a próxima linha correspondendo ao beginboundary /^=head1/ após a seção ``NAME'' (traduzido para ``NOM'' em Francês) é aquela declarando os autores. Então, o adendo será colocado entre as duas seções. Note que se outra seção for adicionada entre as seções NAME e AUTHOR posteriormente, po4a colocará o adendo equivocadamente antes da nova seção.

Para evitar isto, você pode realizar o mesmo usando mode=before:

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

 

Como ele funciona?

This chapter gives you a brief overview of the po4a internals, so that you may feel more confident to help us to maintain and to improve it. It may also help you to understand why it does not do what you expected, and how to solve your problems.  

TransTractors and project architecture

At the core of the po4a project, the Locale::Po4a::TransTractor(3pm) class is the common ancestor to all po4a parsers. This strange name comes from the fact that it is at the same time in charge of translating document and extracting strings.

More formally, it takes a document to translate plus a PO file containing the translations to use as input while producing two separate outputs: Another PO file (resulting of the extraction of translatable strings from the input document), and a translated document (with the same structure as the input one, but with all translatable strings replaced with content of the input PO). Here is a graphical representation of this:

   Doc. de entrada --\                             /---> Doc. de saída
                      \      TransTractor::       /       (traduzido)
                       +-->--   parse()  --------+
                      /                           \
   PO de entrada ----/                             \---> PO de saída
                                                           (extraído)

This little bone is the core of all the po4a architecture. If you provide both input and disregard the output PO, you get po4a-translate. If you disregard the output document instead, you get po4a-updatepo. The po4a uses a first TransTractor to get an up-to-date output POT file (disregarding the output documents), calls msgmerge -U to update the translation PO files on disk, and builds a second TransTractor with these updated PO files to update the output documents. In short, po4a provides one-stop solution to update what needs to be, using a single configuration file.

po4a-gettextize also uses two TransTractors, but another way: It builds one TransTractor per language, and then build a new PO file using the msgids of the original document as msgids, and the msgids of the translated document as msgstrs. Much care is needed to ensure that the strings matched this way actually match, as described in po4a-gettextize(1).  

Format-specific parsers

All po4a format parsers are implemented on top of the TransTractor. Some of them are very simple, such as the Text, Markdown and AsciiDoc ones. They load the lines one by one using "TransTractor::shiftline()", accumulate the paragraphs' content or whatever. Once a string is completely parsed, the parser uses "TransTractor::translate()" to (1) add this string to the output PO file and (2) get the translation from the input PO file. The parser then pushes the result to the output file using "TransTractor::pushline()".

Some other parsers are more complex because they rely on an external parser to analyze the input document. The Xml, HTML, SGML and Pod parsers are built on top of SAX parsers. They declare callbacks to events such as ``I found a new title which content is the following'' to update the output document and output POT files according to the input content using "TransTractor::translate()" and "TransTractor::pushline()". The Yaml parser is similar but different: it serializes a data structure produced by the YAML::Tiny parser. This is why the Yaml module of po4a fails to declare the reference lines: the location of each string in the input file is not kept by the parser, so we can only provide ``$filename:1'' as a string location. The SAX-oriented parsers use globals and other tricks to save the file name and line numbers of references.

One specific issues arises from file encodings and BOM markers. Simple parsers can forget about this issue, that is handled by "TransTractor::read()" (used internally to get the lines of an input document), but the modules relying on an external parser must ensure that all files are read with an appropriate PerlIO decoding layer. The easiest is to open the file yourself, and provide an filehandle or directly the full string to your external parser. Check on "Pod::read()" and "Pod::parse()" for an example. The content read by the TransTractor is ignored, but a fresh filehandle is passed to the external parser. The important part is the "<:encoding($charset)" mode that is passed to the open() perl function.  

Po objects

The Locale::Po4a::Po(3pm) class is in charge of loading and using PO and POT files. Basically, you can read a file, add entries, get translations with the gettext() method, write the PO into a file. More advanced features such as merging a PO file against a POT file or validating a file are delegated to msgmerge and msgfmt respectively.  

Contributing to po4a

Even if you have never contributed to any Open Source project in the past, you are welcome: we are willing to help and mentor you here. po4a is best maintained by its users nowadays. As we lack manpower, we try to make the project welcoming by improving the doc and the automatic tests to make you confident in contributing to the project. Please refer to the CONTRIBUTING.md file for more details.  

Projetos de código aberto que usam o po4a

Aqui está uma lista bem parcial de projetos que usam po4a na produção para sua documentação. Se você quiser adicionar seu projeto à lista, basta nos enviar um e-mail (ou uma merge request).
adduser (man): ferramenta de gerenciamento de usuários e grupos.
apt (man, docbook): Gerenciador de pacotes do Debian.
aptitude (docbook, svg): Gerenciador de pacotes em interface de texto para Debian
F-Droid website <https://gitlab.com/fdroid/fdroid-website> (markdown): installable catalog of FOSS (Free and Open Source Software) applications for the Android platform.
git <https://github.com/jnavila/git-manpages-l10n> (asciidoc): sistema de controle de versão distribuído para alterações de rastreamento em código-fonte.
Páginas man do Linux <https://salsa.debian.org/manpages-l10n-team/manpages-l10n> (man)

Este projeto fornece uma infraestrutura para traduzir muitas páginas man para diferentes idiomas, prontas para integração em várias grandes distribuições (Arch Linux, Debian e derivados, Fedora).

Stellarium <https://github.com/Stellarium/stellarium> (HTML): um planetário de código aberto e livre para o seu computador. po4a é usado para traduzir as descrições da cultura do céu.
Jamulus <https://jamulus.io/> (markdown, yaml, HTML): a FOSS application for online jamming in real time. The website documentation is maintained in multiple languages using po4a.
Outro item para resolver: <https://gitlab.com/fdroid/fdroid-website/> <https://github.com/fsfe/reuse-docs/pull/61>
 

FAQ

 

Como você pronuncia po4a?

Eu pessoalmente vocalizo-o como pouah <https://en.wiktionary.org/wiki/pouah>, que é um onomatopoético francês que usamos no lugar de ``eca'' :) eu posso ter um senso de humor estranho :)  

Why are the individual scripts deprecated?

Indeed, po4a-updatepo and po4a-translate are deprecated in flavor of po4a. The reason is that while po4a can be used as a drop-in replacement to these scripts, there is quite a lot of code duplication here. Individual scripts last around 150 lines of codes while the po4a program lasts 1200 lines, so they do a lot in addition of the common internals. The code duplication results in bugs occuring in both versions and needing two fixes. One example of such duplication are the bugs #1022216 in Debian and the issue #442 in GitHub that had the exact same fix, but one in po4a and the other po4a-updatepo.

In the long run, I would like to drop the individual scripts and only maintain one version of this code. The sure thing is that the individual scripts will not get improved anymore, so only po4a will get the new features. That being said, there is no deprecation urgency. I plan to keep the individual scripts as long as possible, and at least until 2030. If your project still use po4a-updatepo and po4a-translate in 2030, you may have a problem.

We may also remove the deprecation of these scripts at some point, if a refactoring reduces the code duplication to zero. If you have an idea (or better: a patch), your help is welcome.  

E as outras ferramentas de tradução para documentação usando gettext?

There are a few of them. Here is a possibly incomplete list, and more tools are coming at the horizon.
poxml
Essa é a ferramenta desenvolvida pelo pessoal do KDE para manipular DocBook XML. Até onde eu sei, esse foi o primeiro programa a extrair strings para traduzir de documentação para arquivos PO, e a injetá-las de volta após a tradução.

Ela só consegue manipular XML e apenas um DTD em particular. Eu fico, particularmente, não gosto das listas de manipulação, que acabam com um grande msgid. Quando a lista fica grande, o fragmento se torna mais difícil de engolir.

po-debiandoc
Esse problema desenvolvido por Denis Barbier é uma espécie de precursor do módulo de SGML do po4a, o qual meio que torna-o (po-debiandoc) obsoleto. Como o nome já diz, ele linda apenas o DebianDoc DTD, o qual é meio que um DTD obsoleto.
xml2po.py
Used by the GIMP Documentation Team since 2004, works quite well even if, as the name suggests, only with XML files and needs specially configured makefiles.
Sphinx
The Sphinx Documentation Project also uses gettext extensively to manage its translations. Unfortunately, it works only for a few text formats, rest and markdown, although it is perhaps the only tool that does this managing the whole translation process.

As principais vantagens do po4a sobre eles é a facilidade de adição de conteúdo extra (o que é bem pior lá) e a habilidade de alcançar gettextização.  

RESUMO das vantagens da abordagem baseada em gettext

As traduções não são armazenadas junto do original, o que possibilita detectar se as traduções estão desatualizadas.
As traduções são armazenadas em arquivos separados um dos outros, o que previne tradutores de idiomas diferentes interferir tanto quando da submissão do patch quanto a nível de codificação do arquivo.
Ele é internamente baseado no gettext (mas po4a oferece uma interface bem simples, de forma que você não precisa entender as especificidades para usá-lo). Dessa forma, nós não temos que reinventar a roda e, por causa do seu amplo uso, nós podemos pensar que essas ferramentas meio que não tem erros.
Nada mudou para o usuário final (além do fato de traduções estarem melhor mantidas, espero). o arquivo de documentação resultante distribuído é exatamente o mesmo.
Não há necessidade de tradutores aprenderem um novo arquivo de sintaxe e seu editor de arquivos PO (como o modo PO do Emacs, Lokalize ou Gtranslator) vão funcionar muito bem.
gettext oferece uma forma simples de obter estatísticas sobre o que está feito, o que deveria ser revisto e atualizado e o que ainda deve ser feito. Alguns exemplos podem ser encontrados nesses endereços:

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

Mas tudo tem seu lado negativo, e essa abordagem tem algumas desvantagens com as quais nós temos que lidar.

Addenda are somewhat strange at the first glance.
Você não pode adaptar o texto traduzido às suas preferências, com divisão de um parágrafo aqui e juntar outros dois ali. Mas de certa forma, se há um problema com o original, isso deveria ser relatado como um erro.
Até mesmo com uma interface fácil, ainda é uma nova ferramenta que as pessoas precisam aprender.

Um dos meus sonhos seria integrar de alguma forma po4a ao Gtranslator ou Lokalize. Quando um arquivo de documento fosse aberto, as strings seriam automaticamente extraídas e um arquivo traduzido + arquivo po poderia ser gravado no disco. Se nós conseguirmos fazer um módulo para MS Word (TM) (ou pelo menos RTF), tradutores profissionais podem até mesmo usá-lo.

 

VEJA TAMBÉM

A documentação da ferramenta multifuncional que você deve usar: po4a(1).
A documentação dos scripts individuais do po4a: po4a-gettextize(1), po4a-updatepo(1), po4a-translate(1), po4a-normalize(1).
Os scripts de ajuda adicionais: msguntypot(1), po4a-display-man(1), po4a-display-pod(1).
Os analisadores de cada formato, em particular para ver as opções aceitas por cada um deles: 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).
A implementação da infraestrutura principal: Locale::Po4a::TransTractor(3pm) (particularmente importante para entender a organização do código), Locale::Po4a::Chooser(3pm), Locale::Po4a::Po(3pm), Locale::Po4a::Common(3pm). Por favor, verifique também o arquivo CONTRIBUTING.md na árvore de fonts.
 

AUTORES

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


 

Index

NOME
Introdução
Por que o po4a?
Formatos suportados
Usando po4a
Detailed schema of the po4a workflow
Starting a new translation project
Updating the translations and documents
Usando adendos para adicionar texto extra às traduções
Como ele funciona?
TransTractors and project architecture
Format-specific parsers
Po objects
Contributing to po4a
Projetos de código aberto que usam o po4a
FAQ
Como você pronuncia po4a?
Why are the individual scripts deprecated?
E as outras ferramentas de tradução para documentação usando gettext?
RESUMO das vantagens da abordagem baseada em gettext
VEJA TAMBÉM
AUTORES

This document was created by using the manual pages.
Time: 00:28:47 GMT, January 29, 2024