PO4A-GETTEXTIZE(1p)

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