oracular (7) po4a.7.gz

Provided by: po4a_0.73-2ubuntu1_all bug

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.

       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 você apenas precisa copiar o arquivo-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 em um 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 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.

       gemtext (very highly experimental parser)
           The native plain text format of the Gemini protocol.  The extension ".gmi" is commonly
           used.  Support for this module in po4a is still in its infancy. If you find anything,
           please file a bug or feature request.

       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

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

   Esquema detalhado do fluxo de trabalho do po4a
       Certifique-se de ler po4a(1) antes desta seçã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 detalhes.

       No esquema a seguir, mestre.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 mestre.doc (que pode ser uma página man, um documento XML, um arquivo
       AsciiDoc etc.); os tradutores se preocuparão principalmente com o arquivo PO, enquanto os
       usuários finais verão apenas o arquivo XX.doc.

       Transições com colchetes, como "[po4a atualiza po]", representam a execução de uma
       ferramenta po4a, enquanto transições com chaves, como "{atualização do mestre.doc}",
       representam uma modificação manual dos arquivos do projeto.

                                          mestre.doc
                                              |
                                              V
            +<-----<----+<-----<-----<--------+------->-------->-------+
            :           |                     |                        :
        {tradução}      |        {atualização de mestre.doc}           :
            :           |                     |                        :
          XX.doc        |                     V                        V
        (opcional)      |                 mestre.doc ->-------->------>+
            :           |                  (novo)                      |
            V           V                     |                        |
         [po4a-gettextize]  doc.XX.po---->+   |                        |
                 |           (velho)      |   |                        |
                 |              ^         V   V                        |
                 |              |    [po4a atualiza po]                |
                 V              |           |                          V
            tradução.pot        ^           V                          |
                 |              |       doc.XX.po                      |
                 |              |       (incerto)                      |
            {tradução}          |           |                          |
                 |              ^           V                          V
                 |              |    {edição manual}                   |
                 |              |           |                          |
                 V              |           V                          V
             doc.XX.po --->---->+<---<-- doc.XX.po    adendo      mestre.doc
             (inicial)                 (atualizado)  (opcional)  (atualizado)
                 :                          |            |             |
                 :                          V            |             |
                 +----->----->----->------> +            |             |
                                            |            |             |
                                            V            V             V
                                            +------>-----+------<------+
                                                         |
                                                         V
                                              [po4a atualiza traduções]
                                                         |
                                                         V
                                                       XX.doc
                                                   (atualizado)

       Novamente, esse 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 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.

       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
       arquivos de tradução: os novos materiais são extraídos e comparados com a tradução
       existente. A tradução anterior é usado 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.

       Then, the manual editing block depicts the action of the translators, that modify the PO
       files to provide translations to every original string and paragraph. This can be done
       using either a specific editor such as the GNOME Translation Editor, KDE's Lokalize or
       poedit, or using an online localization platform such as weblate or pootle. The
       translation result is a set of PO files, one per language. Please refer to the gettext
       documentation for more details.

       A parte inferior da figura mostra como po4a cria um documento fonte traduzido do documento
       original mestre.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 por sua contraparte traduzida. Opcionalmente, um adendo pode ser usado para
       adicionar um texto extra à 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 arquivos de tradução e os arquivos de
       documentação traduzidos.

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

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

   Atualizando as traduções e os documentos
       Após a configuração, invocar po4a é suficiente para atualizar os arquivos PO de tradução e
       os documentos traduzidos. Você pode passar o "--no-translations" para po4a para não
       atualizar as traduções (atualizando apenas os arquivos PO) ou "--no-update" para não
       atualizar os arquivos PO (atualizando apenas as traduções). Isso 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 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>

       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 seção.
       Portanto, essa linha de cabeçalho exige a inserção do adendo após a seção que contém
       "About this document" e instrui o po4a que uma seção começa com uma linha que contém a tag
       "<section>". Isso é equivalente ao exemplo anterior, porque o que você realmente deseja é
       adicionar este adendo após "</section>" ou antes de "<section>".

       You can also set the insertion mode to the value "before", with a similar semantic:
       combining "mode=before" with an "endboundary" will put the addendum just after the matched
       boundary, that is the last potential boundary line before the "position". Combining
       "mode=before" with an "beginboundary" will put the addendum just before the matched
       boundary, that is the last potential boundary line before the "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 o 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"

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

            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?

       Este capítulo dá a você uma visão geral da parte interna do po4a, de forma que você pode
       se sentir mais confiante para nos ajudar a mantê-lo e melhorá-lo. Ele também pode ajudá-lo
       a entender o porquê de ele não funcionar da forma que você esperava, e como resolver 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. Esse nome estranho vem do fato que ele é ao mesmo
       tempo o encarregado por tradução de documento e extração de strings.

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

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

       Este ossinho é o núcleo de toda a arquitetura po4a. Se você fornecer a entrada e
       desconsiderar o PO de saída, obterá po4a-translate. Se você desconsiderar o documento de
       saída, obterá po4a-updatepo. O po4a usa um primeiro TransTractor para obter um arquivo POT
       de saída atualizado (desconsiderando os documentos de saída), chama msgmerge -U para
       atualizar os arquivos PO de tradução no disco e constrói um segundo TransTractor com estes
       arquivos 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 arquivo 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 arquivo 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 strings 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 string é completamente analisada, o analisador usa TransTractor::translate() para
       (1) adicionar essa string ao arquivo PO de saída e (2) obter a tradução do arquivo PO de
       entrada. O analisador então envia o resultado para o arquivo 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 arquivos 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 string no arquivo de entrada não é mantida pelo analisador, então só
       podemos fornecer "$filename:1" como localização da string. Os analisadores orientados a
       SAX usam globais e outros truques para salvar o nome do arquivo e os números de linha das
       referências.

       One specific issue 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.

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

   Contribuindo para o po4a
       Mesmo que você nunca tenha contribuído para nenhum projeto de código aberto no passado,
       você é bem-vindo: estamos dispostos a ajudá-lo e orientá-lo aqui. po4a é melhor mantido
       por seus usuários 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 você tenha confiança
       em contribuir com o projeto. Consulte o arquivo CONTRIBUTING.md para obter mais detalhes.

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

       •   Site do F-Droid <https://gitlab.com/fdroid/fdroid-website> (markdown): catálogo
           instalável de aplicativos 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 aplicativo FOSS para jamming
           online em tempo real. A documentação do site é mantida em vários idiomas usando 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 :)

   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 esses 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 usa po4a-updatepo e po4a-translate em 2030, você 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 você tem uma ideia (ou melhor: um
       patch), sua ajuda é bem-vinda.

   E as outras ferramentas de tradução para documentação usando gettext?
       Existem alguns deles. Aqui está uma lista possivelmente incompleta e mais ferramentas
       estão surgindo no horizonte.

       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
           Usado pela equipe de documentação do GIMP desde 2004, funciona muito bem mesmo que,
           como o nome sugere, apenas com arquivos XML e precise de makefiles especialmente
           configurados.

       Sphinx
           O Projeto de Documentação Sphinx também usa gettext extensivamente para gerenciar suas
           traduções. Infelizmente funciona apenas para alguns formatos de texto, rest e
           markdown, embora seja talvez a única ferramenta que faz isso gerenciando todo o
           processo de tradução.

       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.

       • Os adendos são meio que estranhos à primeira vista.

       • 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)