
        *****************************************************
        *           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 arquivo original (e suas traduções) para um
arquivo PO

=head1 SINOPSE

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

(I<XX.po> é a saída, e todo o resto é entrada)

=head1 DESCRIÇÃO

po4a (PO for anything) facilita a manutenção de tradução da documentação
usando as ferramentas clássicas do gettext. A principal característica 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> está encarregado da conversão de arquivos de
documentação para arquivos PO. Você só precisa configurar o seu projeto de
tradução com o po4a, nunca depois.

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

Se o documento mestre possui caracteres não-ASCII, o novo arquivo PO gerado
vai estar in UTF-8. Do contrário (se o documento mestre estiver
completamente em ASCII), o PO gerado vai usar a codificação do documento de
entrada traduzido, ou UTF-8 se nenhum documento traduzido for fornecido.

=head1 OPÇÕES

=over 4

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

Formato da documentação que você quer manipular. Use a opção
B<--help-format> para ver a lista de formatos disponíveis.

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

Arquivo contendo o documento mestre para traduzir. Você pode usar esta opção
múltiplas vezes, se você quiser usar gettextize em múltiplos documentos.

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

Conjunto de caracteres do arquivo contendo o documento para traduzir.

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

Arquivo contendo o documento localizado (traduzido). Se você forneceu
múltiplos arquivos mestre, você pode desejar fornecer múltiplos arquivos
localizados usando esta opção mais de uma vez.

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

Conjunto de caracteres do arquivo contendo o documento localizado.

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

Arquivo para o qual a mensagem deve ser escrita. Se não fornecido, o
catálogo de mensagens será escrito para a saída padrão.

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

Opções extras para passar o plug-in de formato. Veja a documentação de cada
plug-in para mais informações sobre as opções válidas e seus
significados. Por exemplo, você poderia passar "-o tablecells" para o
analisador AsciiDoc, enquanto o analisador de texto aceitaria "-o
tabs=split".

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

Mostra uma mensagem de ajuda.

=item B<--help-format>

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

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

Exibe a versão do script e sai.

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

Aumenta o nível de detalhamento do programa.

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

Imprime algumas informações de depuração.

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

Define o endereço para relatórios de erros em msgids. Por padrão, os
arquivos POT criados possuem nenhum campo Report-Msgid-Bugs-To.

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

Define o detentor do copyright no cabeçalho do POT. O valor padrão é "Free
Software Foundation, Inc."

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

Define o nome do pacote para o cabeçalho do POT. O padrão é "PACKAGE".

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

Define a versão do pacote do cabeçalho do POT. O padrão é "VERSION".

=back

=head2 Convertendo uma tradução manual em po4a

B<po4a-gettextize> vai tentar extrair o conteúdo de qualquer arquivo PO
fornecido, e usar este conteúdo como msgstr no arquivo PO produzido. Esteja
avisado que este processo é muito frágil: a enésima string do arquivo
traduzido deve ser a tradução da enésima string do original. Isso
naturalmente não vai funcionar a menos que ambos arquivos compartilhem
exatamente a mesma estrutura.

Internamente, cada analisador po4a relata o tipo sintático de cada sequência
extraída. É assim que a dessincronização é detectada durante a
gettextization. Por exemplo, se os arquivos tiverem a seguinte estrutura, é
muito improvável que a quarta string na tradução (do tipo "chapter") seja a
tradução da quarta string no original (do tipo "paragraph"). É mais provável
que um novo parágrafo tenha sido adicionado ao original ou que dois
parágrafos originais tenham sido mesclados 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, você deve editar manualmente os
arquivos (isso provavelmente requer que você tenha algumas noções do idioma
de destino). Você 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 seção.

Mesmo quando o documento é processado com sucesso, disparidades não
detectadas 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 string antes ou depois.

Como você pode ver, a chave aqui é 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
arquivo PO somente no arquivo mestre mais recente depois que a gettextização
tiver êxito.

Se você tiver a sorte de ter uma correspondência perfeita nas estruturas de
arquivos, criar um arquivo PO correto é uma questão de segundos. Caso
contrário, você logo entenderá por que esse processo tem um nome tão feio :)
Mas lembre-se de que esse trabalho pesado é o preço a pagar para obter o
conforto de po4a posteriormente. Uma vez convertida, a sincronização entre
documentos mestre e traduções será sempre totalmente automática.

Mesmo quando as coisas dão errado, a gettextização geralmente é mais rápida
que traduzir tudo novamente. Eu consegui gettextizar a tradução para francês
existente de toda a documentação do Perl em um dia, ainda que estrutura de
muitos documentos estivessem dessincronizados. Isso foi mais de dois
megabytes que o texto original (2 milhões de caracteres): reiniciar a
tradução do zero teria exibido vários meses de trabalho.

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

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

Quando isso acontece, todo o jogo se resume ao alinhamento das estruturas
destes malditos arquivos de novo através de edição
manual. B<po4a-gettextize> é bastante detalhado sobre o que correu mal
quando isso acontece. Ele relata as strings que não correspondem, suas
posições no texto, e o tipo de cada um deles. Além disso, o arquivo PO
gerados até o momento é despejado como F<gettextization.failed.po> para
posterior inspeção.

Aqui estão alguns outros truques para ajudar você neste processo tedioso:

=over 

=item 

Remova todo o conteúdo extra das traduções, como a seção que dá créditos aos
tradutores. Você pode adicioná-lo novamente no po4a posteriormente, usando
um adendo (consulte L<po4a(7)>).

=item 

Se precisar editar os arquivos para alinhar suas estruturas, você deve
preferir editar a tradução, se possível. De fato, se as alterações no
original forem muito intrusivas, as versões 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 necessário: o importante é obter um primeiro arquivo 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 arquivo PO com o documento.

=item 

Você provavelmente deve informar o autor original de qualquer alteração
estrutural na tradução que pareça justificada. Problemas no documento
original devem ser relatadas ao autor. Corrigi-los na sua tradução os
corrige apenas para uma parte da comunidade. Além disso, é impossível fazer
isso ao usar po4a ;)

=item 

Algumas vezes, o conteúdo do parágrafo não corresponde, mas não os seus
tipos. Corrigir isso é até dependente do formato. No POD e man,
frequentemente ele vem do fato que um deles contém uma linha começando com
espaço em branco, enquanto 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 no 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
detectado no início do processo. Procure o ponto de dessincronização real
inspecionando F<gettextization.failed.po> e corrija o problema onde ele
realmente está.

=item 

Em algumas situações infelizes, você terá a sensação de que algumas partes
do texto po4a, tanto o original quanto a
tradução. F<gettextization.failed.po> indica que os dois arquivos
corresponderam conforme o esperado até o parágrafo N. Mas, então, é feita
uma tentativa (sem êxito) de corresponder ao parágrafo N+1 no arquivo
original e não ao parágrafo N+1 em a tradução como deveria, mas com o
parágrafo N+2. Como se o parágrafo N+1 que você vê no documento simplesmente
desaparecesse do arquivo durante o processo.

Essa situação infeliz acontece quando o mesmo parágrafo é repetido no
documento. Nesse caso, nenhuma nova entrada é criada no arquivo PO, mas uma
nova referência é adicionada ao já existente.

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. Você também pode preferir
eliminar o segundo parágrafo no documento original.

Pelo contrário, se o mesmo parágrafo que aparece duas vezes no documento
original não for traduzido exatamente da mesma maneira nos dois locais, você
sentirá que um parágrafo do documento original desapareceu. Basta copiar a
melhor tradução sobre a outra no documento traduzido para corrigir o
problema.

=item 

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

Por exemplo, o primeiro B<po4a-updatepo> da tradução em francês da
documentação do Perl (arquivo 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 VEJA 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 COPYRIGHT E LICENÇA

Copyright 2002-2020 por SPI, inc.

Esse programa é um software livre; você pode redistribuí-lo e/ou modificá-lo
sob os termos da GPL (veja o arquivo COPYING).

