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)