
        *****************************************************
        *           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 - infraestrutura para traduzir documentação e outros materiais

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

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

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

=head2 Formatos suportados

Atualmente, esta abordagem tem sido implementada com sucesso para vários
tipos de 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í. 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 L<Locale::Po4a::Man(3pm)|Man> também possui suporte do 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 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 L<Locale::Po4a::AsciiDoc> para detalhes.

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

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

=item TeX / LaTeX (analisador maduro)

O formato LaTeX é o formato de documentação principal usado nas publicações
de Software Livre mundiais.

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

=item 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
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 detalhes)
e o 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 etiquetas 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 núcleo 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 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 L<Locale::Po4a:Halibut> para mais detalhes.

=item Ini (analisador provavelmente experimental)

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

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

=item 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
L<Locale::Po4a::Texinfo(3pm)|Texinfo> em po4a ainda está no início. Por
favor, reporte erros e solicitações de 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 encontrar alguma coisa, registe um relatório de bug ou uma
solicitação de recurso.

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

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

=item simplepod (analisador altamente experimental)

Semelhante ao anteriormente mencionado I<pod>, este adota o novo
L<Pod::Simple> como seu analisador.  Como é criação recente, são esperados
alguns bugs.  Se você notar qualquer comportamento estranho, por favor
diga-nos.  Eventualmente, este módulo irá substituir o I<pod>.

=item 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+
(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 o seu formato
alvo. Veja L<Locale::Po4a::TransTractor(3pm)> para mais informações sobre
isto.

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

=back

=head1 Usar o po4a

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

=head2 Esquema detalhado do fluxo de trabalho do po4a

Certifique-se de ler L<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, F<master.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<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 F<XX.doc>.

Transições com parênteses retos, como C<[po4a atualiza po]>, representam a
execução de uma ferramenta po4a, enquanto transições com chavetas, como
C<{atualização do mestre.doc}>, representam uma modificação manual dos
ficheiros 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, este 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 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 L<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 I<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
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 ficheiros PO, um por idioma. Consulte
a documentação gettext para mais pormenores.

A parte inferior da figura mostra como B<po4a> cria um documento fonte
traduzido do documento original F<master.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 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, B<po4a> atualiza automaticamente os ficheiros de tradução
e os ficheiros de documentação traduzidos.

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

=head2 Atualizar as traduções e os documentos

Após a configuração, invocar B<po4a> é suficiente para atualizar os
ficheiros PO de tradução e os documentos traduzidos. Pode passar o
C<--no-translations> para B<po4a> para não atualizar as traduções
(atualizando apenas os ficheiros PO) ou C<--no-update> para não atualizar os
ficheiros PO (atualizando apenas as traduções). Isto 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 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 B<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 I<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 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 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 C<About this document>
na tradução.

 PO4A-HEADER: position=Acerca deste 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 se
esqueça que o po4a considera o documento B<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 C<position> foi 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 secção
atual).

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

 PO4A-HEADER: position=Sobre este documento; 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 secção. Portanto, esta linha
de cabeçalho exige a inserção do adendo após a secção que contém C<About
this document> e instrui o po4a que uma secção começa com uma linha que
contém a tag C<< <section> >>. Isto é equivalente ao exemplo anterior,
porque o que realmente deseja é adicionar este adendo após C<< </section> >>
ou antes de C<< <section> >>.

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>
porá 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> porá 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 ficheiro

=head3 Dicas e truques sobre adendos

=over

=item

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

 PO4A-HEADER: position=Acerca deste documento; mode=after; beginboundary=<section>
 PO4A-HEADER: position=Acerca deste documento ; mode=after; beginboundary=<section>

=item

Embora essa pesquisa de contexto possa ser considerada para operar cerca de
cada linha do documento B<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 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 perceber como os adendos são
adicionados à tradução. Também pode ajudar a executar B<po4a> no modo de
depuração para ver a cadeia de dados interna real quando o seu adendo não se
aplica.

=back

=head3 Exemplos de adendos

=over

=item

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

  .SH "AUTORES"

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

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

=item

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

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

=item

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

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

=back

=head3 Exemplo mais detalhado

Documento original (POD formatado):

 |=head1 NOME
 |
 |fictício - um programa fictício
 |
 |=head1 AUTOR
 |
 |eu

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=AUTOR;beginboundary=^=head
 |
 |=head1 TRADUTOR
 |
 |eu
 |

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

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

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

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

   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 fornecer a entrada e
desconsiderar o PO de saída, obterá B<po4a-translate>. Se desconsiderar o
documento de saída, obterá B<po4a-updatepo>. O B<po4a> usa um primeiro
TransTractor para obter um ficheiro POT de saída atualizado (desconsiderando
os documentos de saída), chama B<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, B<po4a>
fornece uma solução completa para atualizar o que precisa ser, usando um
único ficheiro 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 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 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 cadeia é completamente analisada, o analisador usa
C<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
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
ficheiros 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 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
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 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 C<Pod::read()> e C<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 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
ficheiros PO e POT. Basicamente, pode ler um ficheiro, adicionar entradas,
obter traduções com o método B<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 B<msgmerge> e B<msgfmt>
respectivamente.

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

=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 a
documentação deles. Se quiser adicionar o seu projeto à lista, basta nos
enviar um e-mail (ou um Pedido de Fusão).

=over

=item

adduser (man): ferramenta de gestão de utilizadores e grupos.

=item

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

=item

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

=item

L<F-Droid website|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.

=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<Linux manpages|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 aplicação FOSS
para jamming online em tempo real. A documentação do site é mantida em
vários idiomas usando po4a.

=item

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

=back

=head1 PERGUNTAS MAIS FREQUENTES

=head2 Como se pronuncia po4a?

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

=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 estes 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 usar
B<po4a-updatepo> e B<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.

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

=over

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

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

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

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

=back

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.

=head2 SUMÁRIO de vantagens da abordagem baseada em gettext

=over 2

=item

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

=item

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.

=item

É baseado em B<gettext> (mas B<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.

=item

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.

=item

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.

=item

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/

=back

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

=over 2

=item

Os adendos são um pouco estranhos à primeira vista.

=item

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.

=item

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.

=back

=head1 VEJA TAMBÉM

=over

=item

A documentação da ferramenta multifuncional que 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

The parsers of each formats, in particular to see the options accepted by
each of them: 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 ficheiro F<CONTRIBUTING.md> na árvore fonte.

=back

=head1 AUTORES

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