Provided by: po4a_0.52-1_all 
NOME
po4a - framework para traduzir documentação e outros materiais
Introdução
A missão do projeto po4a (em inglês, PO for anything) é facilitar as traduções (e o mais interessante, a
manutenção de traduções) usando ferramentas de gettext em áreas onde elas não eram esperadas, como
documentação.
Sumário
Esse documento é organizado da seguinte forma:
1 Por que eu deveria usar po4a? O que tem de bom nele?
Este capítulo introdutório explica a motivação do projeto e sua filosofia. Você deveria ler este
primeiro, se você está em processo de avaliação do po4a para suas próprias traduções.
2 Como usar po4a?
Este capítulo é um tipo de manual de referência, tentando responder as perguntas dos usuários e dar a
você um entendimento melhor do processo como um todo. Ele introduz como fazer coisas com po4a e serve
como uma introdução à documentação das ferramentas específicas.
COMO começar uma nova tradução?
COMO alterar a tradução de volta para um arquivo de documentação?
COMO atualizar uma tradução de po4a?
COMO converter uma tradução pré-existente para po4a?
COMO adicionar um texto extra às traduções (ex.: nome do tradutor)?
COMO fazer tudo isso em uma invocação de programa?
COMO personalizar o po4a?
3 Como ele funciona?
Este capítulo dá a você uma visão geral da parte interna do po4a, de forma que você pode se sentir
mais confiante para nos ajudar a manter e melhorá-lo. ele também pode ajudá-lo a entender o porquê de
ele não funcionar da forma que você esperava, e como resolver seus problemas.
4 FAQ
Este capítulo agrupa as perguntas frequentes (FAQ). Na verdade, a maioria das perguntas até agora
puderam ser formuladas dessa forma: "Porque ele é projetado dessa forma e não dessa outra?" Se você
pensa que po4a não é a resposta correta para tradução de documentação, você deveria considerar ler
esta seção. Se ele não responder suas perguntas, por favor entre em contato conosco na lista de
discussão <po4a-devel@lists.alioth.debian.org>. Nós adoramos feedback.
5 Notas específicas sobre módulos
Este capítulo apresenta as especificidades de cada módulo do ponto de vista do autor original e do
tradutor. Leia isso para aprender a sintaxe que você vai encontrar ao traduzir as coisas neste
módulo, ou as regras que você deveria ser no seu documento original para tornar a vida dos tradutores
mais fácil.
Na verdade, essa seção não é realmente parte desse documento. Ao invés disso, ela é colocada na
documentação de cada módulo. Isso ajuda a assegurar que a informação está atualizada mantendo a
documentação e o código juntos.
Por que eu deveria usar po4a? O que tem de bom nele?
Eu gosto da ideia de software de código aberto, tornando possível para todos acessar o software e seu
código fonte. Mas por ser francês, estou ciente de que a licença não é a única restrição à abertura do
software: um software livre não traduzido é inútil para aqueles que não sabem inglês e, então, nós ainda
temos mais trabalho para disponibilizar para realmente todo mundo por aí.
A percepção dessa situação aos atores do código do aberto tem melhorado drasticamente nos últimos tempos.
Nós, como tradutores, vencemos a primeira batalha e convencemos a todos a importância da tradução. Mas,
infelizmente, essa era uma parte fácil. Agora, nós temos que fazer o trabalho e realmente traduzir todas
essas coisas.
Na verdade, softwares de código aberto se beneficiam de um nível decente de tradução, graças a
maravilhosa suíte de ferramentas do gettext. Ele é capaz de extrair as strings para traduzir a partir do
programa, apresentar um formato uniforme para tradutores e, então, usar o resultado do seus trabalhos em
tempo de execução para exibir mensagens traduzidas para o usuário.
Mas a situação é um pouco diferente quando se trata de documentação. Com muita frequência, a documentação
traduzida não é visível o suficiente (não distribuída como uma parte do programa), apenas parcialmente,
ou não atualizada. Esta última situação é de longe a pior possível. Tradução desatualizada pode se tornar
pior do que nenhuma tradução para os usuários ao descrever comportamento antigo do programa, que não é
mais usado.
O problema para resolver
Tradução de documentação não é muito difícil em si. Textos são bem maiores do que as mensagens do
programa e, portanto, demoram mais para se alcançar, mas nenhuma habilidade técnica é realmente
necessária para isso. A parte difícil aparece quando você tem que manter o seu trabalho. A detecção de
quais partes mudaram e a necessidade de se manter atualizada é muito difícil, propensa a erro e muito
desagradável. Eu acho que isso explica o porquê de várias documentações por aí estão desatualizadas.
As respostas do po4a
Então, a função do po4a é tornar a tradução de documentação manutenível. A ideia é reusar a metodologia
do gettext para esse novo campo. Assim como no gettext, textos são extraídos de suas localizações
originais para estar presente em um formato uniforme para os tradutores. As ferramentas clássicas do
gettext os ajudam a atualizar seus trabalhos quando um novo lançamento do original surge. Mas para
diferenciar do modelo clássico do gettext, as traduções são, então, reinjetadas na estrutura do documento
original de forma que elas podem ser processadas e distribuídas igual como a versão em inglês.
Graças a isso, a descoberta de quais partes do documento foram alteradas e que precisam ser atualizadas
se torna mais fácil. Outra coisa boa é que as ferramentas vão fazer a maior parte do trabalho quando a
estrutura do documento original estiver fundamentalmente reorganizado e quando alguns capítulos tiverem
sido movidos, mesclados ou divididos. Ao extrair o texto para traduzir da estrutura do documento, ele
também afasta você da complexidade da formatação do texto e reduz suas chances de acabar com um documento
quebrado (mesmo que ele não previna completamente você de fazer isso).
Por favor, veja também o FAQ abaixo neste documento para uma lista mais completa de vantagens e
desvantagens desta abordagem.
Formatos suportados
Atualmente, essa abordagem tem sido implementada com sucesso em vários formatos de formatação de texto:
man
O bom e velho formato de páginas de manual, usado por tantos programas por aí. O suporte do po4a é muito
bem-vindo, considerando que esse formato é de certa forma difícil de usar e não exatamente amigável para
novatos. O módulo Locale::Po4a::Man(3pm) também possui suporte ao formato mdoc, usado pelas páginas de
manual do BSD (elas também são bens comuns no Linux).
pod
Esse é o formato da documentação online de Perl, ou Perl Online Documentation. A própria linguagem e
extensões são documentadas dessa forma, assim como a maioria dos scripts Perl existentes. Isso facilita a
manter a documentação ferto do real código embutindo-os no mesmo arquivo. Isso torna a vida dos
programadores mais fácil, mas infelizmente, não a do tradutor.
sgml
Mesmo se de certa forma tenha sido substituído nos dias de hoje pelo XML, esse formato ainda é usado com
certa frequência por documentos que são maiores do algumas telas. Ele permite que você faça livros
completos. Atualizar a tradução de documentos grandes pode se mostrar ser um verdadeiro pesadelo. diff se
mostra frequentemente inútil quando o texto original foi recuado depois da atualização. Por sorte, po4a
pode ajudar você nesse processo.
Atualmente, há suporte apenas ao DebianDoc e o DocBook DTD, mas a adição de suporte a um novo é realmente
fácil. É possível até mesmo usar po4a em um SGML DTD desconhecido sem alterar o código, desde que sejam
fornecidas as informações necessárias na linha de comando. Veja Locale::Po4a::Sgml(3pm) para mais
detalhes.
TeX / LaTeX
O formato LaTeX é um formato de documentação mais usado no mundo de software livre e para publicações. O
módulo Locale::Po4a::LaTeX(3pm) foi testado com a documentação do Python, um livro e algumas
apresentações.
texinfo
Toda a documentação do GNU é escrita neste formato (esse é até mesmo um dos requisitos para se tornar um
projeto GNU oficial). O suporte a Locale::Po4a::Texinfo(3pm) no po4a ainda está nas fases iniciais. Por
favor relate eventuais erros e requisição por recursos.
xml
O formato XML é um formato base para muitos formatos de documentação.
Atualmente, po4a possui suporte a DocBook DTD. Veja Locale::Po4a::Docbook(3pm) para mais detalhes.
outros
Po4a também pode manipular alguns formatos mais raros ou especializados, como a documentação de opções de
compilação dos kernels Linux 2.4+ ou diagramas produzidos pela ferramenta Dia. A adição de um novo
formato é normalmente muito fácil e a tarefa principal é fazer um analisador do seu formato alvo. Veja
Locale::Po4a::TransTractor(3pm) para mais informações sobre isso.
Formatos sem suporte
Infelizmente, po4a ainda não tem suporte a vários formatos de documentação.
Há uma grande quantidade de formatos que nós gostaríamos que po4a tivesse suporte, e não somente de
documentação. Realmente, nós miramos em acertar todos os "furos de mercado" deixados pelas ferramentas
clássicas do gettext. Isos envolve descrições de pacotes (deb e rpm), perguntas de scripts de instalação
de pacotes, changelogs de pacotes e todos formatos de arquivo especializados como cenários de jogos e
arquivos de recursos do wine.
Como usar po4a?
Este capítulo é um tipo de manual de referência, tentando responder as perguntas dos usuários e dar a
você um entendimento melhor do processo como um todo. Ele introduz como fazer coisas com po4a e serve
como uma introdução à documentação das ferramentas específicas.
Visão geral gráfica
O esquema a seguir dá uma visão geral do processo de tradução de documentação usando po4a. Não tenha medo
pela sua complexidade aparente, pois ela vem do fato de que todo o processo está representado aqui. Assim
que você tiver convertido seu projeto para po4a, apenas a parte da direita é relevante.
Note que mestre.doc é tido como um exemplo de documentação a ser traduzida e tradução.doc é o texto
tradução correspondente. O sufixo poderia ser .pod, .xml ou .sgml, dependendo do seu formato. Cada parte
da imagem será detalhada nas próximas seções.
mestre.doc
|
V
+<-----<----+<-----<-----<--------+------->-------->-------+
: | | :
{tradução} | { atualização de mestre.doc } :
: | | :
XX.doc | V V
(opcional) | mestre.doc ->-------->------>+
: | (novo) |
V V | |
[po4a-gettextize] doc.XX.po---->+ | |
| (velho) | | |
| ^ V V |
| | [po4a-updatepo] |
V | | V
tradução.pot ^ V |
| | doc.XX.po |
| | (incerto) |
{ tradução } | | |
| ^ V V
| | {edição manual} |
| | | |
V | V V
doc.XX.po --->---->+<---<-- doc.XX.po adendo mestre.doc
(inicial) (atualizado) (opcional) (atualizado)
: | | |
: V | |
+----->----->----->------> + | |
| | |
V V V
+------>-----+------<------+
|
V
[po4a-translate]
|
V
XX.doc
(atualizado)
Na parte da esquerda, a conversão de uma tradução não usando po4a para esse sistema é mostrada. No topo
da parte da direita, a ação do autor original está descrita (atualização da documentação). O meio da
parte da direita é onde as ações automáticas do po4a estão descritas. Os novos materiais são extraídos e
comparados com a tradução existente. Partes que não foram alteradas são encontradas e a tradução anterior
é usada. Partes que foram parcialmente modificadas também são conectadas à tradução anterior, mas com uma
marcação indicando que a tradução deve ser atualizada. A parte inferior da figura mostra como um
documento formatado é compilado.
Na verdade, como um tradutor, a única operação manual que você tem que fazer é a parte marcada {edição
manual}. Sim, me desculpe, mas o po4a ajuda você a traduzir. Ele não traduz para você...
COMO começar uma nova tradução?
Esta seção apresenta as etapas necessárias para começar uma nova tradução com po4a. Os refinamentos
envolvidos na conversão de um projeto existente para esse sistema estão detalhados na seção relevante.
Para começar uma nova tradução usando po4a, você tem que seguir as etapas a seguir:
- Extraia o texto que você tem que ser traduzido do documento <mestre.doc> original para um arquivo do
novo modelo de tradução <tradução.pot> (o formato gettext). Para isso, use o programa po4a-gettextize
desta forma:
$ po4a-gettextize -f <formato> -m <mestre.doc> -p <tradução.pot>
<formato> normalmente é o formato usado no documento mestre.doc. Como esperado, a saída vai para
tradução.pot. Por favor, veja po4a-gettextize(1) para mais detalhes sobre as opções existentes.
- Realmente traduza o que deveria ser traduzido. Para isso, você tem que renomear o arquivo POT para, por
exemplo, doc.XX.po (sendo XX o código ISO 639-1 do idioma para o qual você está traduzindo, ex.: fr
para francês) e edite o arquivo resultante. Normalmente, é uma boa ideia não nomear o arquivo XX.po
para evitar confusão com a tradução das mensagens do programa, mas a decisão é sua. Não se esqueça de
atualizar os cabeçalhos dos arquivos PO, pois eles são importantes.
A tradução pode ser feita ser feita usando o modo PO do Emacs ou do, Lokalize (baseado no KDE),
Gtranslator (baseado no GNOME) ou qualquer outro programa que você preferir usar para isso (ex.:
Virtaal).
Se você prefere aprender mais sobre isso, você definitivamente precisa ver a documentação do gettext,
disponível no pacote gettext-doc.
COMO alterar a tradução de volta para um arquivo de documentação?
Assim que você finalizar com a tradução, você quer pegar a documentação traduzida e distribuí-la para os
usuários junto com o original. Para isso, use o programa po4a-translate(1) dessa forma (sendo XX o código
do idioma):
$ po4a-translate -f <formato> -m <mestre.doc> -p <doc.XX.po> -l <XX.doc>
Como antes, <formato> é o formato usado no documento mestre.doc. Mas dessa vez, o arquivo PO fornecido
com a opção -p é parte da entrada. Essa é a sua tradução. A saída vai para XX.doc.
Por favor, veja po4a-translate(1) para mais detalhes.
COMO atualizar uma tradução de po4a?
Para atualizar sua tradução quando o arquivo original mestre.doc foi alterado, use o programa
po4a-updatepo(1) dessa forma:
$ po4a-updatepo -f <formato> -m <novo_mestre.doc> -p <doc_antigo.XX.po>
(Por favor, veja po4a-updatepo(1) para mais detalhes)
Normalmente, o novo parágrafo no documento não será traduzido magicamente no arquivo PO com esta operação
e você vai precisar atualizar o arquivo PO manualmente. Da mesma forma, você pode ter que retrabalhar a
tradução por parágrafos que foram um pouco modificados. Para certificar-se de que você vai perder nenhum
deles, eles são marcados como "fuzzy" (aproximado) durante o processo e você tem que remover essa
marcação antes que a tradução possa ser usada por po4a-translate. como a tradução inicial, o melhor a se
fazer é usar aqui o seu editor de PO favorito.
Assim que seu arquivo PO estiver atualizado novamente, sem qualquer string não traduzida ou incerta, você
pode gerar um arquivo de documentação traduzida, como explicado na seção anterior.
COMO converter uma tradução pré-existente para po4a?
Geralmente, você costumava traduzir manualmente a documentação até que uma grande reorganização do
mestre.doc original aconteceu. Então após algumas tentativas desagradáveis com diff ou ferramentas
similares, você quer converter para po4a. Mas, é claro, você não quer perder sua tradução existente no
processo. Não se preocupe, esse caso também é manipulado pelas ferramentas do po4a e é chamado de
gettextização.
A chave aqui é ter a mesma estrutura no documento traduzido e no original, de forma que as ferramentas
possam conferir o conteúdo corretamente.
Se você tiver sorte (isso é, se as estruturas de ambos documentos corresponderem perfeitamente), isso vai
funcionar de forma transparente e você vai estar pronto em poucos segundos. Do contrário, você pode
entender o porquê desse processo ter um nome tão feito, e é bom que você esteja preparado para um
trabalho suado aqui. Em qualquer caso, lembre-se de que o preço a se pagar pelo conforto do po4a
posteriormente. E o lado bom é que você só tem que fazer isso uma vez.
Eu não consigo enfatizar isso muito. Para facilitar o processo, é, então, importante que você localize a
versão exata que foi usada para a tradução. A melhor situação é quando você anotou a revisão no sistema
de controle de versão usada para a tradução e não modificou o seu processo de tradução de forma que você
possa usá-lo.
Vai funcionar melhor quando você usar um texto original atualizado com a tradução antiga. Ainda é
possível, mas é mais difícil e realmente deveria ser evitado, se possível. Na verdade, creio que se você
não conseguir localizar o texto original novamente, a melhor solução é localizar alguém para fazer a
gettextização para você (mas, por favor, não eu ;).
Talvez eu esteja sendo muito dramático. Mesmo quando as coisas dão errado, ainda há formas mais rápidas
do que traduzir tudo de novo. Eu consegui gettextizar a tradução para francês existente da documentação
do Perl em um dia, mesmo as coisas tenham dado errado. Aquilo foi mais do que 2 megabytes de texto, e uma
nova tradução demoraria meses ou mais.
Deixe-me explicar a base do procedimento primeiro e eu vou voltar com dicas para concluir quando o
processo dá errado. Para facilitar a compreensão, vamos usar o exemplo acima novamente.
Assim que você tiver mestre.doc antigo novamente, o qual corresponde com a tradução XX.doc, a
gettextização pode ser feita diretamente ao arquivo PO doc.XX.po sem tradução manual do arquivo
tradução.pot:
$ po4a-gettextize -f <formato> -m <mestre antigo.doc> -l <XX.doc> -p <doc.XX.po>
Quando você tiver sorte, é só isso. Você converteu sua tradução antiga para po4a e pode começar a tarefa
de atualização agora mesmo. Basta seguir o procedimento explicado algumas seções atrás para sincronizar
seu arquivo PO com o documento original mais novo e atualizar a tradução.
Por favor, note que mesmo quando as coisas parecem funcionar adequadamente, ainda há espaços para erros
neste processo. A questão é que po4a não é capaz de entender o texto para certificar-se de que a tradução
corresponde com o original. É por isso que todas as strings serão marcadas como "fuzzy" no processo. Você
deveria verificar cada uma cuidadosamente antes de remover essas marcações.
Com frequência as estruturas do documento não correspondem exatamente, evitando po4a-gettextize de fazer
seu trabalho adequadamente. A essa altura, o jogo em questão é sobre editar os arquivos para fazer com
que suas estruturas correspondam.
Pode ser uma ajuda ler a seção Gettextização: como ela funciona? abaixo. Entender o processo interno
pode ajudar você a fazer o seu trabalho. O lado positivo é que po4a-gettextize é bem detalhista sobre o
que deu errado quando isso acontece. Primeiro, ele indica onde nos documentos há discrepância na
estrutura. Você vai descobrir as strings que não correspondem, suas posições no texto e o tipo de cada
uma delas. Mais ainda, o arquivo PO gerado será despejado para gettextization.failed.po.
- Remove todas as partes extras das traduções, como as seções em que você informa o nome do tradutor e
agradeço a todas as pessoas que contribuíram para a tradução. Adendos, que será descrito na próxima
seção, vai permitir que você adicione-os posteriormente.
- Não hesite em editar ambos o original e a tradução. A coisa mais importante é obter o arquivo PO.
Você poderá atualizá-lo posteriormente. Isto posto, a edição da tradução deveria ser preferida quando
pode-se fazer as duas coisas, pois ela facilita quando a gettextização tiver concluída.
- Se necessário, mate algumas partes do original se elas não tiverem sido traduzidas; Ao se sincronizar
do PO com o documento posteriormente, elas vão voltar por conta própria.
- Se você alterou a estrutura um pouco (para mesclar dois parágrafos ou dividir outro), desfaça aquelas
alterações. Se há problemas no original, você deveria informar o autor original. A correção deles na
sua tradução resolve somente uma parte da comunidade. E além disso, isso é impossível quando se está
usando po4a ;)
- Algumas vezes, o conteúdo do parágrafo não corresponde, mas seus tipos não. Corrigir isso é até
dependente do formato. No POD e man, frequentemente ele vem do fato que um dos dois contém uma linha
começando 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.
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.
- Algumas vezes, há uma dessincronização entre os arquivos e a tradução é anexada ao parágrafo original
incorreto. Isso é um sinal de que o problema real é de antes nestes arquivos. Verifique
gettextization.failed.po para ver quando começa a dessincronização e corrija-a lá.
- Algumas vezes, você tem a sensação de que po4a comeu parte do texto, seja do original seja da
tradução. gettextization.failed.po indica que ambos correspondem gentilmente e, então, a
gettextização falha porque ele tentou corresponder um parágrafo com outro após (ou antes) do correto,
como se o correto tivesse desaparecido. Xingue po4a como eu fiz quando isso aconteceu comigo.
Generosamente.
Essa situação infeliz acontece quando o mesmo parágrafo é repetido no documento. Nesse caso, nenhuma
nova entrada é criada no arquivo PO, mas uma nova referência é adicionada ao já existente.
Então, quando o mesmo parágrafo aparece duas vezes no original, mas ambos não estão traduzidos da
mesma forma cada vez, você terá a sensação de que um parágrafo do original desapareceu. Basta matar a
nova tradução. Se, ao invés disso, você preferir matar a primeira tradução quando a segunda estiver
melhor, substitua a primeira pela segunda.
Do contrário, se dois parágrafos similares, mas diferentes, foram traduzidos na mesma forma, você
terá a sensação de que um parágrafo da tradução desapareceu. Uma solução é adicionar a estúpida da
string ao parágrafo original (do tipo "Sou diferente"). Não tenha medo, aquelas coisas vão
desaparecer durante a sincronização e quando o texto adicionar for curto o suficiente, gettext vai
corresponder sua tradução ao texto existente (marcando-o como incerto, mas você não se importa se
considerar que todas strings estarão marcadas como incertas após a gettextização).
Com muita esperança, essas dicas vão ajudar você a fazer sua gettextização funcionar e obter seu precioso
arquivo PO. Agora você está pronto para sincronizar seu arquivo e começar sua tradução. Por favor, note
que em um texto largo, pode acontecer de a primeira sincronização demorar um bom tempo.
Por exemplo, o primeiro po4a-updatepo da tradução para francês da documentação do Perl (arquivo PO de 5.5
MB) levou cerca de dois dias completos em um computador G5 de 1GHz. Sim, 48 horas. Mas os subsequentes
demora apenas algumas dezenas de segundos no meu laptop antigo. Isso acontece porque na primeira vez, a
maioria do msgid do arquivo PO não corresponde a qualquer dos arquivos POT. Isso força o gettext a
pesquisar pelos mais próximos usando um custoso algoritmo de proximidade de strings.
COMO adicionar um texto extra às traduções (ex.: nome do tradutor)?
Por causa da abordagem do gettext, fazer isso se torna mais difícil em po4a do que era quando simples
edição de um novo arquivo junto com o original, Mas isso ainda é possível, graças aos famosos adendos.
Pode ajudar a compreensão considerar os adendos como uma espécie de patches aplicados ao documento
localizado após processamento. Eles são meio que diferentes dos patches comuns (eles têm apenas uma linha
de contexto, o que pode embutir expressões regulares de Perl, e podem adicionar apenas novos textos sem
remover algum), mas as funcionalidades são as mesmas.
Seu objetivo é permitir que o tradutor adicione conteúdo extra ao documento que não está traduzido a
partir do documento original. O uso mais comum é adicionar uma seção sobre a tradução em si, listando
contribuidores e explicando como relatar um erro da tradução.
Um adendo deve ser fornecido em um arquivo separado. A primeira linha constitui em um cabeçalho indicando
onde no documento produzido ele deveria ser colocado. O resto do arquivo de adendo será adicionado
literalmente à posição determinada do documento resultante.
O cabeçalho possui uma sintaxe bem rígida: ele deve começar com a string PO4A-HEADER:, seguida por um uma
lista separada por ponto-e-vírgula (;) de campos chave=valor. Espaços em branco SÃO importantes. Note que
se você não puder usar o caractere ponto-e-vírgula (;) no valor e colocar entre aspas não vai ajudar.
Novamente, pode soar assustador, mas os exemplos dados abaixo deve ajudar você a descobrir como escrever
a linha de cabeçalho que você precisa. Para ilustrar a discussão, suponha que nós queremos adicionar uma
seção chamada "Sobre esta tradução" após a de "Sobre este documento".
Arqui estão as chaves de cabeçalho possíveis:
position (obrigatório)
uma regexp (expressão regular) Perl. O adendo será colocado perto da linha correspondendo a esta
regexp. Note que estamos falando do documento traduzido aqui, e não do original. Se mais do que uma
linha corresponder a esta expressão (ou nenhuma), a adição vai falhar. É realmente melhor relatar um
erro do que inserir um adendo na localização incorreta.
Esta linha é chamada de ponto de posição a seguir. O ponto onde o adendo é adicionado é chamado de
ponto de inserção. Esses dois pontos estão perto um do outro, mas não são iguais. Por exemplo, se
você quer inserir uma nova seção, é fácil colocar o ponto de posição no título da seção precedente e
explicar para o po4a onde a seção termina (lembre-se de que ponto de posição é dado por uma regexp
que deveria corresponder a uma única linha).
A localização do ponto de inserção no que se refere ao ponto de posição é controlada pelos campos
mode, beginboundary e endboundary, como explicado abaixo.
No nosso caso, não teríamos:
position=<title>Sobre esse documento</title>
mode (obrigatório)
Pode ser tanto a string antes quanto depois, especificando a posição do adendo, relativa ao ponto de
posição. Caso antes seja fornecida, o ponto de inserção será colocado exatamente antes do ponto de
posição. O comportamento depois é detalhado abaixo.
Já que nós queremos que a nova seção seja colocada abaixo daquela que estamos correspondendo, nós
temos:
mode=after
beginboundary (usado somente quando mode=after e obrigatório neste caso)
endboundary (idem)
regexp correspondendo ao fim da seção após a qual o adendo entra.
Quando mode=after, o ponto de inserção está após o ponto de posição, mas não diretamente após! É
colocado no final da seção começando com o ponto de posição, isto é, após ou antes da linha ter
correspondido ao argumento ???boundary, dependendo de se você usou beginboundary ou endboundary.
No nosso caso, nós podemos escolher indicar o fim da seção que nós correspondemos ao adicionar:
endboundary=</section>
ou indicar o começo da próxima seção ao indicar:
beginboundary=<section>
Em ambos casos, nosso adendo vai ser localizado após </section> e antes de <section>. O primeiro é
melhor já que ele vai funcionar mesmo se o documento for reorganizado.
Ambas formas existem porque os formatos de documentação são diferentes. em alguns deles, há uma forma
de marcar o fim da seção (como o </section> que nós usamos), enquanto alguns outros não marcam
explicitamente o fim da seção (como no man). No primeiro caso, nós queremos fazer um boundary
correspondendo ao fim da seção, de forma que o ponto de inserção venha após este. No segundo caso,
nós queremos fazer um boundary correspondendo o começo da próxima seção, de forma que o ponto de
inserção venha logo antes dele.
Isso pode parecer obscuro, mas esperamos que os próximos exemplos sejam mais claros.
Para resumir o exemplo usado até agora, para adicionar uma seção chamada "Sobre esta tradução" após a de
"Sobre esta documentação" em um documento SGML, você pode usar qualquer uma das linhas de cabeçalho:
PO4A-HEADER: mode=after; position=Sobre este documento; endboundary=</section>
PO4A-HEADER: mode=after; position=Sobre este documento; beginboundary=<section>
Se você quiser adicionar alguma coisa após a seção nroff a seguir:
.SH "AUTHORS"
você deveria colocar uma position correspondendo a esta linha e um beginboundary correspondendo ao
começo da próxima seção (isto é,, ^\.SH). O adendo vai, então, ser adicionado após o ponto de posição e
imediatamente antes da primeira linha correspondendo ao beginboundary. Isso é dizer:
PO4A-HEADER:mode=after;position=AUTHORS;beginboundary=\.SH
Se você quiser adicionar alguma coisa a uma seção (como após "Copyright Grande Cara") ao invés de
adicionar uma seção inteira, forneça um position correspondendo a esta linha e forneça um beginboundary
correspondendo a qualquer linha.
PO4A-HEADER:mode=after;position=Copyright Grande Cara, 2004;beginboundary=^
Se você quiser adicionar alguma coisa ao final do documento, forneça um position correspondendo a
qualquer linha do seu documento (mas apenas uma linha. Po4a não vai proceder se ela não for única), e
forneça um endboundary correspondendo a nada. Não use strings simples aqui como "EOF", e sim prefira
aquelas que possuem menos chance de estar no seu documento.
PO4A-HEADER:mode=after;position=<title>Sobre</title>;beginboundary=FakePo4aBoundary
Em qualquer caso, lembre-se que essas são regexp. Por exemplo, se você quiser corresponder o fim de uma
seção de nroff finalizando com a linha
.fi
não use .fi como endboundary porque ele vai corresponder a "the[ fi]le", o que obviamente não é o que
está esperando. O endboundary correto neste caso é: ^\.fi$.
Se o adendo não for onde você esperava, tente passar o argumento -vv para as ferramentas, de forma que
elas expliquem a você o que estão fazendo enquanto inserem o adendo.
Exemplo mais detalhado
Documento original (formatado em POD):
|=head1 NAME
|
|dummy - a dummy program
|
|=head1 AUTHOR
|
|me
Então, o adendo a seguir vai assegurar que a seção (em Francês) sobre o tradutor seja adicionado ao final
do arquivo. (em Francês, "TRADUCTEUR" significa "TRADUTOR", e "moi" significa "eu")
|PO4A-HEADER:mode=after;position=AUTEUR;beginboundary=^=head
|
|=head1 TRADUCTEUR
|
|moi
|
Para colocar seu adendo antes do AUTHOR, use o seguinte cabeçalho:
PO4A-HEADER:mode=after;position=NOM;beginboundary=^=head1
Isso funciona porque a próxima linha correspondendo ao beginboundary /^=head1/ após a seção "NAME"
(traduzido para "NOM" em Francês) é aquela declarando os autores. Então, o adendo será colocado entre as
duas seções. Note que se mais tarde alguma outra seção for adicionada entre NAME e AUTHOR, ele irá
quebrar este exemplo, fazendo com que os adendos sejam adicionados antes desta seção recém adicionada.
Para evitar isto, você pode realizar o mesmo usando modo=depois:
PO4A-HEADER:mode=before;position=^=head1 AUTEUR
COMO fazer tudo isso em uma invocação de programa?
O uso do po4a provou ser um pouco propenso a erros para usuários considerando que você tem que chamar
dois programas diferentes na ordem correta (po4a-updatepo e então po4a-translate), cada um deles
precisando de mais do que 3 argumentos. Além disso, era difícil com este sistema usar apenas um arquivo
PO para todos os seus documentos quando mais de um formato era usado.
O programa po4a(1) foi projetado para resolver essas dificuldades. Assim que seu projeto tiver sido
convertido para o sistema, você escreve um simples arquivo de configuração explicando onde seus arquivos
de tradução estão (PO e POT), onde os documentos originais estão, seus formatos e onde suas traduções
devem ser colocadas.
Então, ao chamar po4a(1) com este arquivo assegura que os arquivos PO são sincronizados com o documento
original e que os documentos traduzidos sejam gerados adequadamente. É claro que você vai querer chamar
este programa duas vezes: uma antes da edição dos arquivos PO para atualizá-los e mais uma vez em seguida
para obter um documento traduzido completamente atualizado. Mas você só precisa se lembrar de uma linha
de comando.
COMO personalizar o po4a?
Módulos do po4a possuem opções (especificadas com a opção -o) que podem ser usadas para alterar o
comportamento do módulo.
Você também pode editar o código fonte dos módulos existentes ou até mesmo escrever seus próprios
módulos. Para torná-los visíveis ao po4a, copie seus módulos para o caminho
"/bli/blah/blu/lib/Locale/Po4a/" e adicione o caminho "/bli/blah/blu" na variável de ambiente "PERLIB" ou
"PERL5LIB". Por exemplo:
PERLLIB=$PWD/lib po4a --previous po4a/po4a.cfg
Nota: o nome real do diretório lib não é importante.
Como ele funciona?
Este capítulo dá a você uma visão geral da parte interna do po4a, de forma que você pode se sentir mais
confiante para nos ajudar a manter e melhorá-lo. ele também pode ajudá-lo a entender o porquê de ele não
funcionar da forma que você esperava, e como resolver seus problemas.
Qual é a jogada aqui?
A arquitetura do po4a é orientada a objeto (em Perl. Isso não é legal?). O antepassado comum para todas
as classes analisadoras é chamado de TransTractor. Esse nome estranho vem do fato que ele é ao mesmo
tempo o encarregado por tradução de documento e extração de strings.
Mais formalmente, ele pega um documento para traduzir mais um arquivo PO contendo as traduções para usar
como entrada, enquanto produz duas saídas separadas: outro arquivo PO (resultante da extração das strings
traduzíveis do documento de entrada) e um documento traduzido (com a mesma estrutura daquele de entrada,
mas com todas as strings traduzíveis substituídas com o conteúdo do PO de entrada). Aqui está uma
representação gráfica disso:
Doc. de entrada --\ /---> Doc. de saída
\ TransTractor:: / (traduzido)
+-->-- parse() --------+
/ \
PO de entrada ----/ \---> PO de saída
(extraído)
Esse pequeno osso é o núcleo de toda arquitetura do po4a. Se você omitir o PO de entrada e o documento de
saída, você obtém po4a-gettextize. Se você fornecer ambos arquivos de entrada e desconsiderar o PO de
saída, você obtém po4a-translate.
TransTractor::parse() é uma função virtual implementada por cada módulo. Aqui está um pequeno exemplo
para mostrar a você como ela funciona. Ela analisa uma lista de parágrafos, um de cada vez com <p>.
1 sub parse {
2 PARAGRAPH: while (1) {
3 $my ($paragraph,$pararef,$line,$lref)=("","","","");
4 $my $first=1;
5 while (($line,$lref)=$document->shiftline() && defined($line)) {
6 if ($line =~ m/<p>/ && !$first--; ) {
7 $document->unshiftline($line,$lref);
8
9 $paragraph =~ s/^<p>//s;
10 $document->pushline("<p>".$document->translate($paragraph,$pararef));
11
12 next PARAGRAPH;
13 } else {
14 $paragraph .= $line;
15 $pararef = $lref unless(length($pararef));
16 }
17 }
18 return; # Não conseguiu uma linha definida? Fim do arquivo de entrada.
19 }
20 }
Na linha 6, nós encontramos <p> pela segunda vez. Esse é o sinal de próximo parágrafo. Nós deveríamos,
então, colocar a linha que acabamos de obter de volta no documento original (linha 7) e jogar o parágrafo
adquirido até agora para as saídas. Após remover o <p> do começo do parágrafo na linha 9, nós realizamos
a concatenação dessa marcação com a tradução do resto do parágrafo.
Essa função translate() é muito legal. Ela joga o argumento para o arquivo PO de saída (extração) e
retorna sua tradução da forma como encontrada no arquivo PO de entrada (tradução). Considerando que é
usada como parte do argumento de pushline(), essa tradução acaba dentro do documento de saída.
Isso não é legal? É possível compilar um módulo po4a completo em menos de 20 segundos quando o formato é
simples o suficiente...
Você pode aprender mais sobre isso en Locale::Po4a::TransTractor(3pm).
Gettextização: como ela funciona?
A ideia aqui é pegar o documento original e sua tradução, e dizer que a enésima string extraída da
tradução é a tradução da enésima string extraída do original. Para que isso funcione, ambos arquivos
devem compartilhar exatamente a mesma estrutura. Por exemplo, se os arquivos possui a estrutura a seguir,
é improvável que a 4ª string na tradução (do tipo "capítulo") seja a tradução da 4ª string no original
(do tipo "parágrafo").
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
Para isso, analisadores po4a são usados em ambos arquivos original e tradução para extrair arquivos PO e,
então, um terceiro arquivo PO é compilado deles pegando as mensagens do segundo como tradução das strings
do primeiro. Para confirmar que as strings que nós colocamos juntas são realmente as traduções de cada
um, os analisadores de documento no po4a deveria colocar informação sobre o tipo sintático das strings
extraídas do documento (todos existentes fazem isso, os seus devem fazer também). Então, essa informação
é usada para certificar-se de que ambos documentos possuem a mesma sintaxe. O exemplo anterior, ele nos
permitiria detectar que a string 4 é um parágrafo em um caso, e no outro é um título de capítulo e
relatar o problema.
Em teoria, seria possível detectar o problema e sincronizar novamente os arquivos em seguida (assim como
o diff faz). Mas o que nós deveríamos fazer com as poucas strings antes da dessincronização não é muito
claro, e isso poderia produzir resultados indesejáveis em algumas situações. É por isso que a
implementação atual não tenta sincronizar novamente e falha com detalhes quando alguma coisa dá errado,
exigindo modificação manual dos arquivos para corrigir o problema.
Mesmo com essas precauções, coisas podem dar errado facilmente aqui. É por isso que todas as traduções
presumidas dessa forma são marcadas como incertas, para certificar de que o tradutor reveja e verifique-
as.
Adendo: como ele funciona?
Bom, isso é bem simples. O documento traduzido não é escrito diretamente, mas é mantido na memória até
que os adendos são aplicados. Os algoritmos envolvidos são até que simples. Nós procuramos por uma linha
correspondendo a posição da regexp e inserimos o adendo antes, se estivermos em mode=before. Se não, nós
procuramos pela próxima linha correspondendo à fronteira ("boundary") e insere o adendo após a linha, se
ele for um endboundary, ou antes dessa linha, se ele for um beginboundary.
FAQ
Este capítulo agrupa as perguntas frequentes (FAQ). Na verdade, a maioria das perguntas até agora puderam
ser formuladas dessa forma: "Porque ele é projetado dessa forma e não dessa outra?" Se você pensa que
po4a não é a resposta correta para tradução de documentação, você deveria considerar ler esta seção. Se
ele não responder suas perguntas, por favor entre em contato conosco na lista de discussão
<po4a-devel@lists.alioth.debian.org>. Nós adoramos feedback.
Por que traduzir cada parágrafo separadamente?
Sim, no po4a, cada parágrafo é traduzido separadamente (na verdade, cada módulo decide isso, mas todos os
módulos existentes fazem isso, e o seu deveria também). Há muitas vantagens nesta abordagem:
• Quando as partes técnicas do documento estão ocultas da cena, o tradutor não pode bagunçá-las. Quanto
menos marcadores nós mostrarmos para o tradutor, menos erro ele pode criar.
• Cortar o documento ajuda a isolar as alterações do documento original, localizando quais partes da
tradução precisam ser atualizadas para facilitar esse processo.
Mesmo com essas vantagens, algumas pessoas não gostam da ideia de traduzir cada parágrafo separadamente.
Aqui estão algumas respostas que eu posso dar para o seus medo:
• Essa abordagem foi provada com sucesso no projeto KDE e permite que as pessoas produzam o maior corpo
de documentação traduzida e atualizada que eu conheço.
• Os tradutores ainda podem usar o contexto para traduzir, já que as strings no arquivo PO estão na mesma
ordem que no documento original. Traduzir sequencialmente é, então, comparável se você sua po4a ou não.
E, em qualquer caso, a melhor forma de obter o contexto está em converter o documento para um formato
imprimível, já que o formatadores de texto não são realmente legíveis, na minha opinião.
• Essa abordagem é uma das usadas por tradutores profissionais. Nós concordamos que eles têm objetivos
meio diferentes dos tradutores de código aberto. A manutenção é, por exemplo, normalmente menos crítica
para eles, já que o conteúdo raramente é alterado.
Por que não dividir a nível de sentença (ou menor)?
Ferramentas dos tradutores profissionais de alguma forma dividem o documento a nível de sentença para
obter o máximo de reusabilidade das traduções antigas e para agilizar seu processo. O problema é que a
mesma sentença pode ter várias traduções, dependendo do contexto.
Parágrafos são por definição maiores que as sentenças. Isso vai assegurar que mantendo o mesmo parágrafo
em dois documentos vai haver o mesmo sentido (e tradução), independente do contexto de cada caso.
Divisão em partes menores do que a sentença seria muito ruim. Demoraria um pouco explicar o porquê aqui,
mas o leitor interessado pode ver o página de manual do Locale::Maketext::TPJ13(3pm) (a qual vem com a
documentação do Perl), por exemplo. Resumindo, cada idioma tem suas próprias regras sintáticas e não é
possível criar sentenças agregando de partes de sentenças de forma que funcione para todos os idiomas
existentes (ou até mesmo para as 5 das 10 mais falados, ou até menos).
Por que não colocar o original como comentário junto da tradução (ou o contrário)?
À primeira vista, gettext não parece estar adaptado para todos os tipos de traduções. Por exemplo, ele
não parecia adaptado para debconf, a interface que todos os pacotes Debian usamo para sua interação com o
usuário durante a instalação. Neste caso, os textos para traduzir eram bem pequeno (umas dúzias de linhas
para cada pacote) e era difícil colocar a tradução em um arquivo especializado, já que ele tinha que
estar disponível antes da instalação do pacote.
É por isso que o desenvolvedor do debconf decidiu implementar outra solução, na qual traduções estariam
localizadas no mesmo arquivo que o original. Isso até que é atraente. Alguém poderia até querer fazer
isso para XML, por exemplo. Se pareceria essa forma:
<section>
<title lang="en">My title</title>
<title lang="fr">Mon titre</title>
<para>
<text lang="en">My text.</text>
<text lang="fr">Mon texte.</text>
</para>
</section>
Mas isso era tão problemático que uma abordagem baseada em PO é usada no momento. Apenas o original pode
ser editado no arquivo e as traduções devem ser feitas nos arquivos PO extraídos do modelo mestre (e
colocadas de volta na hora de compilar o pacote). O sistema antigo estava obsoleto porque possuía
diversos problemas:
• problemas de manutenção
Se vários tradutores fornecessem um patch ao mesmo tempo, ficava difícil mesclá-los.
Como você vai detectar alterações no original ao qual precisam ser aplicadas as traduções? Para poder
usar diff, você tem que anotar qual versão do original você traduzido, isto é, você precisa de um
arquivo PO no seu arquivo ;)
• problemas de codificação
Essa solução é viável quando somente idiomas europeus estão envolvidos, mas a tradução de coreano,
russo e/ou árabe realmente complica a situação. UTF seria uma solução, mas ainda haveria problemas
nessa questão.
Além disso, tais problemas são difíceis de detectar (isto é, somente leitores coreanos vão detectar
que a codificação em coreano está quebrada [por causa do tradutor russo])
gettext resolve todos os problemas ao mesmo tempo.
Mas gettext não foi projetado para esse uso!
É verdade, mas até agora ninguém veio com uma solução melhor. E a única alternativa conhecida é a
tradução manual, com todos os problemas de manutenção.
E as outras ferramentas de tradução para documentação usando gettext?
Até onde eu sei, há somente duas:
poxml
Essa é a ferramenta desenvolvida pelo pessoal do KDE para manipular DocBook XML. Até onde eu sei,
esse foi o primeiro programa a extrair strings para traduzir de documentação para arquivos PO, e a
injetá-las de volta após a tradução.
Ela só consegue manipular XML e apenas um DTD em particular. Eu fico, particularmente, não gosto das
listas de manipulação, que acabam com um grande msgid. Quando a lista fica grande, o fragmento se
torna mais difícil de engolir.
po-debiandoc
Esse problema desenvolvido por Denis Barbier é uma espécie de precursor do módulo de SGML do po4a, o
qual meio que torna-o (po-debiandoc) obsoleto. Como o nome já diz, ele linda apenas o DebianDoc DTD,
o qual é meio que um DTD obsoleto.
As principais vantagens do po4a sobre eles é a facilidade de adição de conteúdo extra (o que é bem pior
lá) e a habilidade de alcançar gettextização.
Educando desenvolvedores sobre tradução
Quando você tenta traduzir documentação ou programas, você lida com três tipos de problemas: linguísticas
(nem todo mundo sabe 2 idiomas), técnicos (é por isso que po4a existe) e relacional/humano. Nem todos os
desenvolvedores entendem a necessidade de traduzir as coisas. Mesmo quando estão com boa vontade, eles
podem ignorar como facilitar o trabalho de tradutores. Para ajudar nisso, po4a vem com muita documentação
que pode ser vista.
Outro ponto importante é que cada arquivo traduzido começa com um comentário curto, indicando que arquivo
é e como usá-lo. Isso deve ajudar os coitados dos desenvolvedores mergulhados em toneladas de arquivos em
diferentes idiomas que eles mal conhecem e os ajuda a lidar com isso corretamente.
No projeto po4a, os documentos traduzidos não são mais arquivos fontes, no sentido que estes arquivos não
são da forma preferencial de trabalho para fazer modificações. Já que isto não é convencional, é uma
fonte de erro fácil. É por isso que todos os arquivos possuem esse cabeçalho:
| *****************************************************
| * GENERATED FILE, DO NOT EDIT *
| * THIS IS NO SOURCE FILE, BUT RESULT OF COMPILATION *
| *****************************************************
|
| This file was generated by po4a-translate(1). Do not store it (in VCS,
| for example), but store the PO file used as source file by po4a-translate.
|
| In fact, consider this as a binary, and the PO file as a regular source file:
| If the PO gets lost, keeping this translation up-to-date will be harder ;)
Da mesma forma, arquivo PO comuns do gettext apenas precisam ser copiados para o diretório po/. Mas esse
não é o caso daqueles manipulados por po4a. O maior risco aqui é um desenvolvedor apagar a tradução
existente do seu programa com a tradução da sua documentação. (os dois não podem ser armazenados no mesmo
arquivo PO, porque o programa precisa instalar sua tradução em um arquivo MO enquanto a documentação usa
apenas sua tradução em tempo de compilação). É por isso que os arquivos PO produzidos pelo módulo po-
debiandoc contêm o cabeçalho a seguir:
#
# ADVISES TO DEVELOPERS:
# - you do not need to manually edit POT or PO files.
# - this file contains the translation of your debconf templates.
# Do not replace the translation of your program with this !!
# (or your translators will get very upset)
#
# ADVISES TO TRANSLATORS:
# If you are not familiar with the PO format, gettext documentation
# is worth reading, especially sections dedicated to this format.
# For example, run:
# info -n '(gettext)PO Files'
# info -n '(gettext)Header Entry'
#
# Some information specific to po-debconf are available at
# /usr/share/doc/po-debconf/README-trans
# or http://www.debian.org/intl/l10n/po-debconf/README-trans
#
RESUMO das vantagens da abordagem baseada em gettext
• As traduções não são armazenadas junto do original, o que possibilita detectar se as traduções estão
desatualizadas.
• As traduções são armazenadas em arquivos separados um dos outros, o que previne tradutores de idiomas
diferentes interferir tanto quando da submissão do patch quanto a nível de codificação do arquivo.
• Ele é internamente baseado no gettext (mas po4a oferece uma interface bem simples, de forma que você
não precisa entender as especificidades para usá-lo). Dessa forma, nós não temos que reinventar a roda
e, por causa do seu amplo uso, nós podemos pensar que essas ferramentas meio que não tem erros.
• Nada mudou para o usuário final (além do fato de traduções estarem melhor mantidas, espero). o arquivo
de documentação resultante distribuído é exatamente o mesmo.
• Não há necessidade de tradutores aprenderem um novo arquivo de sintaxe e seu editor de arquivos PO
(como o modo PO do Emacs, Lokalize ou Gtranslator) vão funcionar muito bem.
• gettext oferece uma forma simples de obter estatísticas sobre o que está feito, o que deveria ser
revisto e atualizado e o que ainda deve ser feito. Alguns exemplos podem ser encontrados nesses
endereços:
- http://kv-53.narod.ru/kaider1.png
- http://www.debian.org/intl/l10n/
Mas tudo tem seu lado negativo, e essa abordagem tem algumas desvantagens com as quais nós temos que
lidar.
• Adendos são... estranhos à primeira vista.
• Você não pode adaptar o texto traduzido às suas preferências, com divisão de um parágrafo aqui e juntar
outros dois ali. Mas de certa forma, se há um problema com o original, isso deveria ser relatado como
um erro.
• Até mesmo com uma interface fácil, ainda é uma nova ferramenta que as pessoas precisam aprender.
Um dos meus sonhos seria integrar de alguma forma po4a ao Gtranslator ou Lokalize. Quando um arquivo de
documento fosse aberto, as strings seriam automaticamente extraídas e um arquivo traduzido + arquivo po
poderia ser gravado no disco. Se nós conseguirmos fazer um módulo para MS Word (TM) (ou pelo menos
RTF), tradutores profissionais podem até mesmo usá-lo.
AUTORES
Denis Barbier <barbier,linuxfr.org>
Martin Quinson (mquinson#debian.org)
Ferramentas do Po4a 2017-08-26 PO4A(7)