
        *****************************************************
        *           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 - quadro para traduzir a 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, com foco nos
utilizadores em potencial, a considerar 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 é 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 de copiar o
ficheiro-fonte da documentação e começar a traduzir o conteúdo. No entanto,
quando a documentação original é modificada, manter-se a par das
modificações rapidamente transforma-se num pesadelo para os tradutores. Se
for 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 I<manter> traduções de documentações
possível.

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í. Suporte do po4a é muito bem-vindo, a considerar que esse formato é de
certa forma difícil de usar e não mesmo 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 a usar po4a.

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

=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 o 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 obter 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, debian/changelong 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 de 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 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 Outros formatos suportados

Po4a também pode lidar com alguns formatos mais raros ou especializados,
como a documentação de opções de compilação para os kernels 2.4+ ou os
diagramas produzidos pela ferramenta dia. Adicionar um formato novo é muitas
vezes bastante fácil e a tarefa principal é chegar com um analisador do
formato de destino dele. Consulte L<Locale::Po4a::TransTractor(3pm)> para
obter mais informações sobre isso.

=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

Historicamente, o po4a foi construído à volta de quatro scripts, cada um a
cumprir uma tarefa específica. L<po4a-gettextize(1)> ajuda na inicialização
de traduções e, opcionalmente, na conversão de projetos de tradução
existentes em po4a. L<po4a-updatepo(1)> reflete as alterações na
documentação original nos ficheiros po correspondentes. L<po4a-translate(1)>
constrói o ficheiro de origem traduzido do ficheiro original e do ficheiro
PO correspondente. Além disso, L<po4a-normalize(1)> é principalmente útil
para depurar os analisadores de po4a, pois produz um documento não traduzido
do original. Torna mais fácil identificar as falhas introduzidas pelo
processo de análise.

A maioria dos projetos requer apenas os recursos de L<po4a-updatepo(1)> e
L<po4a-translate(1)>, mas esses scripts provaram ser pesados e propensos a
erros. Se a documentação a ser traduzida estiver dividida em vários
ficheiros fonte, é difícil manter os ficheiros PO atualizados e criar os
ficheiros de documentação corretamente. Como resposta, uma ferramenta
multifuncional foi fornecida: L<po4a(1)>. Essa ferramenta utiliza um
ficheiro de configuração que descreve a estrutura do projeto de tradução: o
local dos ficheiros PO, a lista de ficheiros a serem traduzidos e as opções
a serem usadas, além de automatizar o processo completamente. Quando invoca
L<po4a(1)>, ele atualiza os ficheiros PO e regenera os ficheiros de tradução
necessários. Se tudo já estiver atualizado, L<po4a(1)> não altera nenhum
ficheiro.

O restante desta secção fornece uma visão geral de como usar a interface de
scripts do po4a. A maioria dos utilizadores provavelmente preferirá usar a
ferramenta multifuncional, descrita na documentação de L<po4a(1)>.

=head2 Visão geral gráfica dos scripts do po4a

O esquema a seguir fornece uma visão geral de como cada script po4a pode ser
usado. Aqui, 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 ou
semelhante); os tradutores se preocuparão principalmente com o ficheiro PO,
enquanto os utilizadores finais verão apenas o ficheiro F<XX.doc>.

                                   original.doc
                                       |
                                       V
     +<-----<----+<-----<-----<--------+------->-------->-------+
     :           |                     |                        :
 {tradução}      |         { actualização do original.doc }     :
     :           |                     |                        :
   XX.doc        |                     V                        V
(opcional)       |               original.doc ->-------->------>+
     :           |                  (novo)                      |
     V           V                     |                        |
  [po4a-gettextize]    doc.XX.po--->+  |                        |
          |             (antigo)    |  |                        |
          |              ^          V  V                        |
          |              |     [po4a-atualizar po]              |
          V              |             |                        V
     tradução.pot        ^             V                        |
          |              |         doc.XX.po                    |
          |              |         (impreciso)                  |
     {tradução}          |           |                          |
          |              ^           V                          V
          |              |     {edição manual}                  |
          |              |           |                          |
          V              |           V                          V
      doc.XX.po --->---->+<---<---- doc.XX.po   adenda     original.doc
      (inicial)                   (atualizado) (optional)   (atualizado) 
          :                          |            |             |
          :                          V            |             |
          +----->----->----->------> +            |             |
                                     |            |             |
                                     V            V             V
                                     +------>-----+------<------+
                                                  |
                                                  V
                                           [po4a-traduzido]
                                                  |
                                                  V
                                                XX.doc
                                            (atualizado)

Esse esquema é complicado, mas na prática apenas a parte correta (a envolver
L<po4a-updatepo(1)> e L<po4a-translate(1)>) é usada depois que o projeto é
instalado e configurado.

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 na parte certa do esquema.

Na parte superior direita, a ação do autor original é retratada, a atualizar
a documentação. Na parte do meio, à direita, as ações automáticas de
L<po4a-updatepo(1)> são representadas. O novo material é extraído e
comparado com a tradução de saída. A tradução anterior é utilizada para as
partes que não mudaram, enquanto as partes parcialmente modificadas são
ligadas à tradução anterior com um marcador "fuzzy" a indicar que a tradução
deve ser atualizada. O material novo ou fortemente modificado não é
traduzido.

A seguir, a I<edição manual> relatada representa a ação dos tradutores, que
modificam os ficheiro PO para fornecer traduções para todas as cadeias e os
parágrafos originais. Isso pode ser feito a usar um editor específico, como
o B<Editor de Tradução do GNOME>, o B<Lokalize> do KDE ou B<poedit> ou a
usar 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 detalhes.

A parte inferior da figura mostra como L<po4a-translate(1)> 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.

Como observado anteriormente, o programa L<po4a(1)> combina os efeitos dos
scripts separados, a atualizar os ficheiros PO e o documento traduzido numa
chamada. A lógica subjacente permanece a mesma.

=head2 Iniciar uma nova tradução

Se usar L<po4a(1)>, não há etapas específicas para iniciar uma
tradução. Apenas precisa listar os idiomas no ficheiro de configuração e os
ficheiros PO ausentes são criados automaticamente. Naturalmente, o tradutor
deve fornecer traduções para todos os conteúdos usados nos seus
documentos. L<po4a(1)> também cria um ficheiro POT, que é um ficheiro de
modelo de PO. Tradutores possíveis podem traduzir o seu projeto a um novo
idioma a renomear esse ficheiro e a fornecer as traduções no idioma deles.

Se preferir usar os scripts individuais separadamente, use
L<po4a-gettextize(1)> da maniera seguinte para criar o ficheiro POT. Este
ficheiro pode ser copiado em F<XX.po> para iniciar uma nova tradução.

  $ po4a-gettextize --format <format> --master <master.doc> --po <translation.pot>

O documento mestre é usado na entrada, enquanto o ficheiro PO é a saída
deste processo.

=head2 Integrar alterações ao documento original

O script a ser usado para isso é L<po4a-updatepo(1)> (consulte a
documentação para obter detalhes):

  $ po4a-updatepo --format <format> --master <new_master.doc> --po <old_doc.XX.po>

O documento mestre é usado na entrada, enquanto o ficheiro PO é atualizado:
ele é usado tanto na entrada quanto na saída.

=head2 Geração de um documento traduzido

Uma vez que acabou com a tradução, deseja obter a documentação traduzida e
distribuí-la aos utilizadores com o original. Para isso, use o programa
L<po4a-translate(1)> como a seguir:

  $ po4a-translate --format <format> --master <master.doc> --po <doc.XX.po> --localized <XX.doc>

Os ficheiros mestre e PO são usados na entrada, enquanto o ficheiro
localizado é a saída desse processo.

=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<Sobre este documento>
na tradução.

=pod

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

Na prática, ao tentar aplicar um adendo, o po4a pesquisa a primeira linha
correspondente ao argumento 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 adiciona 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, essa 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
marcação C<<section>>. Isso é 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>
pôrá 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> pôrá 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<são diferentes>. 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 a 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 B<-vv> para po4a para entender como os adendos são
adicionados à tradução. Também pode ajudar a executar po4a no modo de
depuração para ver a 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 a abordagem em duas etapas a configurar B<mode=after>. Em
seguida, deve restringir a pesquisa à linha após B<AUTHORS> com a regex de
argumento B<position>. Depois deve combinar o início da próxima secção (isto
é, B<^ \. SH>) com a regex de argumento B<beginboundary>. Isso é 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 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

Isso funciona porque a próxima linha a corresponder ao B<beginboundary>
/^=head1/ após a secção "NAME" (traduzido para "NOM" em Francês) é aquela a
declarar 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 pôrá 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á-nos uma visão geral interna do po4a, de modo que possa
sentir-se mais confiante para nos ajudar a manter e a melhorar. Pode também
ajudá-lo a entender por que ele não faz o que esperava e como resolver os
seus problemas.

A arquitetura do po4a é orientada a objetos. A
L<Locale::Po4a::TransTractor(3pm)|TransTractor> class é o ancestral comum a
todos os analisadores do po4a. Este estranho nome vem do facto de ser ao
mesmo tempo responsável pela tradução de documentos e pela extração de
cadeias.

Mais formalmente, é preciso um documento para traduzir mais um ficheiro PO
que contém as traduções para usar como entrada, enquanto produz duas saídas
separadas: Outro ficheiro PO (resultante da extração das sequências
traduzíveis no documento de entrada) e um documento traduzido (com a mesma
estrutura do que a entrada, mas com todas as sequências de cadeias
traduzíveis substituídos com o conteúdo de entrada PO). Aqui é uma
representação gráfica deste:

   entrada documento --\                             /---> saída documento
                       \      TransTractor::       /       (traduzido)
                        +-->--  analise()  --------+
                      /                             \
   entrada PO --------/                               \---> saída PO
                                                           (extraido)



Este pequeno osso é o núcleo de toda a arquitetura do po4a. Se omitir o PO
de entrada e o documento de saída, obtém B<po4a-gettextize>. Se fornecer
ambos ficheiros de entrada e desconsiderar o PO de saída, obtém
B<po4a-translate>. O B<po4a> chama o TransTractor duas vezes e chama
B<msgmerge -U> entre essas chamadas do TransTractor para fornecer uma
solução completa com um único ficheiro de configuração. Por favor veja
L<Locale::Po4a::TransTractor(3pm)> para 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 a
documentação deles. Se quiser adicionar o seu projeto à lista, basta nos
enviar um e-mail (ou uma merge request).

=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<Site do F-Droid|https://gitlab.com/fdroid/fdroid-website> (markdown):
catálogo instalável de aplicações FOSS (abreviação de software livre e de
código aberto) para a plataforma Android.

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

=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 E sobre as outras ferramentas de tradução para documentação a usar gettext?

Quanto sei, existem apenas duas delas:

=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 de 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 despreza. Como o nome diz, ele trata apenas o
DebianDoc DTD, que é mais ou menos um DTD obsoleto.

=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 aproximação de base ao 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/pt_BR/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 

Adendos são… 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 VER 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 

Os analisadores de cada formato, particularmente para ver as opções aceitas
por cada um deles:L<Locale::Po4a::AsciiDoc(3pm)> L<Locale::Po4a::Dia(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::Pod(3pm)>,
L<Locale::Po4a::Sgml(3pm)>, L<Locale::Po4a::TeX(3pm)>,
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 de fonts.

=back

=head1 AUTORES

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

