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.

           = item -k --keep-temps

           Keep the temporary master and localized POT files built before merging. This can be
           useful to understand why these files get desynchronized, leading to gettextization
           problems

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

       •   In some case, po4a adds a space at the end of either the original or the translated
           strings. This is because every string must be deduplicated during the gettextize
           process. Imagine that a string appearing several times unmodified in the original, but
           is translated in differing way, or that different paragraphs are translated in the
           exact same way.

           Without deduplication, such case would break the gettexization algorithm, as it is a
           simple one to one pairing between the msgids of both the master and the localized
           files. Since one of the PO files would miss an entry (that would be reported as
           duplicate, with two references), the pairing would fail.

           Since po4a uses the entry type ("title" or "plain paragraph", etc) to detect whether
           the parsing streams got desynchronized, similar issues could occur if two identical
           entries (same content but differing type) of the master file are translated in the
           exact same way in the localized file. po4a would detect a fake desyncronization in
           such case.

           In most cases, the extra space added by po4a to deduplicate the strings has no impact
           on the formatting. Strings are fuzzied anyway, and msgmerge will probably match the
           strings accordingly afterward.

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