PO4A-GETTEXTIZE.1P(1)

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 ajuda você a converter suas traduções anteriormente existentes em um fluxo de trabalho baseado em po4a. Isso só deve ser feito uma vez para salvar uma tradução existente ao converter para po4a, não em uma base regular após a conversão de seu projeto. Este processo tedioso é explicado em detalhes na Seção 'Convertendo uma tradução manual em po4a' abaixo.

Você deve fornecer um arquivo mestre (por exemplo, a fonte em inglês) e um arquivo traduzido existente (por exemplo, uma tentativa de tradução anterior sem po4a). Se você fornecer mais de um mestre ou arquivos 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 msgmerge para mesclar todos os arquivos PO produzidos. Como preferir.

Se o documento mestre possui caracteres não-ASCII, o novo arquivo 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.

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.

-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 sincroniza os arquivos mestres e localizados para extrair seu conteúdo em um arquivo PO. O conteúdo do arquivo mestre fornece o msgid enquanto o conteúdo do arquivo localizado fornece o msgstr. Este processo é um tanto frágil: supõe-se que a enésima string do arquivo traduzido seja a tradução da enésima string no original.

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

Internamente, cada analisador do po4a relata o tipo sintático de cada string extraída. É assim que a dessincronização é detectada durante a gettextização. No exemplo mostrado abaixo, é 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á verbosamente qualquer dessincronização de estrutura. Quando isso acontece, você deve editar manualmente os arquivos para adicionar parágrafos falsos ou remover algum conteúdo aqui e ali, até que a estrutura dos dois arquivos corresponda perfeitamente. Alguns truques são fornecidos abaixo para salvar ao máximo a tradução existente ao fazer isso.

If you are lucky enough to have a perfect match in the file structures out of the box, building a correct PO file is a matter of seconds. Otherwise, you will soon understand why this process has such an ugly name :) Even so, gettextization often remains faster than translating everything again. I gettextized the French translation of the whole Perl documentation in one day despite the many synchronization issues. Given the amount of text (2MB of original text), restarting the translation without first salvaging the old translations would have required several months of work. In addition, this grunt work is the price to pay to get the comfort of po4a. Once converted, the synchronization between master documents and translations will always be fully automatic.

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

Dicas e truques para o processo de gettextização

A gettextização para assim que uma dessincronização é detectada. Quando isso acontece, você precisa editar os arquivos o quanto for necessário para realinhar as estruturas dos arquivos. po4a-gettextize é bastante detalhado quando as coisas dão errado. Informa as strings que não correspondem, suas posições no texto e o tipo de cada uma delas. Além disso, o arquivo PO gerado até agora é descartado como gettextization.failed.po para inspeção adicional.

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

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

•   Ao editar os arquivos para alinhar 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, você 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 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 ;) Mas você provavelmente desejará esperar até o final da conversão para po4a antes de alterar os arquivos originais.

•   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 o arquivo gettextization.failed.po que foi produzido e corrija o problema onde ele realmente está.

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

  Revisando arquivos produzidos pelo po4a-gettextize
Qualquer arquivo produzido pelo po4a-gettextize deve ser revisado manualmente, mesmo quando o script tiver concluído com sucesso. Você deve dar uma olhada no arquivo PO, garantindo que msgid e 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. Você 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 você deseja salvá-las.

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

Se você detectar uma incompatibilidade, edite os arquivos originais e de tradução como se po4a-gettextize tivesse relatado um erro e tente novamente. Depois de ter um arquivo PO decente para sua tradução anterior, faça backup dele até que o po4a funcione corretamente.

  Executando po4a pela primeira vez
A maneira mais fácil de configurar o po4a é escrever um arquivo de configuração po4a.conf e usar o programa po4a integrado (po4a-updatepo e po4a-translate foram descontinuados). Por favor, verifique a seção "ARQUIVO DE CONFIGURAÇÃO" na documentação do po4a(1) para mais detalhes.

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

  Movendo suas traduções para produção
Após esta primeira execução, os arquivos PO estão prontos para serem revisados pelos tradutores. Todas as entradas foram marcadas como aproximadas (fuzzy) no arquivo PO pelo po4a-gettextization, forçando 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, po4a começará a gerar os arquivos de tradução no disco e você estará pronto para mover 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 po4a.

VEJA TAMBÉM
po4a(1), po4a-normalize(1), po4a-translate(1), po4a-updatepo(1), po4a(7).

AUTORES
 Denis Barbier <barbier@linuxfr.org>
 Nicolas François <nicolas.francois@centraliens.net>
 Martin Quinson (mquinson#debian.org)

COPYRIGHT E LICENÇA
Copyright 2002-2023 por SPI, inc.

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