
        *****************************************************
        *           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-gettextize - converte um ficheiro original (e a tradução dele) para um
ficheiro PO

=head1 SINOPSE

B<po4a-gettextize> B<-f> I<fmt> B<-m> I<master.doc> [B<-l> I<XX.doc>] B<-p>
I<XX.po>

(I<XX.po> é a saída, todos os outros são entradas)

=head1 DESCRIÇÃO

po4a (PO for anything) facilita a manutenção de tradução da documentação a
usar as ferramentas clássicas do gettext. A característica principal do po4a
é que ele dissocia a tradução do conteúdo da estrutura documental. Consulte
a página L<po4a(7)> para uma introdução suave a este projeto.

O script B<po4a-gettextize> é responsável pela conversão de ficheiros de
documentação em ficheiros PO. Só precisa dele para configurar o seu projeto
de tradução com o po4a, nunca depois.

Se começar do zero, B<po4a-gettextize> extrairá as cadeias traduzíveis da
documentação e gravará um ficheiro POT. Se fornecer um ficheiro traduzido
existente anteriormente com o sinalizador B<-l>, B<po4a-gettextize> tentará
usar as traduções que ele contém no ficheiro PO produzido. Esse processo
permanece tedioso e manual, conforme explicado na Secção "Converter uma
tradução manual em po4a" abaixo.

Se o documento principal tiver caracteres não ASCII, o novo ficheiro PO
gerado estará em UTF-8. Caso contrário (se o documento principal estiver
completamente em ASCII), o PO gerado utilizará a codificação do documento de
entrada traduzido, ou UTF-8 se não for fornecido nenhum documento traduzido.

=head1 OPÇÕES

=over 4

=item B<-f>, B<--format>

O formato da documentação que pretende processar. Use a opção
B<--help-format> para ver a lista de formatos disponíveis.

=item B<-m>, B<--master>

Ficheiro que contem o documento principal para traduzir. Pode usar esta
opção várias vezes se quiser 'gettextize' vários documentos.

=item B<-M>, B<--master-charset>

Conjunto de carateres do ficheiro que contém o documento a traduzir.

=item B<-l>, B<--localized>

Ficheiro que contem o documento localizado (traduzido). Se forneceu
ficheiros mestres múltiplos, pode fornecer múltiplos ficheiros localizados a
usar esta opção mais de uma vez.

=item B<-L>, B<--localized-charset>

Conjunto de carateres do ficheiro que contém o documento localizado.

=item B<-p>, B<--po>

Ficheiro onde o catálogo de mensagens deve ser escrito. Se não for dado, a
mensagem catálogo será escrito na saída predefinido.

=item B<-o>, B<--option>

Opção/ções adicional/ais para passar ao plugin de formato. Veja a
documentação de cada plugin para mais informações sobre as opções válidas e
os significados deles. Por exemplo, poderia passar '-o tablecells' para o
analisador AsciiDoc, enquanto o analisador de texto aceitaria '-o
tabs=split'.

=item B<-h>, B<--help>

Mostrar uma pequena mensagem de ajuda.

=item B<--help-format>

Lista os formatos de documentação compreendidos por po4a.

=item B<-V>, B<--version>

Mostrar a versão do script e sair.

=item B<-v>, B<--verbose>

Aumentar o detalhe do programa.

=item B<-d>, B<--debug>

Saída de alguma informação de depuração.

=item B<--msgid-bugs-address> I<e-mail@endereço>

Definir o endereço do relatório para msgid bugs. Por predefinição, os
ficheiros POT criados não têm campos Report-Msgid-bugs-To.

=item B<--copyright-holder> I<string>

Definir o titular dos direitos de autor no cabeçalho POT. O valor
predefinido é " Free Software Foundation, Inc."

=item B<--package-name> I<string>

Definir o nome do pacote para o cabeçalho POT. A predefinição é "PACKAGE".

=item B<--package-version> I<string>

Definir o nome do pacote para o cabeçalho POT. A predefinição é "VERSION".

=back

=head2 Converter a tradução manual para po4a

B<po4a-gettextize> tentará extrair o conteúdo de qualquer ficheiro de
tradução fornecido e utilizará esse conteúdo como msgstr no ficheiro PO
produzido. Este processo é muito frágil: a N-ésima cadeia do ficheiro
traduzido deve ser a tradução da N-ésima cadeia no original. Isto
naturalmente não vai funcionar a menos que ambos os ficheiros compartilhem a
mesma estrutura.

Internamente, cada analisador po4a reporta o tipo sintático de cada cadeia
extraída. Esta é a forma como a dessincronização é detetada durante a
gettext-ização.  Por exemplo, se os ficheiros têm a seguinte estrutura, é
muito improvável que a 4ª cadeia na tradução (do tipo 'capítulo') seja a
tradução da 4ª cadeia no original (do tipo 'parágrafo'). É provável que um
novo parágrafo tenha sido adicionado ao original ou que dois parágrafos
originais tenham sido fundidos na tradução.

    Original          Tradução

  capítulo            capítulo
    parágrafo           parágrafo
    parágrafo           parágrafo
    parágrafo         capítulo
  capítulo              parágrafo
    parágrafo           parágrafo

B<po4a-gettextize> diagnosticará verbalmente qualquer dessincronização de
estrutura detectada. Quando isso acontece, deve editar os ficheiros
manualmente (isso provavelmente requer que tenha algumas noções do idioma de
destino). Deve adicionar parágrafos falsos ou remover algum conteúdo de um
dos documentos (ou ambos) para corrigir as disparidades relatadas, até que a
estrutura dos dois documentos corresponda perfeitamente. Alguns truques são
dados na próxima secção.

Mesmo quando o documento é processado com sucesso, disparidades não
detetadas e erros silenciosos ainda são possíveis. É por isso que qualquer
tradução associada automaticamente pelo po4a-gettextize é marcada como
I<fuzzy> para exigir uma inspeção manual por seres humanos. É preciso
verificar se cada msgstr recuperado é realmente a tradução do msgid
associado e não a cadeia antes ou depois.

Como pode ver, a chave aqui é de ter exatamente a mesma estrutura no
documento traduzido e no original. O melhor é fazer a gettextização na
versão exata de F<master.doc> que foi usada para a tradução e atualizar o
ficheiro PO somente no ficheiro mestre mais recente depois que a
gettextização tiver êxito.

Se tiver a sorte de ter uma correspondência perfeita nas estruturas do
ficheiro, construir um ficheiro PO correto é uma questão de segundos. Caso
contrário, logo entenderá porque este processo tem um nome tão feio :) Mas
lembre-se que este trabalho grunhido é o preço a pagar para ter o conforto
de po4a depois. Uma vez convertido, a sincronização entre os documentos
mestres e as traduções será sempre totalmente automática.

Mesmo quando as coisas correm mal, a gettext-ização permanece muitas vezes
mais rápida do que a tradução de tudo de novo. Consegui fazer a
gettext-ização da tradução francesa existente de toda a documentação Perl
num dia, embora a estrutura de muitos documentos tenha sido
dessincronizada. Foram mais que dois megabytes de texto original (2 milhões
de caracteres): reiniciar a tradução a partir do zero teria exigido vários
meses de trabalho.

=head2 Dicas e truques para o processo de gettextização

A gettextização acaba assim que uma dessincronização é detetada. Em teoria,
provavelmente seria possível ressincronizar a gettextização posteriormente
nos documentos a usar, por exemplo, o mesmo algoritmo que o utilitário
L<diff(1)>. Mas uma intervenção manual ainda seria obrigatória para
corresponder aos elementos manualmente que não puderam ser correspondidos
automaticamente, a explicar por que a ressincronização automática ainda não
foi implementada (ainda?).

Quando isso acontece, tudo se resume novamente ao alinhamento das malditas
estruturas desses ficheiros através de edições manuais. B<po4a-gettextize> é
bastante verboso sobre o que deu errado quando isso acontece. Ele relata as
cadeias que não correspondem, as posições delas no texto e o tipo de cada
uma delas. Além disso, o ficheiro PO gerado até o momento é descartado como
F<gettextization.failed.po> para uma inspeção posterior.

Aqui estão alguns outros truques para ajudar-lo neste processo tedioso:

=over 

=item 

Remova todo o conteúdo adicional das traduções, como a secção que dá méritos
aos tradutores. Pode adicioná-lo novamente no po4a posteriormente, a usar um
adendo (consulte L<po4a(7)>).

=item 

Se precisar de editar os ficheiros para alinhar as estruturas deles, deve
preferir editar a tradução, se possível. De fato, se as alterações no
original forem muito intrusivas, a versão antiga e nova não corresponderão
durante a atualização do pedido e a tradução correspondente será despejada
de qualquer maneira. Mas não hesite em editar também o documento original,
se for necessário: o importante é obter um primeiro ficheiro PO para
começar.

=item 

Não hesite em eliminar qualquer conteúdo original que não exista na versão
traduzida. Este conteúdo será reintroduzido automaticamente posteriormente,
ao sincronizar o ficheiro PO com o documento.

=item 

Provavelmente deve informar o autor original de qualquer mudança estrutural
na tradução que pareça justificada. Questões no documento original devem ser
relatadas ao autor. Fixá-los na sua tradução apenas os corrige para uma
parte da comunidade. Além disso, é impossível fazê-lo quando se utiliza o
po4a ;)

=item 

Algumas vezes, o conteúdo do parágrafo não corresponde, mas tipos deles
não. Corrigir isso é até dependente do formato. No POD e man, frequentemente
vem do fato que um deles contém uma linha a começar com espaço em branco,
mas a outra não.  Naqueles formatos tal parágrafo não pode ser dimensionado
e, então, se torna um tipo diferente. Basta remover o espaço e está
terminado. Pode ser um erro de escrita no nome da marcação em XML.

Da mesma forma, dois parágrafos podem ser mesclados num POD quando a linha
separadora contém alguns espaços ou quando não há linha vazia entre a linha
B<=item> e o conteúdo do item.

=item 

Às vezes a mensagem de dessincronização parece estranha porque a tradução
está anexada ao parágrafo original errado. É o sinal de um problema não
detetado no início do processo. Procure o ponto real de dessincronização a
inspecionar F<gettextization.failed.po> e conserte o problema onde ele
realmente está.

=item 

Em alguns cenários infelizes, terá a sensação de que o po4a comeu algumas
partes do texto, seja o original ou a tradução. F<gettextization.failed.po>
indica que ambos os ficheiros corresponderam como esperado até o parágrafo
N. Mas uma tentativa (sem sucesso) é feita para corresponder o parágrafo N+1
no ficheiro original não com o parágrafo N+1 na tradução como deveria, mas
com o parágrafo N+2. Tal como se o parágrafo N+1 que se vê no documento
simplesmente desaparecesse do ficheiro durante o processo.

Esta situação infeliz acontece quando o mesmo parágrafo é repetido sobre
odocumento. Neste caso, não é criada uma nova entrada no ficheiro de PO, mas
uma nova referência é adicionada ao já existente em seu lugar.

Portanto, a situação anterior ocorre quando dois parágrafos semelhantes, mas
diferentes, são traduzidos exatamente da mesma maneira. Aparentemente, isso
removerá um parágrafo da tradução. Para corrigir o problema, basta alterar
ligeiramente uma das traduções no documento. Também pode preferir eliminar o
segundo parágrafo no documento original.

Ao contrário, se o mesmo parágrafo que aparece duas vezes no documento
original não for traduzido exatamente da mesma forma em ambos os locais,
terá a sensação de que um parágrafo do documento original simplesmente
desapareceu. Basta copiar a melhor tradução sobre a outra no documento
traduzido para resolver o problema.

=item 

Como nota final, não se surpreenda se a primeira sincronização do seu
ficheiro PO demorar muito tempo. Isso acontece porque a maioria do msgid do
ficheiro PO resultante da gettextização não corresponde exatamente a nenhum
elemento do ficheiro POT criado dos ficheiros mestre recentes. Isso força o
gettext a procurar o mais próximo a usar um algoritmo de proximidade de
cadeias caro.

Por exemplo, o primeiro B<po4a-updatepo> da tradução em francês da
documentação do Perl (ficheiro PO de 5.5 MB) levou cerca de 48 horas (sim,
dois dias), enquanto os subsequentes demoram apenas uma dúzia de segundos.

=back

=head1 VER TAMBÉM

L<po4a(1)>, L<po4a-normalize(1)>, L<po4a-translate(1)>, L<po4a-updatepo(1)>,
L<po4a(7)>.

=head1 AUTORES

 Denis Barbier <barbier@linuxfr.org>
 Nicolas François <nicolas.francois@centraliens.net>
 Martin Quinson (mquinson#debian.org)

=head1 DIREITOS DE AUTOR E LICENÇA

Direitos de Autor 2002-2020 por SPI, inc.

Este programa é software livre, pode redistribuí-lo e/ou modificá-lo sob os
termos da GPL (consulte o ficheiro CÓPIA).

