PO4A.7

Section: User Contributed Perl Documentation (1)
Updated: 2025-06-30
Index Return to Main Contents

NOME

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

Introdução

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

Este documento serve como uma introdução ao projeto po4a focado em potenciais utilizadores que considerem a possibilidade de usar essa ferramenta e no desejo curioso de perceber por que as coisas são como são.

Porquê o po4a?

A filosofia do Software Livre é fazer a tecnologia verdadeiramente disponível a todos. Mas o licenciamento não é a única consideração: software livre não traduzido é inútil para quem não fala inglês. Portanto, ainda temos algum trabalho a fazer para fazer o software disponível a 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 Open Source é, na verdade, muito bem traduzido a usar o conjunto de ferramentas gettext. Essas ferramentas são usadas para extrair as cadeias a traduzir de um programa e apresentar as cadeias a traduzir num formato padronizado (chamado de ficheiros PO ou catálogos de tradução). Todo um ecossistema de ferramentas surgiu para ajudar os tradutores a realmente traduzir esses ficheiros PO. O resultado é então utilizado pela gettext em tempo de execução para exibir as mensagens traduzidas para os utilizadores finais.

Em relação à documentação, no entanto, a situação ainda é um pouco decepcionante. No início, traduzir a documentação pode parecer mais fácil do que traduzir um programa, pois parece que apenas precisa copiar o ficheiro-fonte da documentação e começar a traduzir o conteúdo. No entanto, quando a documentação original é modificada, acompanhar as modificações rapidamente se transforma num pesadelo para os tradutores. Se realizada manualmente, esta tarefa é desagradável e propensa a erros.

Traduções desatualizadas geralmente são piores do que nenhuma tradução. Os utilizadores 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 a documentação deles está traduzida. Essas dificuldades, muitas vezes causadas por ferramentas precárias, podem minar a motivação de tradutores voluntários, a agravar o problema ainda mais.

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

A ideia é de reutilizar e adaptar a abordagem gettext a esse campo. Assim como o gettext, os textos são extraídos dos 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 equipa. O po4a injeta as traduções diretamente na estrutura da documentação para produzir ficheiros de origem traduzidos que podem ser processados e distribuídos da mesma forma que os ficheiros em inglês. Qualquer parágrafo que não seja traduzido é deixado em inglês no documento resultante, a garantir que os utilizadores 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 torna-se 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 hipótese de erros de formatação que resultariam num documento quebrado.

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

Formatos suportados

Atualmente, esta abordagem tem sido implementada com sucesso para vários tipos de 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í. O suporte ao po4a é muito bem-vindo pois este formato é de certa forma difícil de usar e realmente não amigável para novatos.
O módulo Locale::Po4a::Man(3pm) também possui suporte do 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 markup 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): Este é o formato de Documentação Perl Online. A linguagem e as próprias extensões são documentadas a usar este formato, além da maioria dos scripts Perl existentes. Torna fácil manter a documentação perto do código real, a incorpora-los ambos no mesmo ficheiro. Torna a vida do programador mais fácil, mas infelizmente não a do tradutor, até que use o po4a.
Veja Locale::Po4a::Pod para detalhes.
sgml (analisador maduro): Mesmo que hoje em dia seja substituído pelo XML, este formato ainda é utilizado para documentos com o comprimento de mais do que alguns ecrãs. Pode até mesmo ser usado para livros inteiros. Pode ser muito desafiador de atualizar documentos deste tamanho. diff frequentemente revela-se inútil quando o texto original foi reintroduzido após a atualização. Felizmente, o po4a pode ajudá-lo após esse processo.
Atualmente, apenas os DTD DebianDoc e DocBook são suportados, mas a acrescentar suporte para um novo é muito simples. É até possível usar po4a num SGML DTD desconhecido sem alterar o código, a fornecer as necessárias informações sobre a linha de comando. Veja Locale::Po4a::Sgml(3pm) para mais detalhes.
TeX / LaTeX (analisador maduro): O formato LaTeX é o formato de documentação principal usado nas publicações de Software Livre mundiais.
O módulo Locale::Po4a::LaTeX(3pm) foi testado com a documentação Python, um livro e algumas apresentações.
text (analisador maduro): O formato Text é o formato base para muitos formatos que incluem longos blocos de texto, incluindo Markdown, fortunes, secção de página de rotos YAML, debian/changelog e debian/control.
Este possui suporte do 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 detalhes) e o 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 etiquetas 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 núcleo 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 provavelmente experimental): Um sistema de produção de documentação, com elementos semelhantes ao TeX, debiandoc-sgml, TeXinfo e outros, desenvolvido por Simon Tatham, o programador do PuTTY.
Veja Locale::Po4a:Halibut para mais detalhes.
Ini (analisador provavelmente experimental): Formato de ficheiro de configuração popularizado pelo MS-DOS.
Veja Locale::Po4a::Ini para mais detalhes.
texinfo (analisador altamente experimental): Toda a documentação GNU está escrita neste formato (ainda é um dos requisitos para um projeto GNU se tornar oficial). O apoio para Locale::Po4a::Texinfo(3pm) em po4a ainda está no início. Por favor, reporte erros e solicitações de recursos.
gemtext (analisador altamente experimental): O formato de texto simples nativo do protocolo Gemini. A extensão ".gmi" é comumente usada. O suporte para este módulo no po4a ainda está em estágio muito inicial. Se encontrar alguma coisa, registe um relatório de bug ou uma solicitação de recurso.
org (analisador altamente experimental): O formato de documento usado pelo modo Org. Apoio para este módulo em po4a continua na sua infância. Se encontrar alguma coisa, por favor crie um bug ou uma solicitação de recurso.
vimhelp (analisador altamente experimental): O formato usado para ficheiros de ajuda do Vim (e alguma documentação do plugin de terceiros). O suporte para este formato em po4a ainda está na sua infância. Se encontrar algo, por favor envie um relatório de bug ou uma solicitação de recurso.
simplepod (very highly experimental parser): Similar to the previously mentioned pod, this one adopts the new 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 pod.
Outros formatos suportados: 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 o seu formato alvo. Veja Locale::Po4a::TransTractor(3pm) para mais informações sobre isto.
Formatos não suportados: Infelizmente, o po4a ainda carece suporte para vários formatos de documentação. Muitos deles facilmente seriam suportados pelo po4a. Isto inclui formatos não apenas usados para documentação, tais como, descrições de pacotes (deb e rpm), questões de scripts de instalação de pacotes, changelogs de pacotes e todos os formatos de ficheiros especializados usados por programas como cenários de jogos ou ficheiros de recursos do wine.

Usar o po4a

A maneira mais fácil de usar esta ferramenta no seu projeto é escrever um ficheiro de configuração para o programa po4a e interagir apenas com este programa. Consulte a sua documentação, em po4a(1). O restante desta secção fornece mais pormenores para os utilizadores avançados do po4a que desejam aprofundar a sua compreensão.

Esquema detalhado do fluxo de trabalho do po4a

Certifique-se de ler po4a(1) antes desta secção excessivamente detalhada para obter uma visão geral simplificada do fluxo de trabalho do po4a. Volte aqui quando quiser ver a imagem assustadora completa, com quase todos os pormenores.

No esquema a seguir, master.doc é um nome de exemplo para a documentação a ser traduzida; XX.doc é o mesmo documento traduzido no idioma XX, enquanto doc.XX.po é o catálogo de traduções desse documento no idioma XX. Os autores da documentação se preocuparão principalmente com master.doc (que pode ser uma página man, um documento XML, um ficheiro AsciiDoc etc.); os tradutores se preocuparão principalmente com o ficheiro PO, enquanto os utilizadores finais verão apenas o ficheiro XX.doc.

Transições com parênteses retos, como "[po4a atualiza po]", representam a execução de uma ferramenta po4a, enquanto transições com chavetas, como "{atualização do mestre.doc}", representam uma modificação manual dos ficheiros do projeto.

                                   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)

Novamente, este esquema é excessivamente complicado. Confira po4a(1) para uma visão geral simplificada.

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 leva um documento original e o equivalente traduzido e tenta construir o ficheiro 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 as suas traduções existentes. Se não tiver nenhuma tradução para converter, pode esquecer-se disto e focar-se na parte certa do esquema.

Na parte superior direita, a ação do autor original está descrita, atualização da documentação. A parte do meio, à direita, representa as atualizações automáticas dos ficheiros de tradução: os novos materiais são extraídos e comparados com a tradução existente. A tradução anterior é usada para as partes que não foram alteradas, enquanto partes parcialmente modificadas também são conectadas à tradução anterior com uma marcação "fuzzy" indicando que a tradução deve ser atualizada. Material novo ou muito modificado é deixado sem tradução.

Então, o bloco edição manual representa a ação dos tradutores, que modificam os ficheiro PO para fornecer traduções para toda cadeias e parágrafo originais. Isto 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 ficheiros PO, um por idioma. Consulte a documentação gettext para mais pormenores.

A parte inferior da figura mostra como po4a cria um documento fonte traduzido do documento original master.doc e do catálogo de traduções doc.XX.po que foram atualizados pelos tradutores. A estrutura do documento é reutilizada, enquanto o conteúdo original é substituído pela contraparte dele traduzida. Opcionalmente, um adendo pode ser usado para adicionar textos à tradução. Isso geralmente é usado para adicionar o nome do tradutor ao documento final. Veja abaixo os detalhes.

Após a invocação, po4a atualiza automaticamente os ficheiros de tradução e os ficheiros de documentação traduzidos.

Iniciar um novo projeto de tradução

Se começa do zero, basta escrever um ficheiro de configuração para po4a e pronto. Os modelos relevantes são criados para os ficheiros ausentes, permitindo que os seus colaboradores traduzam o seu projeto para o idioma deles. Consulte po4a(1) para um tutorial de início rápido e para todos os pormenores.

Se já possui uma tradução, ou seja, um ficheiro de documentação que foi traduzido manualmente, pode integrar o seu conteúdo no seu fluxo de trabalho po4a usando po4a-gettextize. Esta tarefa é um pouco complicada (conforme descrito no manual da ferramenta), mas assim que o seu projeto for convertido para o fluxo de trabalho po4a, tudo será atualizado automaticamente.

Atualizar as traduções e os documentos

Após a configuração, invocar po4a é suficiente para atualizar os ficheiros PO de tradução e os documentos traduzidos. Pode passar o "--no-translations" para po4a para não atualizar as traduções (atualizando apenas os ficheiros PO) ou "--no-update" para não atualizar os ficheiros PO (atualizando apenas as traduções). Isto corresponde aproximadamente aos scripts individuais po4a-updatepo e po4a-translate que agora foram descontinuados (veja "Por que os scripts individuais foram descontinuados" no FAQ abaixo).

Usando adendos para adicionar textos às traduções

Adicionar novos textos à tradução é provavelmente a única coisa mais fácil a longo prazo quando traduz ficheiros manualmente :). Isso acontece quando deseja adicionar uma secção adicional ao documento traduzido, que não corresponde a nenhum conteúdo no documento original. O caso de uso clássico é dar mérito à equipa de tradução e indicar como relatar problemas específicos da tradução.

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

A linha do cabeçalho deve começar com a cadeia 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 posto bem no final da tradução.

 PO4A-HEADER: mode=eof

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

 PO4A-HEADER: position=About this document; 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 se esqueça que o po4a considera o documento translated aqui. Esta documentação é em Inglês, mas a sua linha provavelmente deve ser a seguinte, se pretende que o seu adendo se aplique à tradução do documento em Francês.

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

Depois que a "position" foi 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 secção atual).

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

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

Aqui, o po4a pesquisa a primeira linha correspondente a "<section>" após a linha correspondente a "About this document" na tradução e adicione o adendo before dessa linha, pois fornecemos um beginboundary, ou seja, um limite que marca o início da próxima secção. Portanto, esta linha de cabeçalho exige a inserção do adendo após a secção que contém "About this document" e instrui o po4a que uma secção começa com uma linha que contém a tag "<section>". Isto é equivalente ao exemplo anterior, porque o que realmente deseja é adicionar este adendo após "</section>" ou antes de "<section>".

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" porá o adendo apenas after o limite correspondente, que é a última linha limite potencial antes da "position". Combinar "mode=before" com um "beginboundary" porá o adendo apenas before do limite correspondente, que é a última linha limite potencial antes da "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

Dicas e truques sobre adendos

•

Lembre-se que estes são regexp. Por exemplo, se quiser combinar o final de uma secção nroff a terminar com a linha ".fi", não use ".fi" como endboundary, porque ele irá combinar com "the[ fi]le", que obviamente não é o que espera. O endboundary correto, nesse 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 suficientes à direita no documento traduzido.

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

•

Embora essa pesquisa de contexto possa ser considerada para operar cerca de cada linha do documento traduzido, realmente opera na cadeia de dados interna do documento traduzido. Essa cadeia de dados interna pode ser um texto a abranger um parágrafo que contem várias linhas ou pode ser uma marcação 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 o po4a para perceber como os adendos são adicionados à tradução. Também pode ajudar a executar po4a no modo de depuração para ver a cadeia de dados interna real quando o seu adendo não se aplica.

Exemplos de adendos

•

Se quiser acrescentar algo depois na secção seguinte nroff:

  .SH "AUTHORS"

Deve selecionar uma abordagem em duas etapas configurando mode=after. Em seguida, deve restringir a pesquisa à linha após AUTHORS com a regex de argumento position. Então, deve combinar o início da próxima secção (isto é, ^ \. SH) com a regex de argumento beginboundary. É para dizer:

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

•

Se quiser adicionar algo logo após uma determinada linha (por exemplo, após a linha "Copyright Big Dude"), use uma position a corresponder a esta linha, mode=after e dê um beginboundary a corresponder a qualquer linha.

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

•

Se quiser adicionar alguma coisa no final do documento, dê uma position correspondente a qualquer linha do seu documento (mas apenas uma linha, po4a não continuará se não é única) e dê uma endboundary sem corresponder a nada. Aqui não use cadeias simples como "EOF", mas prefira as que têm menos hipótese de estar no seu documento.

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

Exemplo mais detalhado

Documento original (POD formatado):

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

Então, a adenda a seguir irá garantir que uma secção (em francês) sobre o tradutor é adicionado no final do processo (em francês, "TRADUCTEUR" significa "TRADUTOR" e, "moi" significa "eu").

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

Para posicionar a sua adenda antes do AUTOR, use o seguinte cabeçalho:

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

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

Para evitar isto, pode realizar o mesmo a usar mode=before:

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

Como é que funciona?

Este capítulo dá a uma visão geral da parte interna do po4a, de forma que pode sentir-se mais confiante para nos ajudar a mantê-lo e melhorá-lo. Ele também pode ajudá-lo a perceber o porquê de ele não funcionar da forma que esperava e como resolver os seus problemas.

TransTractors e arquitetura do projeto

No centro do projeto do po4a, a classe Locale::Po4a::TransTractor(3pm) é um antepassado comum para todos analisadores do po4a. Este nome estranho vem do fato que ele é ao mesmo tempo o encarregado por tradução de documento e extração de cadeias.

Mais formalmente, ele leva um documento para traduzir mais um ficheiro PO contendo as traduções para usar como entrada, enquanto produz duas saídas separadas: outro ficheiro PO (resultante da extração das cadeias traduzíveis do documento de entrada) e um documento traduzido (com a mesma estrutura que a da entrada, mas com todas as cadeias traduzíveis substituídas com o conteúdo do PO de entrada). Aqui está uma representação gráfica disso:

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

Este ossinho é o núcleo de toda a arquitetura po4a. Se fornecer a entrada e desconsiderar o PO de saída, obterá po4a-translate. Se desconsiderar o documento de saída, obterá po4a-updatepo. O po4a usa um primeiro TransTractor para obter um ficheiro POT de saída atualizado (desconsiderando os documentos de saída), chama msgmerge -U para atualizar os ficheiros PO de tradução no disco e constrói um segundo TransTractor com estes ficheiros PO atualizados para atualizar os documentos de saída. Resumindo, po4a fornece uma solução completa para atualizar o que precisa ser, usando um único ficheiro de configuração.

po4a-gettextize também usa dois TransTractors, mas de outra forma: ele constrói um TransTractor por idioma e então constrói um novo ficheiro PO usando os msgids do documento original como msgids e os msgids do documento traduzido como msgstrs. É necessário muito cuidado para garantir que as cadeias correspondidas desta forma realmente correspondam, conforme descrito em po4a-gettextize(1).

Analisadores sintáticos específicos de formatos

Todos os analisadores de formato po4a são implementados no TransTractor. Alguns deles são muito simples, como os Text, Markdown e AsciiDoc. Eles carregam as linhas uma por uma usando TransTractor::shiftline(), acumulam o conteúdo dos parágrafos ou algo assim. Depois que uma cadeia é completamente analisada, o analisador usa TransTractor::translate() para (1) adicionar esta cadeia ao ficheiro PO de saída e (2) obter a tradução do ficheiro PO de entrada. O analisador então envia o resultado para o ficheiro de saída usando TransTractor::pushline().

Alguns outros analisadores são mais complexos porque dependem de um analisador externo para analisar o documento de entrada. Os analisadores Xml, HTML, SGML e Pod são construídos com base nos analisadores SAX. Eles declaram retornos de chamada para eventos como "Encontrei um novo título cujo conteúdo é o seguinte" para atualizar o documento de saída e gerar ficheiros POT de acordo com o conteúdo de entrada usando TransTractor::translate() e TransTractor::pushline(). O analisador Yaml é semelhante, mas diferente: ele serializa uma estrutura de dados produzida pelo analisador YAML::Tiny. É por isso que o módulo Yaml do po4a falha ao declarar as linhas de referência: a localização de cada cadeia no ficheiro de entrada não é mantida pelo analisador, então só podemos fornecer "$filename:1" como localização da cadeia. Os analisadores orientados a SAX usam globais e outros truques para gravar o nome do ficheiro e os números de linha das referências.

Um problema específico surge das codificações de ficheiros e dos marcadores BOM. Analisadores simples podem esquecer este problema, que é tratado por TransTractor::read() (usado internamente para obter as linhas de um documento de entrada), mas os módulos que dependem de um analisador externo devem garantir que todos os ficheiros sejam lidos com uma camada de descodificação PerlIO apropriada. O mais fácil é abrir o ficheiro mesmo e fornecer um identificador de ficheiro ou diretamente a cadeia completa para o seu analisador externo. Verifique Pod::read() e Pod::parse() para obter um exemplo. O conteúdo lido pelo TransTractor é ignorado, mas um novo identificador de ficheiro é passado para o analisador externo. A parte importante é o modo "<:encoding($charset)" que é passado para a função perl open().

Objetos PO

A classe Locale::Po4a::Po(3pm) é responsável por carregar e utilizar ficheiros PO e POT. Basicamente, pode ler um ficheiro, adicionar entradas, obter traduções com o método gettext(), gravar o PO num ficheiro. Recursos mais avançados, como mesclar um ficheiro PO com um ficheiro POT ou validar um ficheiro, são delegados a msgmerge e msgfmt respectivamente.

Contribuir para o po4a

Mesmo que nunca tenha contribuído para nenhum projeto de código aberto no passado, é bem-vindo: estamos dispostos a ajudá-lo e orientá-lo aqui. po4a é melhor mantido pelos seus utilizadores hoje em dia. Como não temos mão de obra, procuramos tornar o projeto acolhedor melhorando a documentação e os testes automáticos para que tenha confiança em contribuir com o projeto. Consulte o ficheiro CONTRIBUTING.md para obter mais pormenores.

Projetos de código aberto que usam o po4a

Aqui está uma lista bem parcial de projetos que usam po4a na produção para a documentação deles. Se quiser adicionar o seu projeto à lista, basta nos enviar um e-mail (ou um Pedido de Fusão).

•: adduser (man): ferramenta de gestão de utilizadores e grupos.
•: apt (man, docbook): Gestor de pacotes do Debian.
•: aptitude (docbook, svg): Gestor de pacotes em interface de texto para Debian
•: Site do F-Droid <https://gitlab.com/fdroid/fdroid-website> (markdown): catálogo instalável de aplicações FOSS (abreviação de software livre e de código aberto) para a plataforma Android.
•: 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): um aplicação FOSS para jamming online em tempo real. A documentação do site é mantida em vários idiomas usando po4a.
•: Outro item para ordenar: <https://gitlab.com/fdroid/fdroid-website/> <https://github.com/fsfe/reuse-docs/pull/61>

PERGUNTAS MAIS FREQUENTES

Como se pronuncia po4a?

Pessoalmente vocalizo-o como pouah <https://en.wiktionary.org/wiki/pouah>, que é um onomatopaico francês que usamos no lugar de "eca" :) posso ter um senso de humor estranho :)

Por que os scripts individuais foram descontinuados?

De fato, po4a-updatepo e po4a-translate foram descontinuados em favor de po4a. A razão é que, embora po4a possa ser usado como um substituto imediato para estes scripts, há muita duplicação de código aqui. Os scripts individuais duram cerca de 150 linhas de códigos, enquanto o programa po4a dura 1200 linhas, então eles fazem muito além dos internos comuns. A duplicação de código resulta em bugs ocorrendo em ambas as versões e necessitando de duas correções. Um exemplo dessa duplicação são os bugs #1022216 no Debian e o issue #442 no GitHub que tiveram exatamente a mesma correção, mas um em po4a e outro em po4a-updatepo.

No longo prazo, gostaria de descartar os scripts individuais e manter apenas uma versão deste código. O certo é que os scripts individuais não serão mais melhorados, então apenas po4a receberá os novos recursos. Dito isto, não há urgência na remoção. Pretendo manter os scripts individuais pelo maior tempo possível e pelo menos até 2030. Se o seu projeto ainda usar po4a-updatepo e po4a-translate em 2030, pode ter um problema.

Também podemos remover a descontinuação desses scripts em algum momento, se uma refatoração reduzir a duplicação de código a zero. Se tem uma ideia (ou melhor: um patch), a sua ajuda é bem-vinda.

E sobre as outras ferramentas de tradução para documentação a usar gettext?

Existem alguns deles. Aqui está uma lista possivelmente incompleta e mais ferramentas estão surgindo no horizonte.

poxml: Esta é a ferramenta desenvolvida por pessoas do KDE para lidar com DocBook XML. AFAIK, ele foi o primeiro programa para extrair cadeias para traduzir de documentação para ficheiros PO e injetá-las de volta depois da tradução.
Só pode lidar com XML e apenas um DTD particular. Estou muito descontente com a manipulação de listas, que terminam com um identificador de mensagem (msgid) grande. Quando a lista se torna enorme, o bloco torna-se mais difícil de absorver.
po-debiandoc: Este programa feito por Denis Barbier é uma espécie de precursor do módulo po4a SGML, que mais ou menos o descontinua. Como o nome diz, ele trata apenas o DebianDoc DTD, que é mais ou menos um DTD obsoleto.
xml2po.py: Usado pela equipa de documentação do GIMP desde 2004, funciona muito bem mesmo que, como o nome sugere, apenas com ficheiros XML e precise de makefiles especialmente configurados.
Sphinx: O Projeto de Documentação Sphinx também usa gettext extensivamente para gerir as suas traduções. Infelizmente funciona apenas para alguns formatos de texto, rest e markdown, embora seja talvez a única ferramenta que faz isto a gerir todo o processo de tradução.

As principais vantagens de po4a sobre eles, são a facilidade de adição de conteúdos extra (que é pior ainda lá) e a capacidade de atingir gettextization.

SUMÁRIO de vantagens da abordagem baseada em gettext

•

As traduções não são armazenadas com o original, o que torna possível detetar se as traduções estão desatualizadas.

•

As traduções estão armazenadas em ficheiros separados a partir de cada um, o que previne os tradutores de idiomas diferentes de intervirem, em ambos, quando submetem os seus fragmentos (patches) e no nível do ficheiro codificado.

•

É baseado em gettext (mas po4a oferece uma interface muito simples assim não precisa de compreender os internos para o usar). Dessa forma não precisamos de reinventar a roda e, porque o uso dele é mundial, podemos pensar que estas ferramentas estão mais ou menos livres de erros.

•

Nada muda para o utilizador final (além do fato das traduções serem, como esperamos, melhor mantidas). O ficheiro de documentação resultante é exatamente o mesmo.

•

Os tradutores não precisam de aprender a nova sintaxe de ficheiros e os editores de ficheiros PO favoritos deles (como o modo PO do Emacs, Lokalize ou Gtranslator) irão trabalhar bem.

•

gettext oferece uma maneira simples de obter estatísticas acerca do que é feito, o que deveria ser revisto e atualizado e, o que ainda está por fazer. Alguns exemplos encontram-se nestes endereços:

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

Mas não é tudo verde e, esta aproximação tem também algumas desvantagens com que temos de lidar.

•: Os adendos são um pouco estranhos à primeira vista.
•: Não pode adaptar o texto traduzido as suas preferências, como a dividir um parágrafo aqui e, a juntar outros dois ali. Mas em certo sentido, se existe um problema com o original, deve ser reportado como um erro de qualquer maneira.
•: Mesmo com um interface fácil, continua a ser ferramenta nova que as pessoas têm que aprender.
Um dos meus sonhos seria integrar de alguma forma po4a ao Gtranslator ou Lokalize. Quando um ficheiro de documento fosse aberto, as cadeias seriam automaticamente extraídas e um ficheiro traduzido + ficheiro po poderia ser gravado no disco. Se 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 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).
•: The parsers of each formats, in particular to see the options accepted by each of them: Locale::Po4a::AsciiDoc(3pm) Locale::Po4a::Dia(3pm), Locale::Po4a::Gemtext(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::Org(3pm), Locale::Po4a::Pod(3pm), Locale::Po4a::SimplePod(3pm), Locale::Po4a::Sgml(3pm), Locale::Po4a::TeX(3pm), Locale::Po4a::VimHelp, 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 ficheiro CONTRIBUTING.md na árvore fonte.

AUTORES

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

Index

NOME

Introdução

Porquê o po4a?

Formatos suportados

Usar o po4a

Esquema detalhado do fluxo de trabalho do po4a
Iniciar um novo projeto de tradução
Atualizar as traduções e os documentos
Usando adendos para adicionar textos às traduções

Como é que funciona?

TransTractors e arquitetura do projeto
Analisadores sintáticos específicos de formatos
Objetos PO
Contribuir para o po4a

Projetos de código aberto que usam o po4a

PERGUNTAS MAIS FREQUENTES

Como se pronuncia po4a?
Por que os scripts individuais foram descontinuados?
E sobre as outras ferramentas de tradução para documentação a usar gettext?
SUMÁRIO de vantagens da abordagem baseada em gettext

VEJA TAMBÉM

AUTORES

This document was created by using the manual pages.
Time: 13:03:53 GMT, June 30, 2025