Provided by: po4a_0.52-1_all 
NOME
po4a - quadro para traduzir a documentação e outros materiais
Introdução
O objetivo do projeto po4a (PO para tudo) é facilitar traduções (e mais interessante, a manutenção das
traduções) usando ferramentas gettext em áreas onde eles não eram esperados como documentação.
Tabela de conteúdo
Este documento está organizado da seguinte forma:
1 Porque deveria eu usar po4a? É bom para quê?
Este capítulo de introdução explica a motivação do projeto e sua filosofia. Você deve lê-lo primeiro,
se você está no processo de avaliação do po4a para suas próprias traduções.
2 Como usar po4a?
Este capítulo é uma espécie de manual de referência, tentando responder às perguntas dos utilizadores
e dar-lhes uma melhor compreensão de todo o processo. Este introduz o modo de fazer as coisas com
po4a e serve como uma apresentação à documentação das ferramentas específicas.
COMO começar uma nova tradução?
COMO mudar a tradução de volta para um ficheiro de documentação?
COMO atualizar uma tradução po4a?
COMO converter uma tradução pré-existente para po4a?
COMO adicionar texto extra para traduções (como o nome do tradutor)?
COMO fazer tudo numa invocação de programa?
COMO personalizar po4a?
3 Como é que funciona?
Este capítulo dá-nos uma visão geral interna do po4a, de modo a que você se possa sentir mais
confiante para nos ajudar a manter e a melhorar. Pode também ajudá-lo a entender por que ele não faz
o que você esperava, e como resolver os seus problemas.
4 FAQ
Este capítulo agrupa as Perguntas Frequentes. Na verdade, a maioria dasperguntas poderia por agora
ser formulada assim: "Por que é projetado este caminho, e não aquele?" Se você acha que po4a não é a
resposta certa para tradução da documentação, deveria considerar a leitura desta secção. Caso não
responder a sua pergunta, por favor contacte-nos em <po4a-devel@lists.alioth.debian.org>lista de
discussão. Nós adoramos feedback.
5 Notas específicas sobre módulos
Este capítulo apresenta as especificidades de cada módulo a partir do ponto vista do tradutor e do
autor original. Leia este capítulo para aprender a sintaxe que você irá encontrar ao traduzir coisas
neste módulo, ou as regras que deve seguir no seu documento original para tornar a vida dos
tradutores mais fácil.
Na verdade, esta secção não é realmente parte deste documento. Ao invés disso, é colocada na
documentação de cada módulo. Isto ajuda a garantir que a informação é atualizada, mantendo a
documentação e o código juntos.
Porque deveria eu usar po4a? Para que é bom?
Eu gosto da idéia de software de código aberto, tornando possível para todos o acesso ao software e seu
código fonte. Mas, sendo francês, eu estou bem ciente que O licenciamento não é a única restrição à
abertura do software: software livre não traduzido é inútil para quem não fala inglês, e nós ainda temos
algum trabalho para realmente torná-lo disponível para todo o mundo.
A percepção desta situação por parte dos atores do código aberto melhorou drasticamente recentemente.
Nós, como tradutores, ganhamos a primeira batalha e convencemos todo mundo da importância das traduções.
Mas infelizmente, foi a parte fácil. Agora, temos que fazer o trabalho e realmente traduzir todas estas
coisas.
Atualmente, o software de código aberto beneficia de um nível decente de tradução, graças ao conjunto
maravilhoso de ferramentas gettext. Ele é capaz de extrair as sequências a traduzir do programa,
apresentar um formato uniforme aos tradutores, e depois usar o resultado de seus trabalhos em tempo de
execução para exibir mensagens traduzidas para o utilizador.
But the situation is rather different when it comes to documentation. Too often, the translated
documentation is not visible enough (not distributed as a part of the program), only partial, or not up
to date. This last situation is by far the worst possible one. Outdated translation can turn out to be
worse than no translation at all to the users by describing old program behavior which are not in use
anymore.
O problema para resolver
Traduzindo documentação não é muito difícil em si mesmo. Os textos são muito mais longos do que as
mensagens do programa e assim, levar mais tempo a ser alcançado, mas nenhuma habilidade técnica é
realmente necessária para fazê-lo. A parte difícil vem quando você tem que manter o seu trabalho.
Detectar em quais partes fez a mudança e precisam ser atualizadas é muito difícil, propenso a erros e
altamente desagradável. Eu acho que isso explica por que é que há tanta documentação traduzida
ultrapassada.
As respostas po4a
Então, todo o ponto de po4a é fazer a tradução da documentação maintainable. A ideia é reutilizar a
metodologia gettext para esse novo campo. Como em gettext, os textos são extraídos dos seus locais
originais em ordem a serem apresentado num formato uniforme para os tradutores. As ferramentas clássicas
gettext ajuda-os a atualizar as suas obras quando uma nova versão do original sai. Mas com a diferença do
modelo clássico gettext, as traduções são re-injetadas na estrutura do documento original de modo que
podem ser processadas e distribuídas como a verão inglesa.
Graças a isso, descobrir quais partes do documento foram alteradas e precisam de uma atualização torna-se
muito fácil. Outro ponto positivo é que as ferramentas fazem quase todo o trabalho quando a estrutura do
documento original fica fundamentalmente reorganizado e quando alguns capítulos são movimentados,
fundidos ou divididos. Ao extrair o texto para traduzir de uma estrutura do documento, você mantém-se
longe da complexidade de formatação de texto e reduz as suas chances de obter um documento partido (mesmo
se não o impedir completamente de o fazer).
Por favor, consulte também o FAQ abaixo neste documento para uma lista mais completa das vantagens e
desvantagens desta abordagem.
Formatos Suportados
Atualmente, esta abordagem tem sido implementada com sucesso para vários tipos de formatos de formatação
de texto:
manual
O bom e velho formato de páginas de manual, usado por muitos programas por aí. O suporte po4a é muito
bem-vindo aqui, pois este formato é um pouco difícil de usar e não é muito amigável para os novatos. O
módulo Locale::Po4a::Man(3pm) também suporta o formato mdoc, usado por aspáginas de manual BSD (também
elas são bastante comuns no Linux).
pod
Este é o formato de Documentação Perl Online. A linguagem e as extensões em si são documentados desta
maneira, assim como a maior parte dos scripts Perl existentes. Isso torna-se fácil de manter a
documentação junto ao código atual por incorporação de ambos no mesmo ficheiro. Isso torna mais fácil a
vida mais fácil ao programador, mas infelizmente, não ao tradutor.
sgml
Mesmo que um pouco substituído por XML hoje em dia, este formato é ainda com frequência bastante usado
para documentos que são mais do que alguns ecrans de comprimento. Ele permite-lhe fazer livros completos.
Atualizando assim a tradução de documentos longos pode revelar-se um verdadeiro pesadelo. diff revela-se
muitas vezes inútil, quando o texto original foi recortado após a atualização. Felizmente, po4a pode
ajudá-lo nesse processo.
Atualmente, são suportados apenas o DebianDoc e DocBook, mas acrescentando suporte para um novo, é muito
simples. É até possível usar po4a num SGML DTD desconhecido sem alterar o código, fornecendo as
necessárias informações sobre a linha de comando. Veja Locale::Po4a::Sgml(3pm) para obter mais detalhes.
TeX / LaTeX
O formato LaTeX é o principal formato de documentação usado nas publicações de Software Livre mundiais.
O módulo Locale::Po4a::LaTeX(3pm) foi testado com documentação Python, um livro e algumas apresentações.
texinfo
Toda a documentação GNU está escrita neste formato (que é ainda um dosrequisito para um projeto GNU se
tornar oficial). O apoio para Locale::Po4a::Texinfo(3pm) em po4a ainda está no início.Por favor, reporte
erros e solicitações de recursos.
xml
O formato XML é um formato de base para muitos formatos de documentação
Atualmente, o DocBook DTD é suportado por po4a. VejaLocale::Po4a::Docbook(3pm) para obter mais detalhes.
outros
Po4a can also handle some more rare or specialized formats, such as the documentation of compilation
options for the 2.4+ Linux kernels or the diagrams produced by the dia tool. Adding a new one is often
very easy and the main task is to come up with a parser of your target format. See
Locale::Po4a::TransTractor(3pm) for more information about this.
Formatos não suportados
Infelizmente, po4a ainda carece de suporte para diversos formatos de documentação.
Há um monte de outros formatos que gostaríamos que fossem suportados em po4a e não só os de documentação.
De fato, pretendemos ligar todos os "market holes" deixados pelas ferramentas clássicas gettext. Abranger
descrições de pacotes (deb e rpm), scripts de perguntas de pacotes de instalação, pacotes com registos
das modificações (changelogs), e todos os formatos de ficheiros especializados utilizados pelos programas
como cenários de jogos ou ficheiros de recursos do Wine.
Como usar po4a?
Este capítulo é uma espécie de manual de referência, tentando responder às perguntas dos utilizadores e
dar-lhes uma melhor compreensão de todo o processo. Este introduz o modo de fazer as coisas com po4a e
serve como uma apresentaçã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
da sua aparente complexidade, vem do fato de que o processo whole é representado aqui. Uma vez que você
converteu seu projeto para po4a, apenas a parte direita do gráfico é relevante.
Note that master.doc is taken as an example for the documentation to be translated and translation.doc is
the corresponding translated text. The suffix could be .pod, .xml, or .sgml depending on its format.
Each part of the picture will be detailed in the next sections.
master.doc
|
V
+<-----<----+<-----<-----<--------+------->-------->-------+
: | | :
{translation} | { update of master.doc } :
: | | :
XX.doc | V V
(optional) | master.doc ->-------->------>+
: | (new) |
V V | |
[po4a-gettextize] doc.XX.po -->+ | |
| (old) | | |
| ^ V V |
| | [po4a-updatepo] |
V | | V
translation.pot ^ V |
| | doc.XX.po |
| | (fuzzy) |
{ translation } | | |
| ^ V V
| | {manual editing} |
| | | |
V | V V
doc.XX.po --->---->+<---<-- doc.XX.po addendum master.doc
(initial) (up-to-date) (optional) (up-to-date)
: | | |
: V | |
+----->----->----->------> + | |
| | |
V V V
+------>-----+------<------+
|
V
[po4a-translate]
|
V
XX.doc
(up-to-date)
Na parte esquerda, é mostrada neste sistema a conversão de uma tradução não utilizando po4a. Na parte
superior do lado direito, a ação do autor original é retratada (atualizando a documentação). No meio da
parte direita onde as as ações de po4a são automáticas são retratadas. O novo material é extraído, e
comparado com a tradução de saída. Partes que não mudaram são encontradas, e onde a tradução anterior é
usada. Partes onde são parcialmente modificadas são também ligadas à tradução anterior, mas com um
marcador específico indicando que a tradução deve ser atualizada. A parte inferior da figura mostra como
um documento formatado é construído.
Na verdade, como um tradutor, a única operação manual que você tem a fazer é a parte marcada {edição
manual}. Sim, eu sinto muito, mas o po4a ajuda-o a traduzir. Ele não traduz qualquer coisa por você ...
COMO começar uma nova tradução?
Esta secção apresenta os passos necessários requeridos para começar uma nova tradução com po4a. os
refinamentos envolvidos na conversão de um projeto existente para este sistema estão detalhados na secção
relevante.
Para começar uma nova tradução usando po4a, você tem que fazer os seguintes passos:
- Extrair o texto que tem que ser traduzido a partir do original <master.doc> documento num novo modelo
de nova tradução <translation.pot> ficheiro (o formato gettext). Para isso, use oprograma
po4a-gettextize desta maneira:
$ po4a-gettextize -f <format> -m <master.doc> -p <translation.pot>
<formato> é naturalmente o formato usado no documento master.doc. Como esperado, a saída vai para
translation.pot. Por favor referir para po4a-gettextize(1) para obter mais detalhes sobre as opções
existentes.
- Actually translate what should be translated. For that, you have to rename the POT file for example to
doc.XX.po (where XX is the ISO 639-1 code of the language you are translating to, e.g. fr for French),
and edit the resulting file. It is often a good idea to not name the file XX.po to avoid confusion with
the translation of the program messages, but this your call. Don't forget to update the PO file
headers, they are important.
A tradução real pode ser feita utilizando-se os modos Emacs ou Vi PO, Lokalize (baseado em KDE),
gTranslator (baseado em GNOME) ou qualquer programa que você prefira usar em vez destes (por exemplo
Virtaal).
Se você quiser saber mais sobre isto, definitivamente precisa de consultar a documentação gettext,
disponível no pacote gettext-doc.
COMO mudar a tradução de volta para um ficheiro de documentação?
Uma vez que você acabou a sua tradução, deseja obter a documentação traduzida e distribuí-la aos
utilizadores, juntamente com o original. Para isso, use o programa po4a-translate(1) assim (onde xx é o
código de linguagem):
$ po4a-translate -f <format> -m <master.doc> -p <doc.XX.po> -l <XX.doc>
As before, <format> is the format used in the master.doc document. But this time, the PO file provided
with the -p flag is part of the input. This is your translation. The output goes into XX.doc.
Por favor, consulte po4a-translate(1) para mais detalhes.
COMO atualizar uma tradução po4a?
Para atualizar a sua tradução quando o ficheiro original master.doc mudou, use o programa
po4a-updatepo(1) assim:
$ po4a-updatepo -f <format> -m <new_master.doc> -p <old_doc.XX.po>
(Por favor, consulte po4a-updatepo(1) para mais detalhes)
Naturalmente, o novo parágrafo no documento não será magicamente traduzido no ficheiro PO com esta
operação, e você precisa atualizar o ficheiro PO manualmente. Da mesma forma, pode ter que refazer a
tradução de parágrafos que foram um pouco modificados. Para se certificar de que não vai perder nenhum
deles, eles são marcados como "fuzzy" durante o processo e tem que remover esse marcador antes da
tradução poder ser usada por po4a-translate. Quanto à tradução inicial, o melhor é usar o seu editor
favorito PO aqui.
Depois que o ficheiro PO é atualizado de novo, sem qualquer falta de sequência não traduzida ou imprecisa
(fuzzy), você pode gerar um ficheiro de documentação traduzida, como explicado na secção anterior.
COMO converter uma tradução pré-existente para po4a?
Muitas vezes, você alegremente traduziu manualmente o documento até uma grande reorganização do documento
original master.doc aconteceu. Então, depois algumas tentativas desagradáveis com diff ou ferramentas
similares, você deseja converter em po4a. Mas, claro, você não quer perder sua tradução existente no
processo. não se preocupe, neste caso, também é tratado por ferramentas po4a e é chamado gettextization.
O importante aqui é para ter a mesma estrutura no documento traduzido e no original, de modo que as
ferramentas possam combinar o conteúdo adequadamente.
Se você tiver sorte (ou seja, se as estruturas de ambos os documentos se adequarem perfeitamente), vai
funcionar perfeitamente e vai ser definido em poucos segundos. Caso contrário, você pode entender porque
este processo tem um nome feio, e é melhor estar preparado para algum trabalho duro aqui. Em qualquer
caso, lembre-se que é o preço a pagar para ter o conforto de po4a depois. E o bom é que tem que fazer
isso apenas uma vez.
I cannot emphasize this too much. In order to ease the process, it is thus important that you find the
exact version which were used to do the translation. The best situation is when you noted down the VCS
revision used for the translation and you didn't modify it in the translation process, so that you can
use it.
Isso não vai funcionar bem quando você usa o texto original atualizado com a tradução antiga. Continua a
ser possível, mas é mais difícil e realmente deve ser evitado se possível. Na verdade, eu acho que se não
encontrar o texto original novamente, a melhor solução é encontrar alguém para lhe fazer a gettextization
(mas, por favor, eu não ;).
Talvez seja muito dramático aqui. Mesmo quando as coisas estão erradas, restam maneiras mais rápidas do
que traduzir tudo de novo. Eu era capaz de gettextizar a tradução francesa existente da documentação Perl
num dia, até mesmo quando as coisas did estão erradas. Isso foi há mais de dois megabytes de texto, e uma
nova tradução teria durado meses ou mais.
Deixe-me explicar a base do primeiro procedimento e vou voltar com dicas para o alcançar quando o
processo dá errado. Para facilitar a compreensão, Vamos usar o exemplo acima, mais uma vez.
Uma vez que você tem o antigo master.doc outra vez que coincide com a tradução XX.doc, a gettextização
pode ser feita diretamente para o ficheiro PO doc.XX.po sem a tradução manual do ficheiro
translation.pot:
$ po4a-gettextize -f <format> -m <old_master.doc> -l <XX.doc> -p <doc.XX.po>
Quando você tiver sorte, é isso. Converteu sua antiga tradução para po4a e pode começar com a tarefa de
atualização imediatamente. Basta seguir o procedimento explicado uma secção um pouco atrás para
sincronizar seus ficheiros PO com o mais novo documento original e, atualizar a tradução em conformidade.
Por favor note que, mesmo quando as coisas parecem funcionar corretamente, ainda há espaço para erros
neste processo. A questão é que po4a é incapaz de compreender o texto para se certificar de que a
tradução coincidir com o original. É por isso que todas as sequências são marcadas como "fuzzy" no
processo. Você deve verificar cada um cuidadosamente antes de retirar os marcadores.
Muitas vezes, as estruturas dos documentos não correspondem exatamente, evitando po4a-gettextize de fazer
seu trabalho corretamente. Neste ponto, o jogo total é sobre a edição dos ficheiros para obter a harmonia
entre as malditas estruturas.
Pode ajudar a ler a secção Gettextization: como é que funciona? abaixo. Compreender o processo interno
vai ajudá-lo a fazer este trabalho. O bom ponto é que po4a-gettextize é bastante detalhado sobre o que
deu errado, quando isso acontece. Primeiro, ele aponta nas estruturas dos documentos onde são as
discrepâncias. Vai aprender que as sequências não correspondem, a suas posições no texto e, o tipo de
cada uma delas. Além disso, o ficheiro PO gerado até agora, vai ser despejado para
gettextization.failed.po.
- Remova todas as peças extras das traduções, como a secção em que você dá o nome do tradutor e
agradece a todas as pessoas que contribuíram para a tradução. Adenda, que são descritos na secção
seguinte, permitirá voltar a adicioná-los mais tarde.
- Não hesite em editar o original e a tradução. A coisa mais importante é obter o ficheiro PO. Você
será capaz de atualizá-lo depois. Dito isto, a edição da tradução deve ser preferida quando ambos são
possíveis uma vez que torna as coisas mais fáceis quando a gettextization está feita.
- Se necessário, mate algumas partes do original, se acontecer não serem traduzidas. Ao sincronizar o
PO com o documento mais tarde, eles vão voltar de si mesmos.
- Se você mudou um pouco a estrutura (para fundir dois parágrafos, ou dividiu uma outra), desfaça as
alterações. Se houver problemas no original, deve informar o autor original. Corrigi-los em sua
tradução só os corrige para uma parte da comunidade. E, além disso, é impossível quando usando po4a
;)
- Às vezes, o conteúdo do parágrafo faz corresponder, mas os seus tipos não. Consertar isto dependente
bastante do formato. Em POD e no manual, muitas vezes vem do fato que um dos dois contém uma linha
que começa com um espaço em branco onde o outro não. Nesses formatos, parágrafo tal, não pode ser
enrolado e assim torna-se num tipo diferente. Basta remover o espaço e está tudo bem. Poderá também
ser um erro de digitação no nome da marca.
Likewise, two paragraphs may get merged together in POD when the separating line contains some
spaces, or when there is no empty line between the =item line and the content of the item.
- Às vezes, há uma dessincronização entre os ficheiros, e a tradução está ligada ao ponto errado
original. É o sinal de que o verdadeiro problema estava antes nos ficheiros. Verifique
gettextization.failed.po para ver quando a dessincronização começa, e corrigi-la lá.
- Às vezes, você tem a forte sensação de que po4a comeu algumas partes do texto, original ou da
tradução. gettextization.failed.po indica quando os dois se correspondente suavemente e, em seguida,
a gettextization falha porque tentou corresponder a um parágrafo com um depois (ou antes) correto,
como se tivesse desaparecido. Maldição po4a, como eu fiz quando me aconteceu pela primeira
vez.Generosamente.
Esta situação infeliz acontece quando o mesmo parágrafo é repetido sobre odocumento. Neste caso, não
é criada uma nova entrada no ficheiro de PO, mas uma nova referência é adicionada ao já existente em
seu lugar.
So, when the same paragraph appears twice in the original but both are not translated in the exact
same way each time, you will get the feeling that a paragraph of the original disappeared. Just kill
the new translation. If you prefer to kill the first translation instead when the second one was
actually better, replace the first one with the second.
No contrário, se dois parágrafos semelhantes, mas diferentes foram traduzidos exatamente da mesma
maneira, você terá a sensação de que um parágrafo da tradução desapareceu. Uma solução é adicionar
uma sequência estúpida ao parágrafo original (como "Eu sou diferente"). Não tenha medo, essas coisas
vão desaparecer durante a sincronização, e quando o texto adicionado é suficiente curto, gettext irá
corresponder a sua tradução para o texto existente (marcando-o como impreciso (fuzzy), mas você
realmente não se importa uma vez que todas as sequências são fuzzy depois da gettextization).
Esperamos que estas dicas o irão ajudar a fazer o seu trabalho de gettextization e obter o precioso
ficheiro PO. Agora você está pronto para sincronizar o seu ficheiro e começar a tradução. Note que no
texto grande, pode acontecer que a primeira sincronização demore um longo tempo.
Por exemplo, o primeiro po4a-updatepo da tradução de documentação Perl em francês (ficheiro PO 5,5 Mb)
demorou cerca de dois dias num computador G5 1Ghz. Sim, 48 horas. Mas as subsequentes levam apenas uma
dúzia de segundos no meu velho portátil. É assim porque na primeira vez, a maioria das 'msgid' do
ficheiro PO não correspondem a nenhum dos ficheiros POT existentes. Isto força o gettext a procurar o
mais próximo, utilizando um caro algoritmo de proximidade de sequências.
COMO adicionar texto extra para traduções (como o nome do tradutor)?
Por causa da abordagem ao gettext, fazendo isto torna-se mais difícil em po4a do que era quando a simples
edição de um novo ficheiro ao longo do original. Mas continua a ser possível, graças ao chamado addenda.
Pode ajudar a compreensão de considerar adendas como uma espécie de remendos aplicados ao documento
localizado após o processamento. Eles são bastante diferentes dos habituais 'patches' (têm apenas uma
linha de contexto, que pode incorporar expressão regular Perl, e só podem adicionar novo texto sem
remover nenhum), mas as funcionalidades são as mesmas.
O seu objetivo é permitir que o tradutor possa adicionar conteúdo extra para o documento que não é
traduzido a partir do documento original. O uso mais comum é adicionar uma secção sobre a sua própria
tradução, lista de colaboradores e explicando como reportar uma erro contra a tradução.
Uma adenda deve ser fornecida como um ficheiro separado. A primeira linha constitui um cabeçalho que
indica onde o documento produzido deve ser colocado. O resto do ficheiro adenda será adicionado
textualmente em determinada posição do documento resultante.
O cabeçalho tem uma sintaxe bastante rígida: Deve começar com a sequência PO4A-HEADER:, seguido por um
ponto e vírgula (;) lista separada de campos key=valor. Espaços em branco SÃO importantes. Note que você
não pode usar o caratere ponto e vírgula (;) no valor, e citando que não ajuda.
Mais uma vez, parece assustador, mas os exemplos dados a seguir devem ajudá-lo a encontrar como escrever
a linha de cabeçalho que precisa. Para ilustrar a discussão, assuma que queremos adicionar uma secção
chamada "Sobre esta tradução" depois uma "Sobre este documento".
Aqui estão as chaves do cabeçalho possíveis:
position (obrigatório)
uma expressão regular Perl. A adenda será colocada perto da linha correspondente a essa regexp. Note-
se que estamos falando sobre o documento traduzido aqui, não o original. Se houver mais de uma linha
corresponde à expressão (ou nenhuma), a adição falhará. Ele é realmente melhor para relatar um erro
do que inserir a adenda no local errado.
Esta linha é chamada position point a seguir. O ponto onde a adenda é adicionada é chamado insertion
point. Esses dois pontos estão perto um do outro, mas não iguais. Por exemplo, se você quiser inserir
uma nova secção, é mais fácil de inserir a position point sobre o título da secção anterior e
explicar po4a onde a secção termina (lembre-se que a position point é dada por uma expressão regular
que deve corresponder uma única linha).
A localização do insertion point no que respeita à posição position point é controlada pelos campos
mode, beginboundary e endboundary , como explicado a seguir.
No nosso caso, teríamos:
position=<title>Acerca deste documento</title>
mode (obrigatório)
It can be either the string before or after, specifying the position of the addendum, relative to the
position point. In case before is given the insertion point will placed exactly before the position
point. The after behaviour is detailed bellow.
Desde que queiramos a nova secção para ser colocada abaixo do que estamos combinando, nós temos:
mode=after
beginboundary (usado somente quando mode=after, e obrigatório neste caso)
endboundary (idem)
expressão regular corresponde ao fim da secção, após o que o adendo vai.
Quando mode=after, o insertion point está após o position point, mas não directamente após! É
colocado no final da secção de início a position point, isto é, antes ou depois de a linha combinada
peloargumento ???boundary, dependendo se você usou beginboundaryou endboundary.
No nosso caso, podemos escolher para indicar o final da secção, nós combinamos por acrescentando:
endboundary=</section>
ou para indicar o início da próxima secção, indicando:
beginboundary=<section>
Em ambos os casos, a nossa adenda será colocado após o </section> e antes do <section>. O primeiro é
melhor, uma vez que vai funcionar mesmo se o documento fica reorganizado.
Ambas as formas existem porque os formatos de documentação são diferentes. Em alguns deles, existe
uma forma de marcar o fim duma secção (tal como o </section>, que utilizamos), enquanto alguns outros
não marcam explicitamente o fim da secção (como no manual). No primeiro caso, você quer fazer um
boundary correspondente a end de um section, de modo que insertion point vem depois. Neste último
caso, você quer fazer um boundary correspondente ao beginning of the next section seguinte, de modo
que a insertion point vem pouco antes.
Isto pode parecer obscuro, mas espero que os próximos exemplos vão esclarecer.
Para resumir o exemplo que usamos até agora, a fim de adicionar uma secção chamada"Sobre esta tradução"
depois uma "Sobre este documento" num documento SGML, você pode usar qualquer uma destas linhas de
cabeçalho:
PO4A-HEADER: mode=after; position=Acerca deste documento; endboundary=</section>
PO4A-HEADER: mode=after; position=Acerca deste documento; beginboundary=<section>
Se você quiser acrescentar algo depois na secção seguinte nroff:
.SH "AUTORES"
você deve colocar o position correspondente a essa linha, e um beginboundary combinando o início da
próxima secção (ou seja, ^\.SH). A adenda será então adicionada after o position point e imediatamente
before a primeira linha correspondente ao beginboundary ou seja:
PO4A-HEADER:mode=after;position=AUTORES;beginboundary=\.SH
Se você quiser adicionar algo numa secção (como depois "Copyright Big Dude") em vez de adicionar uma
secção inteira, dê um position correspondente a essa linha, e dê um beginboundary combinando qualquer
linha.
PO4A-HEADER:mode=after;position=Copyright Big Dude, 2004;beginboundary=^
Se você quiser adicionar alguma coisa no final do documento, dê uma position correspondente a qualquer
linha do seu documento (mas apenas uma linha, po4a não continuará se não é única), e dê uma endboundary
sem corresponder a nada. Aqui não use sequências simples como "EOF", mas prefira as que têm menos chance
estar no seu documento.
PO4A-HEADER:mode=after;position=<title>About</title>;beginboundary=FakePo4aBoundary
Em todo caso, lembre-se que estas são expressões regulares. Por exemplo, se você quiser corresponder à
extremidade de uma secção nroff terminando com a linha
.fi
Não use .fi como endboundary, porque vai coincidir com "the[ fi]le", que obviamente não é o que você
espera. O endboundary correto nesse caso é: .^\fi$.
Se a adenda não for para onde você esperava, tenta passar o argumento -vv para as ferramentas, para que
elas expliquem o que fazem ao colocar a adenda.
Exemplo mais detalhado
Documento original (POD formatado):
|=head1 NOME | |fictício - um programa fictício | |=head1 AUTOR | |eu
Então, a adenda a seguir irá garantir que uma secção (em francês) sobre o tradutor é adicionado no final
do processo. (em francês, "TRADUCTEUR" significa "tradutor" e, "moi" significa "eu")
|PO4A-HEADER:mode=after;position=AUTEUR;beginboundary=^=head
|
|=head1 TRADUCTEUR
|
|moi
|
A fim de colocar a seu adenda antes do AUTOR, use o seguinte cabeçalho:
PO4A-HEADER:mode=after;position=NOM;beginboundary=^=head1
This works because the next line matching the beginboundary /^=head1/ after the section "NAME"
(translated to "NOM" in French), is the one declaring the authors. So, the addendum will be put between
both sections. Note that if later some other section will be added between NAME and AUTHOR sections, it
will break this example making the addenda to be added before this newly added section.
To avoid this you may accomplish the same using mode=before:
PO4A-HEADER:mode=before;position=^=head1 AUTEUR
COMO fazer tudo numa invocação de programa?
O uso de po4a provou ser um erro de pouco propenso para os utilizadores, desde que têm que invocar dois
programas diferentes na ordem correta (po4a-updatepo e depois po4a-translate), cada um deles necessitando
de mais de 3 argumentos. Além disso, foi difícil com este sistema utilizar apenas um ficheiro PO para
todos os seus documentos quando foi usado mais do que um formato.
O programa po4a(1) foi projetado para resolver estas dificuldades. Uma vez que seu projeto é convertido
para o sistema, você escreve um ficheiro de configuração simples a explicar onde estão seus ficheiros de
tradução (PO e POT), onde estão os documentos originais, os seus formatos e onde as suas traduções devem
ser colocadas.
Then, calling po4a(1) on this file ensures that the PO files are synchronized against the original
document, and that the translated document are generated properly. Of course, you will want to call this
program twice: once before editing the PO files to update them and once afterward to get a completely
updated translated document. But you only need to remember one command line.
COMO personalizar po4a?
Os módulos po4a têm opções (especificado com a opção -o) que podem ser usadas para alterar o
comportamento do módulo.
You can also edit the source code of the existing modules or even write your own modules. To make them
visible to po4a, copy your modules into a path called "/bli/blah/blu/lib/Locale/Po4a/" and then adding
the path "/bli/blah/blu" in the "PERLIB" or "PERL5LIB" environment variable. For example:
PERLLIB=$PWD/lib po4a --previous po4a/po4a.cfg
Nota: o atual nome do diretório lib não é importante
Como é que funciona?
Este capítulo dá-nos uma visão geral interna do po4a, de modo a que você se possa sentir mais confiante
para nos ajudar a manter e a melhorar. Pode também ajudá-lo a entender por que ele não faz o que você
esperava, e como resolver os seus problemas.
Qual é a grande imagem aqui?
A arquitetura po4a é orientada a objetos (em Perl. Isso não é de bom gosto?). A ancestral e comum a todas
as classes de analisadores é chamada TransTractor. Este estranho nome vem do facto de ter a
responsabilidade de traduzir documentos e extrair sequências ao mesmo tempo.
Mais formalmente, é preciso um documento para traduzir mais um ficheiro PO contendo as traduções para
usar como entrada, enquanto produz duas saídas separadas: Outro ficheiro PO (resultante da extração das
sequências traduzíveis no documento de entrada) e um documento traduzido (com a mesma estrutura do que a
entrada, mas com todas as sequências de carateres traduzíveis substituídos com o conteúdo de entrada PO).
Aqui é uma representação gráfica deste:
entrada documento --\ /---> saída documento
\ TransTractor:: / (traduzido)
+-->-- analise() --------+
/ \
entrada PO --------/ \---> saída PO
(extraido)
Esse pequeno osso é o núcleo de toda a arquitetura po4a. Se você omitir a entrada PO e do documento de
saída, você obtém po4a-gettextize. Se você fornecer entrada e saída de desconsiderar o PO, você obtém
po4a-translate.
TransTractor::analise() é uma função virtual implementada por cada módulo. Aqui está um pequeno exemplo
para mostrar como funciona. Ele analisa uma lista de parágrafos, cada um deles começando 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; # Did not got a defined line? End of input file.
19 }
20 }
Na linha 6, encontramos <p> para o segundo tempo. Isso é o sinal do próximo parágrafo. Devemos, portanto,
colocar a linha que obtemos de volta no documento original (linha 7) e empurrar o parágrafo construído
até agora nas saídas. Depois de retirar o líder <p> da linha 9, vamos empurrar a concatenação desta
etiqueta com a tradução do resto doparágrafo.
Esta função 'translate'() é muito fixe. Ela empurra o seu argumento para a saída do ficheiro PO
(extração) e retorna a sua tradução como a encontra no ficheiro PO de entrada (tradução). Uma vez que é
usada como parte do argumento de 'pushline'(), estas regiões de tradução para o documento de saída.
Não é fixe? É possível construir um módulo po4a completo em menos de 20 linhas quando o formato é
suficientemente simples...
Você pode aprender mais sobre isso em Locale::Po4a::TransTractor(3pm).
Gettextization: como é que funciona?
A ideia aqui é levar o documento original e a sua tradução, e dizer que a enésima sequência extraída da
tradução é a tradução da enésima sequência extraída do original. Para isto funcionar, os dois ficheiros
devem partilhar exatamente a mesma estrutura. Por exemplo, se os ficheiros têm a seguinte estrutura, é
muito pouco provável que a 4ª sequência na tradução (do tipo 'capítulo') seja a tradução da 4ª sequência
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, os analisadores po4a são usados em ambos os ficheiros, original e a tradução, para extrair
ficheiros PO e, em seguida um terceiro ficheiro PO é construído a partir deles tomando as sequências do
segundo como a tradução de sequências do primeiro. A fim de verificar que as sequências que são colocadas
juntas são realmente as traduções de cada um dos ficheiros, documentos analisados em po4a devem colocar
informações sobre o tipo sintático das sequências extraídas do documento (todos os existentes o fazem, o
seu também deve). Então, esta informação é usada para certificar que ambos os documentos têm a mesma
sintaxe. No exemplo anterior, que nos permitia num caso detetar que a sequência 4 é um parágrafo , e
noutro caso um título do capítulo e relatar o problema.
Em teoria, seria possível detetar o problema, e voltar a sincronizar os ficheiros depois (como faz diff).
Mas o que devemos fazer das poucas sequências antes da dessincronização não é clara, e iria produzir maus
resultados algumas vezes. É por isso que a implementação atual não tenta voltar a sincronizar tudo e
falhar com os detalhes quando algo dá errado, exigindo modificação manual dos ficheiros para corrigir o
problema.
Mesmo com essas precauções, as coisas aqui podem muito facilmente dar errado. É por isso que todas as
traduções supostas desta forma são marcadas como imprecisas (fuzzy) para se certificar de que o tradutor
as revê e verifica.
Adenda: Como isso funciona?
Bem, isso é muito fácil aqui. O documento traduzido não é escrito diretamente para o disco, mas mantido
na memória até que todas as adendas sejam aplicadas. Os algoritmos envolvidos aqui são bastante simples.
Nós olhamos para uma linha que correspondente na posição da expressão regular (regexp), e inserimos a
adenda antes, se estamos emmode=before. Se não, vamos procurar a próxima linha correspondente ao limite e
inserimos a adenda após esta linha se é um endboundary ou antes se esta linha é um beginboundary.
PERGUNTAS MAIS FREQUENTES
Este capítulo agrupa as Perguntas Frequentes. Na verdade, a maioria dasperguntas poderia por agora ser
formulada assim: "Por que é projetado este caminho, e não aquele?" Se você acha que po4a não é a resposta
certa para tradução da documentação, deveria considerar a leitura desta secção. Caso não responder a sua
pergunta, por favor contacte-nos em <po4a-devel@lists.alioth.debian.org>lista de discussão. Nós adoramos
feedback.
Porque se traduz cada parágrafo separadamente?
Sim, em po4a, cada parágrafo é traduzido separadamente (na verdade, cada módulo decide isso, mas todos os
módulos existentes o fazem, e o vossos também devem). Existem são duas vantagens principais para essa
abordagem:
• Quando as partes técnicas do documento estão escondidos da cena, o tradutor não pode mexer com elas.
Quanto menos marcadores apresentarmos ao tradutor menos erro que ele pode fazer.
• Cortar o documento ajuda a isolar as alterações ao documento original. Quando o original é modificado,
encontrando que partes da tradução têm necessidade de ser atualizadas, é facilitado por este processo.
Mesmo com essas vantagens, algumas pessoas não gostam da ideia de traduzir cada parágrafo separadamente.
Aqui estão algumas das respostas que eu posso dar vosso receio:
• Esta abordagem provou ser sucesso no projeto KDE e permite que as pessoas lá produzam o maior 'corpus'
de documentação traduzida e atualizada. Eu sei.
• Os tradutores ainda podem usar o contexto para traduzir, uma vez que as sequências no ficheiro PO estão
da mesma ordem que no documento original. Traduzindo portanto sequencialmente, é comparável se você usa
po4a ou não. E em qualquer caso, a melhor maneira de obter o contexto permanece em converter o
documento para um formato de impressão, desde que a formatação do texto não seja realmente legível,
IMHO.
• Esta abordagem é a usada por tradutores profissionais. Concordo, de que eles têm objetivos um pouco
diferentes dos tradutores de código aberto. A manutenção é por exemplo, muitas vezes menos importante
para eles, uma vez que o conteúdo raramente tem mudanças.
Porque não dividir em nível da frase (ou menor)?
As ferramentas de tradutor profissional, por vezes, dividem o documento nível da frase, a fim de
maximizar a capacidade de reutilização das traduções anteriores e acelerar o seu processo. O problema é
que a mesma frase pode ter traduções diversas, dependendo do contexto.
Os parágrafos são, por definição, mais longos do que frases. Esperemos garantir que tendo o mesmo número
em dois documentos irá ter o mesmo significado (e tradução), independentemente do contexto em cada caso.
Dividindo em partes menores do que a frase seria very bad. Seria um pouco longo para explicar porquê
aqui, mas o leitor interessado pode consultar a página do manual Locale::Maketext::TPJ13(3pm) (que vem
com a documentação Perl), por exemplo. Para ser curto, cada idioma tem as suas regras de sintaxe
específicas, e não há maneira de construir frases agregando partes de frases trabalhando para todos os
idiomas existentes (ou mesmo para 5 dos 10 mais falados, ou até menos).
Why not put the original as comment along with translation (or the other way around)?
À primeira vista, gettext não parece ser adaptado a todos os tipos de traduções. Por exemplo, não parecia
adaptado para debconf, o interface que todos os pacotes do Debian usam para sua interação com o
utilizador durante instalação. Nesse caso, os textos para traduzir eram muito curtos (uma dúzia de linhas
para cada pacote), e foi difícil colocar a tradução num ficheiro especializado uma vez que tem de estar
disponível antes do pacote instalação.
É por isso que o developer debconf decidiu implementar outra solução, onde as traduções são colocados no
mesmo ficheiro que o original. Isto é bastante atraente. Alguém poderia até querer fazer isso para XML,
por exemplo. Ficaria assim:
<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 foi tão problemático que uma abordagem baseada em PO é usada agora. Apenas o original pode ser
editado no ficheiro, e as traduções devem ter lugar em ficheiros PO extraídos do modelo principal (e
colocado de volta no pacote de compilação na hora). O sistema antigo foi substituído por causa de várias
questões:
• Problemas de manutenção
Se vários tradutores fornecerem um fragmento ao mesmo tempo, fica difícil fundi-los.
Como você vai detectar alterações ao original, que precisam ser aplicadas àstraduções? Se usar
'diff', você tem que anotar que versão do original você traduziu. Ou seja, você precisa de um
ficheiro PO em seu ficheiro ;)
• Problemas de codificação
Esta solução é viável quando são envolvidos apenas os idiomas europeus, mas a introdução de coreano,
russo e/ou árabe realmente complicaram o quadro. UTF poderia ser uma solução, mas ainda há alguns
problemas com ele.
Além disso, esses problemas são difíceis de detetar (ou seja, apenas os leitores coreanos irão
detetar que a codificação de coreano está partida [por causa do tradutor russo])
Gettext resolve todos os problemas em conjunto.
Mas gettext não foi projetado para esse uso!
Isso é verdade, mas até agora ninguém apareceu com uma solução melhor. A única alternativa conhecida é a
tradução manual, com todos os problemas de manutenção.
E sobre as outras ferramentas de tradução para documentação usando gettext?
Tanto quanto eu sei, existem apenas duas delas:
poxml
Esta é a ferramenta desenvolvida por pessoas do KDE para lidar com DocBook XML. AFAIK, ele foi o
primeiro programa para extrair sequências para traduzir de documentação para ficheiros PO, e
injetá-las de volta depois de tradução.
Só pode lidar com XML, e apenas um DTD particular. Estou muito descontente com a manipulação de
listas, que terminam com um identificador de mensagem (msgid) grande. Quando a lista se torna enorme,
o bloco torna-se mais difícil de absorver.
po-debiandoc
Este programa feito por Denis Barbier é uma espécie de precursor do módulo po4a SGML, que mais ou
menos o despreza. Como o nome diz, ele trata apenas o DebianDoc DTD, que é mais ou menos um DTD
obsoleto.
As principais vantagens de po4a sobre eles, são a facilidade de adição de conteúdos extra (que é pior
ainda lá) e a capacidade de atingir gettextization.
Educar os developers sobre tradução
Quando você tenta traduzir a documentação ou programas, você enfrenta três tipos de problemas;
Linguística (nem toda a gente fala duas línguas), técnicas (é por isso que existe po4a) e
relacional/humano. Nem todos os developers entendem a necessidade de traduzir o material. Mesmo quando de
boa vontade, eles podem ignorar como facilitar o trabalho dos tradutores. Para ajudar com isso, po4a vem
em muita documentação que pode ser referida.
Outro ponto importante é que cada ficheiro traduzido começa com um curto comentário indicando o que o
ficheiro é e como usá-lo. Isso deve ajudar a os pobres developers inundados com toneladas de ficheiros em
diferentes idiomas que eles dificilmente falam e, ajudá-los a lidar corretamente com ele.
In the po4a project, translated documents are not source files anymore, in the sense that these files are
not the preferred form of the work for making modifications to it. Since this is rather unconventional,
that's a source of easy mistakes. That's why all files present this header:
| *****************************************************
| * 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, os ficheiros PO regulares do gettext só precisam ser copiados para o diretório po/. Mas
este não é um dos casos manipulados por po4a. O grande risco aqui é que um developer apaga a tradução
existente do seu programa com a tradução de sua documentação. (Ambos não podem ser armazenados no mesmo
ficheiro PO, porque o programa precisa para instalar o sua tradução como um ficheiro mo enquanto a
documentação só usa a sua tradução na hora de compilação). É por isso que os ficheiros PO produzidos pelo
módulo po-debiandoc contêm o seguinte cabeçalho:
#
# 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
#
SUMÁRIO de vantagens da aproximação de base ao gettext
• As traduções não são armazenadas com o original, o que torna possível detetar se as traduções estão
desatualizadas.
• As traduções estão armazenadas em ficheiros separados a partir de cada um, o que previne os tradutores
de idiomas diferentes de intervirem, em ambos, quando submetem os seus fragmentos (patches) e no nível
do ficheiro codificado.
• É baseado em gettext (mas po4a oferece uma interface muito simples assim você não precisa de
compreender os internos para o usar).Dessa maneira, não precisamos de reinventar a roda e, porque o seu
uso é mundial, podemos pensar que estas ferramentas estão mais ou menos livres de erros.
• Nada muda para o utilizador final (além do fato das traduções serem, como esperamos, melhor mantidas).
O ficheiro de documentação resultante é exatamente o mesmo.
• Os tradutores não precisam de aprender nova sintaxe de ficheiros e os seus editores de ficheiros PO
favoritos (como o modo PO do Emacs, Lokalize ou Gtranslator) irão trabalhar bem.
• gettext oferece uma maneira simples de obter estatísticas acerca do que é feito, o que deveria ser
revisto e atualizado e, o que ainda está por fazer. Alguns exemplos podem ser encontrados nestes
endereços:
- http://kv-53.narod.ru/kaider1.png
- http://www.debian.org/intl/l10n/
Mas não é tudo verde e, esta aproximação tem também algumas desvantagens com que temos de lidar.
• Adenda é... estranho ao primeiro olhar.
• Não pode adaptar o texto traduzido as suas preferências, como dividindo um parágrafo aqui e, juntando
outros dois ali. Mas em certo sentido, se existe um problema com o original, deve ser reportado como um
erro de qualquer maneira.
• Mesmo com um interface fácil, continua a ser ferramenta nova que as pessoas têm que aprender.
One of my dreams would be to integrate somehow po4a to Gtranslator or Lokalize. When a documentation
file is opened, the strings are automatically extracted, and a translated file + po file can be written
to disk. If we manage to do an MS Word (TM) module (or at least RTF) professional translators may even
use it.
AUTORES
Denis Barbier <barbier,linuxfr.org>
Martin Quinson (mquinson#debian.org)