PO4A-GETTEXTIZE.1P

Section: User Contributed Perl Documentation (1)
Updated: 2025-04-18
Index Return to Main Contents

NOME

po4a-gettextize - converte um ficheiro original (e a tradução dele) para um ficheiro PO

SINOPSE

po4a-gettextize -f fmt -m mestre.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 ajuda a converter as suas traduções anteriormente existentes num fluxo de trabalho baseado em po4a. Isto só deve ser feito uma vez para gravar uma tradução existente ao converter para po4a, não numa base regular após a conversão do seu projeto. Este processo tedioso é explicado em pormenores na Secção 'Convertendo uma tradução manual em po4a' abaixo.

Deve fornecer um ficheiro mestre (por exemplo, a fonte em inglês) e um ficheiro traduzido existente (por exemplo, uma tentativa de tradução anterior sem po4a). Se fornecer mais que um mestre ou ficheiros 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 ficheiros PO produzidos. Como preferir.

Se o documento mestre possui caracteres não-ASCII, o novo ficheiro 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: 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.
-k --keep-temps: Mantém o mestre temporário e os ficheiros POT localizados criados antes da mesclagem. Isto pode servir para entender por que esses ficheiros são dessincronizados, o que leva a problemas de gettextização.
-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 sincroniza os ficheiros mestres e localizados para extrair seu conteúdo num ficheiro PO. O conteúdo do ficheiro mestre fornece o msgid enquanto o conteúdo do ficheiro localizado fornece o msgstr. Este processo é um tanto frágil: supõe-se que a enésima cadeia do ficheiro traduzido seja a tradução da enésima cadeia no original.

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

Internamente, cada analisador do po4a relata o tipo sintático de cada cadeia extraída. É assim que a dessincronização é detetada durante a gettextização. No exemplo mostrado abaixo, é muito improvável que a quarta cadeia na tradução (do tipo "chapter") seja a tradução da quarta cadeia 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 isto acontece, deve editar manualmente os ficheiros para adicionar parágrafos falsos ou remover algum conteúdo aqui e ali, até que a estrutura dos dois ficheiros corresponda perfeitamente. Alguns truques são fornecidos abaixo para gravar ao máximo a tradução existente ao fazer isto.

Se tiver a sorte de ter uma correspondência perfeita de primeira nas estruturas de ficheiro prontas, construir um ficheiro PO correto é uma questão de segundos. Caso contrário, logo perceberá por que este processo tem um nome tão feio :) Mesmo assim, a gettextização geralmente permanece mais rápida do que traduzir tudo novamente. Gettextifiquei a tradução francesa de toda a documentação do Perl num dia, apesar dos problemas de sincronização. Dada a quantidade de texto (2MB de texto original), reiniciar a tradução sem primeiro gravar as traduções antigas teria exigido vários meses de trabalho. Além disso, este trabalho pesado é o preço a pagar para obter o conforto do po4a. Uma vez convertido, a sincronização entre documentos mestre e traduções será sempre totalmente automática.

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

Dicas e truques para o processo de gettextização

A gettextização para assim que uma dessincronização é detetada. Quando isto acontece, deve editar os ficheiros o quanto for necessário para realinhar as estruturas dos ficheiros. po4a-gettextize é bastante detalhado quando as coisas dão errado. Informa as cadeias que não correspondem, as suas posições no texto e o tipo de cada uma delas. Além disso, o ficheiro 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 grave ao máximo a tradução anterior:

•: Remova todo o conteúdo extra das traduções, como a secção que dá créditos aos tradutores. Eles devem ser adicionados separadamente a po4a como adendos (veja po4a(7)).
•: Ao editar os ficheiros para alinhar as 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, 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 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 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 fazê-lo ao usar po4a ;) Mas provavelmente desejará esperar até o final da conversão para po4a antes de alterar os ficheiros originais.
•: 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 de dessincronização real inspecionando o ficheiro gettextization.failed.po que foi produzido e corrija o problema onde ele realmente está.
•: Outros problemas podem vir de cadeias duplicadas no original ou na tradução. Cadeias duplicadas são mescladas em ficheiros PO, com duas referências. Isto constitui uma dificuldade para o algoritmo de gettextização, que é um emparelhamento simples entre os msgids dos ficheiros mestre e localizado. No entanto, acredita-se que as versões recentes do po4a lidam adequadamente com cadeias duplicadas, portanto deve relatar qualquer problema remanescente que possa encontrar.

Rever ficheiros produzidos pelo po4a-gettextize

Qualquer ficheiro produzido pelo po4a-gettextize deve ser revisado manualmente, mesmo quando o script tiver concluído com sucesso. Deve dar uma olhada no ficheiro 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. 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 deseja gravá-las.

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

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

Executar po4a pela primeira vez

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

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

Mover as suas traduções para produção

Após esta primeira execução, os ficheiros PO estão prontos para serem revisados pelos tradutores. Todas as entradas foram marcadas como aproximadas (fuzzy) no ficheiro PO pelo po4a-gettextization, forçando a 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 ficheiros de tradução no disco e estará pronto para mover o 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.

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

DIREITOS DE AUTOR E LICENÇA

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

Index

Converter a tradução manual para po4a
Rever ficheiros produzidos pelo po4a-gettextize
Executar po4a pela primeira vez
Mover as suas traduções para produção

VER TAMBÉM

AUTORES

DIREITOS DE AUTOR E LICENÇA

This document was created by using the manual pages.
Time: 09:22:08 GMT, April 18, 2025

po4av0.73