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

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

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

=encoding UTF-8

=head1 NOME

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

=head1 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.

=head1 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.

B<O objetivo do projeto po4a é facilitar o trabalho dos tradutores de
documentação>. Em particular, ele torna possível I<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 B<FAQ> abaixo neste documento para uma lista mais
completa de vantagens e desvantagens desta abordagem.

=head2 Formatos suportados

Atualmente, essa abordagem tem sido implementada com sucesso em vários
formatos de formatação de texto:

=over

=item 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 L<Locale::Po4a::Man(3pm)|Man> também possui suporte ao formato mdoc
usado pelas páginas man do BSD (elas também são bastante comuns no Linux).

=item 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 L<Locale::Po4a::AsciiDoc> para detalhes.

=item 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 L<Locale::Po4a::Pod> para detalhes.

=item 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. B<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 L<Locale::Po4a::Sgml(3pm)>
para mais detalhes.

=item 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 L<Locale::Po4a::LaTeX(3pm)|LaTeX> foi testado com a documentação do
Python, um livro e algumas apresentações.

=item 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
L<Locale::Po4a::Text(3pm)|Text> para detalhes.

=item xml e XHMTL (analisador provavelmente maduro)

O formato XML é um formato base para muitos formatos de documentação.

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

=item BibTex (analisador provavelmente maduro)

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

Veja L<Locale::Po4a::BibTex> para detalhes.

=item Docbook (analisador provavelmente maduro)

Uma linguagem de marcação baseada em XML que usa tags semânticas para
descrever documentos.

Veja L<Locale::Po4a:Docbook> para mais detalhes.

=item 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 L<Locale::Po4a:Guide> para mais detalhes.

=item 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 L<Locale::Po4a::Wml> para mais detalhes.

=item 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 L<Locale::Po4a::Yaml> para mais detalhes.

=item 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 L<Locale::Po4a::RubyDoc> para mais detalhes.

=item 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 L<Locale::Po4a:Halibut> para mais detalhes.

=item Ini (analisador altamente experimental)

Formato de arquivo de configuração popularizado pelo MS-DOS.

Veja L<Locale::Po4a::Ini> para mais detalhes.

=item 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
L<Locale::Po4a::Texinfo(3pm)|Texinfo> no po4a ainda está nas fases
iniciais. Por favor relate eventuais erros e requisição por recursos.

=item gemtext (analisador altamente experimental)

O formato de texto simples nativo do protocolo Gemini. A extensão C<.gmi> é
comumente usada. O suporte para este módulo no po4a ainda está em estágio
muito inicial. Se você encontrar alguma coisa, registre um relatório de bug
ou uma solicitação de recurso.

=item org (analisador altamente experimental)

O formato de documento usado pelo modo Org. O suporte para este módulo no
po4a ainda está em estágio muito inicial. Se você encontrar alguma coisa,
registre um relatório de bug ou uma solicitação de recurso.

=item vimhelp (analisador altamente experimental)

O formato usado para arquivos de ajuda do Vim (e alguma documentação do
plugin de terceiros). O suporte para este formato em po4a ainda está em sua
infância. Se você encontrar alguma coisa, por favor, envie um relatório de
bug ou uma solicitação de recurso.

=item simplepod (analisador altamente experimental)

Semelhante ao I<pod> mencionado anteriormente, este adota o novo
L<Pod::Simple> como analisador. Como foi criado recentemente, alguns bugs
são esperados. Se notar algum comportamento estranho, por favor, nos
avise. Eventualmente, este módulo substituirá o I<pod>.

=item 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+
(L<Locale::Po4a::KernelHelp>) ou diagramas produzidos pela ferramenta Dia
(L<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
L<Locale::Po4a::TransTractor(3pm)> para mais informações sobre isso.

=item 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.

=back

=head1 Usando po4a

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

=head2 Esquema detalhado do fluxo de trabalho do po4a

Certifique-se de ler L<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, F<mestre.doc> é um nome de exemplo para a documentação
a ser traduzida; F<XX.doc> é o mesmo documento traduzido no idioma XX,
enquanto F<doc.XX.po> é o catálogo de traduções desse documento no idioma
XX. Os autores da documentação se preocuparão principalmente com
F<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 F<XX.doc>.

Transições com colchetes, como C<[po4a atualiza po]>, representam a execução
de uma ferramenta po4a, enquanto transições com chaves, como C<{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 L<po4a(1)> para
uma visão geral simplificada.

A parte esquerda mostra como L<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 L<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.

Então, o bloco I<edição manual> 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 B<Editor
de Tradução do GNOME>, o B<Lokalize> do KDE ou B<poedit>, ou usando uma
plataforma de localização online como o B<weblate> ou B<pootle>. O resultado
da tradução é um conjunto de arquivos PO, um por idioma. Consulte a
documentação gettext para mais detalhes.

A parte inferior da figura mostra como B<po4a> cria um documento fonte
traduzido do documento original F<mestre.doc> e do catálogo de traduções
F<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, B<po4a> atualiza automaticamente os arquivos de tradução e
os arquivos de documentação traduzidos.

=head2 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 L<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 B<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.

=head2 Atualizando as traduções e os documentos

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

=head2 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 B<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 I<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 B<PO4A-HEADER:>, seguida por
uma lista separada por ponto e vírgula dos campos I<chave>B<=>I<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 C<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 C<position> (isso pode ser um regexp). Não
esqueça que o po4a considera o documento B<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 C<position> é encontrada no documento de destino, o po4a
procura a próxima linha após a C<position> que corresponde ao C<endboundary>
fornecido. O adendo é adicionado à direita B<after> essa linha (porque
fornecemos um I<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 C<< <section> >>
após a linha correspondente a C<About this document> na tradução e adicione
o adendo B<before> dessa linha, pois fornecemos um I<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 C<About this
document> e instrui o po4a que uma seção começa com uma linha que contém a
tag C<< <section> >>. Isso é equivalente ao exemplo anterior, porque o que
você realmente deseja é adicionar este adendo após C<< </section> >> ou
antes de C<< <section> >>.

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

=head3 Dicas e truques sobre adendos

=over

=item

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 C<.fi>, não use C<.fi> como
B<endboundary> porque ele vai corresponder a C<the[ fi]le>, o que obviamente
não é o que está esperando. O B<endboundary> correto neste caso é:
C<^\.fi$>.

=item

Espaços em branco SÃO importantes no conteúdo da C<position> e
limites. Portanto, as duas linhas seguintes B<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>

=item

Embora essa pesquisa de contexto possa ser considerada como operando
aproximadamente em cada linha do documento B<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 I<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.

=item

Passe o argumento C<-vv> para o B<po4a> para entender como os adendos são
adicionados à tradução. Também pode ajudar a executar B<po4a> no modo de
depuração para ver a string de dados interna real quando o seu adendo não se
aplica.

=back

=head3 Exemplos de adendos

=over

=item

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
B<mode=after>. Em seguida, você deve restringir a pesquisa à linha após
B<AUTHORS> com a regex de argumento B<position>. Então, você deve combinar o
início da próxima seção (isto é, B<^ \. SH>) com a regex de argumento
B<beginboundary>. Isso é para dizer:

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

=item

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

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

=item

Se você quiser adicionar alguma coisa ao final do documento, forneça um
B<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
B<endboundary> correspondendo a nada. Não use strings simples aqui como
B<"EOF">, e sim prefira aquelas que possuem menos chance de estar no seu
documento.

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

=back

=head3 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 B<beginboundary>
C</^=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 B<mode>=I<before>:

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

=head1 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.

=head2 TransTractors e arquitetura do projeto

No centro do projeto do po4a, a classe
L<Locale::Po4a::TransTractor(3pm)|TransTractor> é 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á B<po4a-translate>. Se você
desconsiderar o documento de saída, obterá B<po4a-updatepo>. O B<po4a> usa
um primeiro TransTractor para obter um arquivo POT de saída atualizado
(desconsiderando os documentos de saída), chama B<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, B<po4a> fornece uma solução completa para atualizar o
que precisa ser, usando um único arquivo de configuração.

B<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 L<po4a-gettextize(1)>.

=head2 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
C<TransTractor::shiftline()>, acumulam o conteúdo dos parágrafos ou algo
assim. Depois que uma string é completamente analisada, o analisador usa
C<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
C<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
C<TransTractor::translate()> e C<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.

Um problema específico surge das codificações de arquivos e dos marcadores
BOM. Analisadores simples podem esquecer esse problema, que é tratado por
C<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 arquivos sejam lidos com uma camada de
decodificação PerlIO apropriada. O mais fácil é abrir o arquivo você mesmo e
fornecer um identificador de arquivo ou diretamente a string completa para
seu analisador externo. Verifique C<Pod::read()> e C<Pod::parse()> para
obter um exemplo. O conteúdo lido pelo TransTractor é ignorado, mas um novo
identificador de arquivo é passado para o analisador externo. A parte
importante é o modo C<< "<:encoding($charset)" >> que é passado para a
função perl B<open()>.

=head2 Objetos PO

A classe L<Locale::Po4a::Po(3pm)|Po> é 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 B<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 B<msgmerge> e B<msgfmt>
respectivamente.

=head2 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.

=head1 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).

=over

=item

adduser (man): ferramenta de gerenciamento de usuários e grupos.

=item

apt (man, docbook): Gerenciador de pacotes do Debian.

=item

aptitude (docbook, svg): Gerenciador de pacotes em interface de texto para
Debian

=item

L<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.

=item

L<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.

=item

L<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).

=item

L<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.

=item

L<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.

=item

Outro item para resolver: L<https://gitlab.com/fdroid/fdroid-website/>
L<https://github.com/fsfe/reuse-docs/pull/61>

=back

=head1 FAQ

=head2 Como você pronuncia po4a?

Eu pessoalmente vocalizo-o como
L<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 :)

=head2 Por que os scripts individuais foram descontinuados?

De fato, B<po4a-updatepo> e B<po4a-translate> foram descontinuados em favor
de B<po4a>. A razão é que, embora B<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
B<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 B<po4a> e outro em B<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 B<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
B<po4a-updatepo> e B<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.

=head2 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.

=over

=item B<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.

=item B<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.

=item B<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.

=item B<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.

=back

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.

=head2 RESUMO das vantagens da abordagem baseada em gettext

=over 2

=item

As traduções não são armazenadas junto do original, o que possibilita
detectar se as traduções estão desatualizadas.

=item

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.

=item

Ele é internamente baseado no B<gettext> (mas B<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.

=item

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.

=item

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.

=item

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/

=back

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

=over 2

=item

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

=item

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.

=item

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.

=back

=head1 VEJA TAMBÉM

=over

=item

A documentação da ferramenta multifuncional que você deve usar: L<po4a(1)>.

=item

A documentação dos scripts individuais do po4a: L<po4a-gettextize(1)>,
L<po4a-updatepo(1)>, L<po4a-translate(1)>, L<po4a-normalize(1)>.

=item

Os scripts de ajuda adicionais: L<msguntypot(1)>, L<po4a-display-man(1)>,
L<po4a-display-pod(1)>.

=item

Os analisadores de cada formato, em particular para ver as opções aceitas
por cada um deles: L<Locale::Po4a::AsciiDoc(3pm)> L<Locale::Po4a::Dia(3pm)>,
L<Locale::Po4a::Gemtext(3pm)>, L<Locale::Po4a::Guide(3pm)>,
L<Locale::Po4a::Ini(3pm)>, L<Locale::Po4a::KernelHelp(3pm)>,
L<Locale::Po4a::Man(3pm)>, L<Locale::Po4a::RubyDoc(3pm)>,
L<Locale::Po4a::Texinfo(3pm)>, L<Locale::Po4a::Text(3pm)>,
L<Locale::Po4a::Xhtml(3pm)>, L<Locale::Po4a::Yaml(3pm)>,
L<Locale::Po4a::BibTeX(3pm)>, L<Locale::Po4a::Docbook(3pm)>,
L<Locale::Po4a::Halibut(3pm)>, L<Locale::Po4a::LaTeX(3pm)>,
L<Locale::Po4a::Org(3pm)>, L<Locale::Po4a::Pod(3pm)>,
L<Locale::Po4a::SimplePod(3pm)>, L<Locale::Po4a::Sgml(3pm)>,
L<Locale::Po4a::TeX(3pm)>, L<Locale::Po4a::VimHelp>,
L<Locale::Po4a::Wml(3pm)>, L<Locale::Po4a::Xml(3pm)>.

=item

A implementação da infraestrutura principal:
L<Locale::Po4a::TransTractor(3pm)> (particularmente importante para entender
a organização do código), L<Locale::Po4a::Chooser(3pm)>,
L<Locale::Po4a::Po(3pm)>, L<Locale::Po4a::Common(3pm)>. Por favor, verifique
também o arquivo F<CONTRIBUTING.md> na árvore de fonts.

=back

=head1 AUTORES

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

=head1 TRADUÇÃO

 Luiz Fernando Ranghetti <elchevive@opensuse.org>
 Rafael Fontenelle <rafaelff@gnome.org>

