NOME

       po4a-gettextize - converte um arquivo original (e suas traduções) para um arquivo PO

SINOPSE

       po4a-gettextize -f fmt -m mestre.doc [-l XX.doc] -p XX.po

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

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 po4a(7) para uma
       introdução suave a este projeto.

       O script 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, 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 -l, 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.

OPÇÕES

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

       -m, --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.

       -M, --master-charset
           Conjunto de caracteres do arquivo contendo o documento para traduzir.

       -l, --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.

       -L, --localized-charset
           Conjunto de caracteres do arquivo contendo o documento localizado.

       -p, --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.

       -o, --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".

       -h, --help
           Mostra uma mensagem de ajuda.

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

           = item -k --keep-temps

           Mantém o mestre temporário e os arquivos POT localizados criados antes da mesclagem.
           Isso pode ser útil para entender por que esses arquivos são dessincronizados, levando
           a problemas de gettextização

       -V, --version
           Exibe a versão do script e sai.

       -v, --verbose
           Aumenta o nível de detalhamento do programa.

       -d, --debug
           Imprime algumas informações de depuração.

       --msgid-bugs-address 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.

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

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

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

   Convertendo uma tradução manual em po4a
       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

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

   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 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. 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 gettextization.failed.po para posterior inspeção.

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

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

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

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

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

       •   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 =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 detectado no início
           do processo. Procure o ponto de dessincronização real inspecionando
           gettextization.failed.po e corrija o problema onde ele realmente está.

       •   Em alguns casos, po4a adiciona um espaço no final das strings originais ou traduzidas.
           Isso ocorre porque cada string deve ser desduplicada durante o processo do gettextize.
           Imagine que uma string aparece várias vezes inalterada no original, mas é traduzida de
           maneira diferente, ou que diferentes parágrafos são traduzidos exatamente da mesma
           maneira.

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

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

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