
        *****************************************************
        *           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 RESUMO

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, 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> ajuda a converter as suas traduções
anteriormente existentes num fluxo de trabalho baseado em po4a. Isto só deve
ser feito uma vez para gravar uma tradução existente ao converter para po4a,
não numa base regular após a conversão do seu projeto. Este processo tedioso
é explicado em pormenores na Secção 'Convertendo uma tradução manual em
po4a' abaixo.

Deve fornecer um ficheiro mestre (por exemplo, a fonte em inglês) e um
ficheiro traduzido existente (por exemplo, uma tentativa de tradução
anterior sem po4a). Se fornecer mais que um mestre ou ficheiros de tradução,
eles serão usados em sequência, mas pode ser mais fácil gettextizar cada
página ou capítulo separadamente e, em seguida, usar B<msgmerge> para fundir
todos os ficheiros PO produzidos. Como preferir.

Se o documento mestre possui caracteres não-ASCII, o novo ficheiro PO gerado
vai estar in UTF-8. Se o documento mestre estiver completamente em ASCII, o
PO gerado vai usar a codificação do documento de entrada 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 caracteres 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 caracteres 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á escrita na saída standard.

=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<-k> B<--keep-temps>

Mantém o mestre temporário e os ficheiros POT localizados criados antes da
fusão. Isto pode servir para entender por que esses ficheiros são
dessincronizados, o que leva a problemas de gettextização.

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

Mostrar a versão do script e sai.

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

Aumenta os detalhes do programa.

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

Produz alguma informação de depuração.

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

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

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

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

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

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

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

Define a versão do pacote para o cabeçalho POT. A predefinição é "VERSION".

=back

=head2 Converter a tradução manual para po4a

B<po4a-gettextize> sincroniza os ficheiros mestres e localizados para
extrair seu conteúdo num ficheiro PO. O conteúdo do ficheiro mestre fornece
o B<msgid> enquanto o conteúdo do ficheiro localizado fornece o
B<msgstr>. Este processo é um tanto frágil: supõe-se que a enésima cadeia do
ficheiro traduzido seja a tradução da enésima cadeia no original.

A gettextização funciona melhor se conseguir recuperar a versão exata do
documento original que foi usado para a tradução. Mesmo assim, pode precisar
mexer com ficheiros mestres e localizados para alinhar a sua estrutura se
foi alterado pelo tradutor original, então é aconselhado trabalhar em cópias
de ficheiros.

Internamente, cada analisador do po4a relata o tipo sintático de cada cadeia
extraída. É assim que a dessincronização é detetada durante a
gettextização. No exemplo mostrado abaixo, é muito improvável que a quarta
cadeia na tradução (do tipo "chapter") seja a tradução da quarta cadeia 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
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> irá diagnosticar detalhadamente qualquer dessincronização
de estrutura. Quando isto acontece, deve editar manualmente os ficheiros
para adicionar parágrafos falsos ou remover algum conteúdo aqui e ali, até
que a estrutura dos dois ficheiros corresponda perfeitamente. Alguns truques
são fornecidos abaixo para salvar o máximo da tradução existente ao fazer
isto.

Se tiver a sorte de ter uma correspondência perfeita de primeira nas
estruturas de ficheiro prontas, construir um ficheiro PO correto é uma
questão de segundos. Caso contrário, logo perceberá por que este processo
tem um nome tão feio :) Mesmo assim, a gettextização geralmente permanece
mais rápida do que traduzir tudo novamente. Gettextifiquei a tradução
francesa de toda a documentação do Perl num dia, apesar dos problemas de
sincronização. Dada a quantidade de texto (2MB de texto original), reiniciar
a tradução sem primeiro gravar as traduções antigas teria exigido vários
meses de trabalho. Além disso, este trabalho pesado é o preço a pagar para
obter o conforto do po4a. Uma vez convertido, a sincronização entre
documentos mestre e traduções será sempre totalmente automática.

Após uma gettextização bem sucedida, os documentos produzidos devem ser
verificados manualmente para disparidades não detetadas e erros silenciosos,
como explicado abaixo.

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

A gettextização pára assim que uma dessincronização é detetada. Quando isto
acontece, deve editar os ficheiros o quanto for necessário para realinhar as
estruturas dos ficheiros. B<po4a-gettextize> é bastante detalhado quando as
coisas dão errado. Informa as cadeias que não correspondem, as suas posições
no texto e o tipo de cada uma delas. Além disso, o ficheiro PO gerado até
agora é descartado como F<gettextization.failed.po> para inspeção adicional.

Aqui estão alguns truques para ajudá-lo neste processo tedioso e garantir
que salve o máximo da tradução anterior:

=over

=item

Remova todo o conteúdo extra das traduções, como a secção que dá créditos
aos tradutores. Eles devem ser adicionados separadamente a B<po4a> como
adendos (veja L<po4a(7)>).

=item

Ao editar os ficheiros para alinhar as suas estruturas, prefira editar a
tradução se possível. Na verdade, se as alterações no original forem muito
intrusivas, as versões antiga e nova não serão correspondidas durante a
primeira execução do po4a após a gettextização (veja abaixo). Qualquer
tradução sem correspondência será descartada de qualquer maneira. Dito isto,
ainda deseja editar o documento original se for muito difícil fazer com que
a gettextização prossiga de outra forma, mesmo que isso signifique que um
parágrafo da tradução seja descartado. 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 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
fazê-lo ao usar po4a ;) Mas provavelmente desejará esperar até o final da
conversão para B<po4a> antes de alterar os ficheiros originais.

=item

Algumas vezes, o conteúdo do parágrafo corresponde, mas não os tipos
deles. 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á tudo bem. Pode também ser um erro de escrita no nome da
marcação em XML.

Da mesma forma, dois parágrafos podem ser fundidos juntamente 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 de dessincronização real
inspecionando o ficheiro F<gettextization.failed.po> que foi produzido e
corrija o problema onde ele realmente está.

=item

Outros problemas podem vir de cadeias duplicadas no original ou na
tradução. Cadeias duplicadas são mescladas em ficheiros PO, com duas
referências. Isto constitui uma dificuldade para o algoritmo de
gettextização, que é um emparelhamento simples entre os B<msgid>s dos
ficheiros mestre e localizado. No entanto, acredita-se que as versões
recentes do po4a lidam adequadamente com cadeias duplicadas, portanto deve
relatar qualquer problema remanescente que possa encontrar.

=back

=head2 Rever ficheiros produzidos pelo B<po4a-gettextize>

Qualquer ficheiro produzido pelo B<po4a-gettextize> deve ser revisado
manualmente, mesmo quando o script tiver concluído com sucesso. Deve dar uma
olhada no ficheiro PO, garantindo que B<msgid> e B<msgstr> realmente
correspondam. Ainda não é necessário garantir que a tradução esteja
perfeitamente correta, pois todas as entradas são marcadas como traduções
difusas de qualquer maneira. Só precisa verificar se há problemas de
correspondência óbvios, pois as traduções com correspondência incorreta
serão descartadas nas etapas subsequentes enquanto deseja gravá-las.

Felizmente, esta etapa não requer o domínio dos idiomas de destino, pois
deseja apenas reconhecer elementos semelhantes em cada B<msgid> e o seu
B<msgstr> correspondente. Como falante de francês, inglês e um pouco de
alemão, posso fazer isto pelo menos para todos os idiomas europeus, mesmo
que não consiga dizer uma palavra da maioria desses idiomas. Às vezes
consigo detetar problemas de correspondência em idiomas não latinos
observando o comprimento das cadeias, as estruturas das frases (a quantidade
de pontos de interrogação corresponde?) e outras pistas, mas prefiro quando
outra pessoa pode revisar estes idiomas.

Se detetar uma incompatibilidade, edite os ficheiros originais e de tradução
como se B<po4a-gettextize> tivesse relatado um erro e tente
novamente. Depois de ter um ficheiro PO decente para a sua tradução
anterior, faça salvaguarda dele até que o po4a funcione corretamente.

=head2 Executar B<po4a> pela primeira vez

A maneira mais fácil de configurar o po4a é escrever um ficheiro de
configuração B<po4a.conf> e usar o programa B<po4a> integrado
(B<po4a-updatepo> e B<po4a-translate> foram descontinuados). Por favor,
verifique a secção "ARQUIVO DE CONFIGURAÇÃO" na documentação do L<po4a(1)>
para mais pormenores.

Quando B<po4a> for executado pela primeira vez, a versão atual dos
documentos mestre será usada para atualizar os ficheiros PO contendo as
traduções antigas que recuperou através da gettextização. Isto pode levar
muito tempo, porque muitos dos B<msgid>s da gettextização não correspondem
exatamente aos elementos do ficheiro POT criado a partir dos ficheiros
mestres recentes. Isto força o gettext a procurar o mais próximo usando um
algoritmo custoso de proximidade de cadeias. Por exemplo, a primeira
execução da tradução francesa da documentação Perl (ficheiro PO de 5,5 MB)
levou cerca de 48 horas (sim, dois dias), enquanto as subsequentes levaram
apenas alguns segundos.

=head2 Mover as suas traduções para produção

Após esta primeira execução, os ficheiros PO estão prontos para serem
revisados pelos tradutores. Todas as entradas foram marcadas como
aproximadas (fuzzy) no ficheiro PO pelo B<po4a-gettextization>, forçando a
sua revisão cuidadosa antes do uso. Os tradutores devem verificar cada
entrada para verificar se a tradução recuperada realmente corresponde ao
texto original atual, atualizar a tradução conforme necessário e remover as
marcações de fuzzy.

Depois que marcadores de fuzzy suficientes forem removidos, B<po4a> começará
a gerar os ficheiros de tradução no disco e estará pronto para mover o seu
fluxo de trabalho de tradução para produção. Alguns projetos acham útil
contar com o weblate para coordenação entre tradutores e mantenedores, mas
isso está além do escopo do B<po4a>.

=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 DIREITOS DE AUTOR E LICENÇA

Copyright 2002-2023 por SPI, inc.

Este programa é um software livre; pode redistribuí-lo e/ou modificá-lo sob
os termos da GPL v2.0 ou posterior (veja o ficheiro COPYING).
