Provided by: po4a_0.66-1_all 
NOME
po4a-gettextize - converte um ficheiro original (e a tradução dele) para um ficheiro PO
SINOPSE
po4a-gettextize -f fmt -m master.doc [-l XX.doc] -p XX.po
(XX.po é a saída, todos os outros são entradas)
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 po4a(7) para uma introdução suave a este projeto.
O script 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, 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 -l, 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.
OPÇÕES
-f, --format
O formato da documentação que pretende processar. Use a opção --help-format para ver a lista de
formatos disponíveis.
-m, --master
Ficheiro que contem o documento principal para traduzir. Pode usar esta opção várias vezes se quiser
'gettextize' vários documentos.
-M, --master-charset
Conjunto de carateres do ficheiro que contém o documento a traduzir.
-l, --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.
-L, --localized-charset
Conjunto de carateres do ficheiro que contém o documento localizado.
-p, --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.
-o, --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'.
-h, --help
Mostrar uma pequena mensagem de ajuda.
--help-format
Lista os formatos de documentação compreendidos por po4a.
-V, --version
Mostrar a versão do script e sair.
-v, --verbose
Aumentar o detalhe do programa.
-d, --debug
Saída de alguma informação de depuração.
--msgid-bugs-address 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.
--copyright-holder string
Definir o titular dos direitos de autor no cabeçalho POT. O valor predefinido é " Free Software
Foundation, Inc."
--package-name string
Definir o nome do pacote para o cabeçalho POT. A predefinição é "PACKAGE".
--package-version string
Definir o nome do pacote para o cabeçalho POT. A predefinição é "VERSION".
Converter a tradução manual para po4a
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
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 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 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.
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 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. 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 gettextization.failed.po para uma
inspeção posterior.
Aqui estão alguns outros truques para ajudar-lo neste processo tedioso:
• 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 po4a(7)).
• 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.
• 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.
• 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 ;)
• 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 =item e o conteúdo do 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 gettextization.failed.po e conserte o problema onde ele realmente
está.
• 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. 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.
• 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 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.
VER TAMBÉM
po4a(1), po4a-normalize(1), po4a-translate(1), po4a-updatepo(1), po4a(7).
AUTORES
Denis Barbier <barbier@linuxfr.org>
Nicolas Francois <nicolas.francois@centraliens.net>
Martin Quinson (mquinson#debian.org)
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).
Ferramentas Po4a 2022-01-02 PO4A-GETTEXTIZE(1p)