po4a - quadro para traduzir a documentação e outros materiais
po4a (PO for anything) facilita a manutenção da
traduções de documentação a usar as ferramentas
gettext clássicas. A característica principal do po4a é
que dissocia a tradução do conteúdo da estrutura
documental dele.
Este documento serve como uma introdução ao projeto po4a, com foco
nos utilizadores em potencial, a considerar a possibilidade de usar essa
ferramenta e no desejo curioso de entender por que as coisas são do
jeito que são.
A filosofia do Software Livre é fazer a tecnologia verdadeiramente
disponível a todos. Mas o licenciamento não é a
única consideração: software livre não traduzido
é inútil para quem não fala inglês. Portanto,
ainda temos algum trabalho a fazer para fazer o software disponível a
todos.
Essa situação é bem compreendida pela maioria dos projetos
e agora todos estão convencidos da necessidade de traduzir tudo. No
entanto, as traduções reais representam um enorme esforço
de muitas pessoas, prejudicadas por pequenas dificuldades técnicas.
Felizmente, o software Open Source é, na verdade, muito bem traduzido a
usar o conjunto de ferramentas gettext. Essas ferramentas são usadas
para extrair as cadeias a traduzir de um programa e apresentar as cadeias a
traduzir num formato padronizado (chamado de ficheiros PO ou catálogos
de tradução). Todo um ecossistema de ferramentas surgiu para
ajudar os tradutores a realmente traduzir esses ficheiros PO. O resultado
é então utilizado pela gettext em tempo de
execução para exibir as mensagens traduzidas para os
utilizadores finais.
Em relação à documentação, no entanto, a
situação ainda é um pouco decepcionante. No
início, traduzir a documentação pode parecer mais
fácil do que traduzir um programa, pois parece que apenas precisa de
copiar o ficheiro-fonte da documentação e começar a
traduzir o conteúdo. No entanto, quando a documentação
original é modificada, manter-se a par das modificações
rapidamente transforma-se num pesadelo para os tradutores. Se for realizada
manualmente, esta tarefa é desagradável e propensa a erros.
Traduções desatualizadas geralmente são piores do que
nenhuma tradução. Os utilizadores finais podem ser enganados
pela documentação que descreve um comportamento antigo do
programa. Além disso, eles não podem interagir diretamente com
os mantenedores, pois não falam inglês. Além disso, o
mantenedor não pode resolver o problema, pois não conhece todos
os idiomas em que a documentação deles está traduzida.
Essas dificuldades, muitas vezes causadas por ferramentas precárias,
podem minar a motivação de tradutores voluntários, a
agravar o problema ainda mais.
O objetivo do projeto po4a é facilitar o trabalho dos tradutores de
documentação. Em particular, torna
manter
traduções de documentações possível.
A ideia é de reutilizar e adaptar a abordagem gettext a esse campo. Assim
como o gettext, os textos são extraídos dos seus locais
originais e apresentados aos tradutores como catálogos de
tradução de pedidos. Os tradutores podem aproveitar as
ferramentas gettext clássicas para monitorar o trabalho a realizar,
colaborar e organizar em equipa. O po4a injeta as traduções
diretamente na estrutura da documentação para produzir ficheiros
de origem traduzidos que podem ser processados e distribuídos da mesma
forma que os ficheiros em inglês. Qualquer parágrafo que
não seja traduzido é deixado em inglês no documento
resultante, a garantir que os utilizadores finais nunca vejam uma
tradução desatualizada na documentação.
Isso automatiza a maior parte do trabalho pesado da manutenção da
tradução. A descoberta dos parágrafos que precisam de
atualização torna-se muito fácil e o processo é
completamente automatizado quando os elementos são reordenados sem
modificações adicionais. A verificação
específica também pode ser usada para reduzir a hipótese
de erros de formatação que resultariam num documento quebrado.
Por favor, consulte também o
FAQ abaixo neste documento para uma
lista mais completa das vantagens e desvantagens desta abordagem.
Atualmente, esta abordagem tem sido implementada com sucesso para vários
tipos de formatos de formatação de texto:
- man (analisador maduro)
- O bom e velho formato de páginas de manual, usado
por muitos programas por aí. Suporte do po4a é muito
bem-vindo, a considerar que esse formato é de certa forma
difícil de usar e não mesmo amigável para novatos.
O módulo Locale::Po4a::Man(3pm) também possui suporte
do formato mdoc usado pelas páginas man do BSD (elas também
são bastante comuns no Linux).
- AsciiDoc (analisador maduro)
- Esse formato é um formato de markup leve, destinado
a facilitar a criação da documentação. Por
exemplo, é usado para documentar o sistema git. Essas
páginas man são traduzidas a usar po4a.
Veja Locale::Po4a::AsciiDoc para detalhes.
- pod (analisador maduro)
- Este é o formato de Documentação Perl
Online. A linguagem e as próprias extensões são
documentadas a usar este formato, além da maioria dos scripts Perl
existentes. Torna fácil manter a documentação perto
do código real, a incorpora-los ambos no mesmo ficheiro. Torna a
vida do programador mais fácil, mas infelizmente não a do
tradutor, até que use o po4a.
Veja Locale::Po4a::Pod para detalhes.
- sgml (analisador maduro)
- Mesmo que hoje em dia seja substituído pelo XML,
este formato ainda é utilizado para documentos com o comprimento de
mais do que alguns ecrãs. Pode até mesmo ser usado para
livros inteiros. Pode ser muito desafiador de atualizar documentos deste
tamanho. diff frequentemente revela-se inútil quando o texto
original foi reintroduzido após a atualização.
Felizmente, o po4a pode ajudá-lo após esse processo.
Atualmente, apenas o DebianDoc e DocBook são suportados, mas a
acrescentar suporte para um novo, é muito simples. É
até possível usar po4a num SGML DTD desconhecido sem alterar
o código, a fornecer as necessárias
informações sobre a linha de comando. Veja
Locale::Po4a::Sgml(3pm) para obter mais detalhes.
- TeX / LaTeX (analisador maduro)
- O formato LaTeX é o formato de
documentação principal usado nas publicações
de Software Livre mundiais.
O módulo Locale::Po4a::LaTeX(3pm) foi testado com a
documentação Python, um livro e algumas
apresentações.
- text (analisador maduro)
- O formato Text é of formato base para muitos
formatos que incluem longos blocos de texto, incluindo Markdown, fortunes,
secção de página de rotos YAML, debian/changelog e
debian/control.
Este possui suporte do formato comum usado em geradores de sites
estáticos, READMEs e outros sistemas de documentação.
Consulte Locale::Po4a::Text(3pm) para detalhes.
- xml e XHMTL (analisador provavelmente maduro)
- O formato XML é um formato de base para muitos
formatos de documentação.
Atualmente, o DocBook DTD (veja Locale::Po4a::Docbook(3pm) para
detalhes) e o XHTML são suportados pelo po4a.
- BibTex (analisador provavelmente maduro)
- O formato BibTex é usado junto com o LaTex para
formatar listas de referências (bibliografias).
Veja Locale::Po4a::BibTex para detalhes.
- Docbook (analisador provavelmente maduro)
- Uma linguagem de marcação baseada em XML que
usa tags semânticas para descrever documentos.
Veja Locale::Po4a:Docbook para mais detalhes.
- Guide XML (analisador provavelmente maduro)
- Um formato de documentação XML. Este
módulo foi desenvolvido especificamente para ajudar no suporte e
manutenção de traduções da
documentação do Gentoo Linux até pelo menos
março de 2016 (baseado na máquina Wayback). Desde
então, o Gentoo mudou para o formato DevBook XML.
Veja Locale::Po4a:Guide para mais detalhes.
- Wml (analisador provavelmente maduro)
- A Web Markup Language, não confunda WML com o
material WAP usado em telefones celulares. Este módulo depende do
módulo Xhtml, que por sua vez depende do módulo XmL.
Veja Locale::Po4a::Wml para mais detalhes.
- Yaml (analisador provavelmente maduro)
- Um superconjunto estrito de JSON. YAML é
frequentemente usado como sistemas ou projetos de
configuração. YAML está no cerne do Ansible da Red
Hat.
Veja Locale::Po4a::Yaml para mais detalhes.
- RubyDoc (analisador provavelmente maduro)
- O formato Ruby Document (RD), originalmente o formato de
documentação padrão para Ruby e projetos Ruby antes
de ser convertido para RDoc em 2002. Embora aparentemente a versão
japonesa do Manual de Referência Ruby ainda use RD.
Veja Locale::Po4a::RubyDoc para mais detalhes.
- Halibut (analisador altamente experimental)
- Um sistema de produção de
documentação, com elementos semelhantes ao TeX,
debiandoc-sgml, TeXinfo e outros, desenvolvido por Simon Tatham, o
programador do PuTTY.
Veja Locale::Po4a:Halibut para mais detalhes.
- Ini (analisador altamente experimental)
- Formato de ficheiro de configuração
popularizado pelo MS-DOS.
Veja Locale::Po4a::Ini para mais detalhes.
- texinfo (analisador altamente experimental)
- Toda a documentação GNU está escrita
neste formato (ainda é um dos requisitos 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.
- Outros formatos suportados
- 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+
(Locale::Po4a::KernelHelp) ou diagramas produzidos pela ferramenta Dia
(Locale::Po4a:Dia). A adição de um novo formato é
normalmente muito fácil e a tarefa principal é fazer um
analisador para o seu formato alvo. Veja
Locale::Po4a::TransTractor(3pm) para mais informações
sobre isso.
- Formatos não suportados
- Infelizmente, o po4a ainda carece suporte para
vários formatos de documentação. Muitos deles
facilmente seriam suportados pelo po4a. Isto inclui formatos não
apenas usados para documentação, tais como,
descrições de pacotes (deb e rpm), questões de
scripts de instalação de pacotes, changelogs de pacotes e
todos os formatos de ficheiros especializados usados por programas como
cenários de jogos ou ficheiros de recursos do wine.
Historicamente, o po4a foi construído à volta de quatro scripts,
cada um a cumprir uma tarefa específica.
po4a-gettextize(1)
ajuda na inicialização de traduções e,
opcionalmente, na conversão de projetos de tradução
existentes em po4a.
po4a-updatepo(1) reflete as
alterações na documentação original nos ficheiros
po correspondentes.
po4a-translate(1) constrói o ficheiro de
origem traduzido do ficheiro original e do ficheiro PO correspondente.
Além disso,
po4a-normalize(1) é principalmente
útil para depurar os analisadores de po4a, pois produz um documento
não traduzido do original. Torna mais fácil identificar as
falhas introduzidas pelo processo de análise.
Most projects only require the features of
po4a-updatepo(1) and
po4a-translate(1), but these scripts proved to be cumbersome and error
prone to use. If the documentation to translate is split over several source
files, it is difficult to keep the PO files up to date and build the
documentation files correctly. As an answer, a all-in-one tool was provided:
po4a(1). This tool takes a configuration file describing the structure
of the translation project: the location of the PO files, the list of files to
translate, and the options to use, and it fully automates the process. When
you invoke
po4a(1), it both updates the PO files and regenerate the
translation files that need to. If everything is already up to date,
po4a(1) does not change any file.
O restante desta secção fornece uma visão geral de como
usar a interface de scripts do po4a. A maioria dos utilizadores provavelmente
preferirá usar a ferramenta multifuncional, descrita na
documentação de
po4a(1).
O esquema a seguir fornece uma visão geral de como cada script po4a pode
ser usado. Aqui,
master.doc é um nome de exemplo para a
documentação a ser traduzida;
XX.doc é o mesmo
documento traduzido no idioma XX, enquanto
doc.XX.po é o
catálogo de traduções desse documento no idioma XX. Os
autores da documentação se preocuparão principalmente com
master.doc (que pode ser uma página man, um documento XML, um
ficheiro asciidoc ou semelhante); os tradutores se preocuparão
principalmente com o ficheiro PO, enquanto os utilizadores finais verão
apenas o ficheiro
XX.doc.
original.doc
|
V
+<-----<----+<-----<-----<--------+------->-------->-------+
: | | :
{tradução} | { actualização do original.doc } :
: | | :
XX.doc | V V
(opcional) | original.doc ->-------->------>+
: | (novo) |
V V | |
[po4a-gettextize] doc.XX.po--->+ | |
| (antigo) | | |
| ^ V V |
| | [po4a-atualizar po] |
V | | V
tradução.pot ^ V |
| | doc.XX.po |
| | (impreciso) |
{tradução} | | |
| ^ V V
| | {edição manual} |
| | | |
V | V V
doc.XX.po --->---->+<---<---- doc.XX.po adenda original.doc
(inicial) (atualizado) (optional) (atualizado)
: | | |
: V | |
+----->----->----->------> + | |
| | |
V V V
+------>-----+------<------+
|
V
[po4a-traduzido]
|
V
XX.doc
(atualizado)
Esse esquema é complicado, mas na prática apenas a parte correta
(a envolver
po4a-updatepo(1) e
po4a-translate(1)) é usada
depois que o projeto é instalado e configurado.
A parte esquerda mostra como
po4a-gettextize(1) pode ser usado para
converter um projeto de tradução existente para a infraestrutura
do po4a. Este script leva um documento original e o equivalente traduzido e
tenta construir o ficheiro PO correspondente. Tal conversão manual
é um pouco trabalhosa (veja a documentação
po4a-gettextize(1) para mais detalhes), mas só é
necessária uma vez para converter as suas traduções
existentes. Se não tiver nenhuma tradução para converter,
pode esquecer-se disto e focar na parte certa do esquema.
Na parte superior direita, a ação do autor original é
retratada, a atualizar a documentação. Na parte do meio,
à direita, as ações automáticas de
po4a-updatepo(1) são representadas. O novo material é
extraído e comparado com a tradução de saída. A
tradução anterior é utilizada para as partes que
não mudaram, enquanto as partes parcialmente modificadas são
ligadas à tradução anterior com um marcador
"fuzzy" a indicar que a tradução deve ser atualizada.
O material novo ou fortemente modificado não é traduzido.
A seguir, a
edição manual relatada representa a
ação dos tradutores, que modificam os ficheiro PO para fornecer
traduções para todas as cadeias e os parágrafos
originais. Isso pode ser feito a usar um editor específico, como o
Editor de Tradução do GNOME, o
Lokalize do KDE ou
poedit ou a usar uma plataforma de localização online
como o
weblate ou
pootle. O resultado da tradução
é um conjunto de ficheiros PO, um por idioma. Consulte a
documentação gettext para mais detalhes.
A parte inferior da figura mostra como
po4a-translate(1) cria um
documento fonte traduzido do documento original
master.doc e do
catálogo de traduções
doc.XX.po que foram
atualizados pelos tradutores . A estrutura do documento é reutilizada,
enquanto o conteúdo original é substituído pela
contraparte dele traduzida. Opcionalmente, um adendo pode ser usado para
adicionar textos à tradução. Isso geralmente é
usado para adicionar o nome do tradutor ao documento final. Veja abaixo os
detalhes.
Como observado anteriormente, o programa
po4a(1) combina os efeitos dos
scripts separados, a atualizar os ficheiros PO e o documento traduzido numa
chamada. A lógica subjacente permanece a mesma.
Se usar
po4a(1), não há etapas específicas para
iniciar uma tradução. Apenas precisa listar os idiomas no
ficheiro de configuração e os ficheiros PO ausentes são
criados automaticamente. Naturalmente, o tradutor deve fornecer
traduções para todos os conteúdos usados nos seus
documentos.
po4a(1) também cria um ficheiro POT, que é um
ficheiro de modelo de PO. Tradutores possíveis podem traduzir o seu
projeto a um novo idioma a renomear esse ficheiro e a fornecer as
traduções no idioma deles.
Se preferir usar os scripts individuais separadamente, use
po4a-gettextize(1) da maniera seguinte para criar o ficheiro POT. Este
ficheiro pode ser copiado em
XX.po para iniciar uma nova
tradução.
$ po4a-gettextize --format <format> --master <master.doc> --po <translation.pot>
O documento mestre é usado na entrada, enquanto o ficheiro PO é a
saída deste processo.
O script a ser usado para isso é
po4a-updatepo(1) (consulte a
documentação para obter detalhes):
$ po4a-updatepo --format <format> --master <new_master.doc> --po <old_doc.XX.po>
O documento mestre é usado na entrada, enquanto o ficheiro PO é
atualizado: ele é usado tanto na entrada quanto na saída.
Uma vez que acabou com a tradução, deseja obter a
documentação traduzida e distribuí-la aos utilizadores
com o original. Para isso, use o programa
po4a-translate(1) como a
seguir:
$ po4a-translate --format <format> --master <master.doc> --po <doc.XX.po> --localized <XX.doc>
Os ficheiros mestre e PO são usados na entrada, enquanto o ficheiro
localizado é a saída desse processo.
Adicionar novos textos à tradução é provavelmente a
única coisa mais fácil a longo prazo quando traduz ficheiros
manualmente :). Isso acontece quando deseja adicionar uma secção
adicional ao documento traduzido, que não corresponde a nenhum
conteúdo no documento original. O caso de uso clássico é
dar mérito à equipa de tradução e indicar como
relatar problemas específicos da tradução.
Com o po4a, é necessário especificar os ficheiros
addendum,
que podem ser vistos conceitualmente como patches aplicados ao documento
localizado após o processamento. Cada adendo deve ser fornecido como um
ficheiro separado, cujo formato é, no entanto, muito diferente dos
patches clássicos. A primeira linha é uma
linha de
cabeçalho, a definir o ponto de inserção do adendo
(com uma sintaxe infelizmente enigmática -- veja abaixo) enquanto o
restante do ficheiro é adicionado literalmente na posição
determinada.
A linha do cabeçalho deve começar com a cadeia
PO4A-HEADER:, seguida por uma lista separada por ponto e vírgula
dos campos
chave=valor.
Por exemplo, o cabeçalho a seguir declara um adendo que deve ser posto
bem no final da tradução.
PO4A-HEADER: mode=eof
As coisas ficam mais complexas quando deseja adicionar o seu conteúdo
adicional no meio do documento. O cabeçalho a seguir declara um adendo
que deve ser posto após a secção XML que contém a
cadeia "Sobre este documento" na tradução.
PO4A-HEADER: position=About this document; mode=after; endboundary=</section>
Na prática, ao tentar aplicar um adendo, o po4a pesquisa a primeira linha
correspondente ao argumento "position" (isso pode ser um regexp).
Não se esqueça que o po4a considera o documento
translated aqui. Esta documentação é em
inglês, mas a sua linha provavelmente deve ser a seguinte, se pretende
que o seu adendo se aplique à tradução do documento em
francês.
PO4A-HEADER: position=À propos de ce document; mode=after; endboundary=</section>
Depois que a "position" foi encontrada no documento de destino, o po4a
procura a próxima linha após a "position" que
corresponde ao "endboundary" fornecido. O adendo é adicionado
à direita
after essa linha (porque fornecemos um
endboundary, ou seja, um limite que termina a secção
atual).
O exato mesmo efeito pode ser obtido com o cabeçalho seguinte, que
é equivalente:
PO4A-HEADER: position=Sobre este documento; mode=after; beginboundary=<section>
Aqui, o po4a pesquisa a primeira linha correspondente a
"<section"> após a linha correspondente a "About
this document" na tradução e adiciona o adendo
before dessa linha, pois fornecemos um
beginboundary, ou seja,
um limite que marca o início da próxima secção.
Portanto, essa linha de cabeçalho exige a inserção do
adendo após a secção que contém "About this
document" e instrui o po4a que uma secção começa com
uma linha que contém a marcação
"<section">. Isso é equivalente ao exemplo anterior,
porque o que realmente deseja é adicionar este adendo após
"/section"> ou antes de "<section">.
Também pode definir a inserção
modo como o valor
"before", com uma semântica semelhante: a
combinação de "mode=before" com um
"endboundary" pôrá o adendo apenas
after o
limite correspondente, que a última linha limite potencial antes da
"position". Combinar "mode=before" com um
"beginboundary" pôrá o adendo apenas
before do
limite correspondente, que é a última linha limite potencial
antes da "position".
Modo | Tipo de limite | Limite usado | Ponto de inserção am comparação ao limite
========|================|============================|==========================================
'before'| 'endboundary' | último antes de 'position' | Logo após o limite selecionado
'before'|'beginboundary' | último antes de 'position' | Logo antes do limite selecionado
'after' | 'endboundary' | primeiro após 'position' | Logo após o limite selecionado
'after' |'beginboundary' | primeiro após 'position' | Logo antes do limite selecionado
'eof' | (none) | n/d | Fim do ficheiro
Dicas e truques sobre adendos
- •
- Lembre-se que estes são regexp. Por exemplo, se
quiser combinar o final de uma secção nroff a terminar com a
linha ".fi", não use ".fi" como
endboundary, porque ele irá combinar com "the[
fi]le", que obviamente não é o que espera. O
endboundary correto, nesse caso, é: "^^.fi$".
- •
- Espaços em branco SÃO importantes no
conteúdo da "position" e limites. Portanto, as duas
linhas seguintes são diferentes. O segundo só
será encontrado se houver espaços suficientes à
direita no documento traduzido.
PO4A-HEADER: position=Acerca deste documento; mode=after; beginboundary=<section>
PO4A-HEADER: position=Acerca deste documento ; mode=after; beginboundary=<section>
- •
- Embora essa pesquisa de contexto possa ser a operar cerca
de cada linha do documento traduzido, realmente opera na cadeia de
dados interna do documento traduzido. Essa cadeia de dados interna pode
ser um texto a abranger um parágrafo que contem várias
linhas ou pode ser uma marcação XML sozinha. O exato
ponto de inserção do adendo deve ser anterior ou
posterior à sequência de dados interna e não pode
estar dentro da cadeia de dados interna.
- •
- Passe o argumento -vv para po4a para entender como
os adendos são adicionados à tradução.
Também pode ajudar a executar po4a no modo de
depuração para ver a cadeia de dados interna real quando o
seu adendo não se aplica.
Exemplos de adendos
- •
- Se quiser acrescentar algo depois na secção
seguinte nroff:
.SH "AUTORES"
Deve selecionar a abordagem em duas etapas a configurar mode=after.
Em seguida, deve restringir a pesquisa à linha após
AUTHORS com a regex de argumento position. Depois deve
combinar o início da próxima secção (isto
é, ^ \. SH) com a regex de argumento beginboundary.
Isso é para dizer:
PO4A-HEADER:mode=after;position=AUTORES;beginboundary=\.SH
- •
- Se quiser adicionar algo logo após uma determinada
linha (por exemplo, após a linha "Copyright Big Dude"),
use uma position a corresponder a esta linha, mode=after e
dê um beginboundary a corresponder a qualquer linha.
PO4A-HEADER:mode=after;position=Copyright Big Dude, 2004;beginboundary=^
- •
- Se 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 cadeias simples como
"EOF", mas prefira as que têm menos
hipótese estar no seu documento.
PO4A-HEADER:mode=after;position=Sobre este documento;beginboundary=FakePo4aBoundary
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=AUTOR;beginboundary=^=head
|
|=head1 TRADUTOR
|
|eu
|
Para posicionar a sua adenda antes do AUTOR, use o seguinte cabeçalho:
PO4A-HEADER:mode=after;position=NOM;beginboundary=^=head1
Isso funciona porque a próxima linha a corresponder ao
beginboundary /^=head1/ após a secção
"NAME" (traduzido para "NOM" em Francês) é
aquela a declarar os autores. Então, o adendo será posto entre
as duas secções. Note que se outra secção for
adicionada entre as secções NAME e AUTHOR posteriormente, po4a
pôrá o adendo equivocadamente antes da nova
secção.
Para evitar isto, pode realizar o mesmo a usar
mode=
before:
PO4A-HEADER:mode=before;position=^=head1 AUTEUR
Este capítulo dá-nos uma visão geral interna do po4a, de
modo que possa sentir-se 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
esperava e como resolver os seus problemas.
A arquitetura do po4a é orientada a objetos. A
Locale::Po4a::TransTractor(3pm) class é o ancestral comum a
todos os analisadores do po4a. Este estranho nome vem do facto de ser ao mesmo
tempo responsável pela tradução de documentos e pela
extração de cadeias.
Mais formalmente, é preciso um documento para traduzir mais um ficheiro
PO que contém 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 cadeias 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)
Este pequeno osso é o núcleo de toda a arquitetura do po4a. Se
omitir o PO de entrada e o documento de saída, obtém
po4a-gettextize. Se fornecer ambos ficheiros de entrada e desconsiderar
o PO de saída, obtém
po4a-translate. O
po4a chama
o TransTractor duas vezes e chama
msgmerge -U entre essas chamadas do
TransTractor para fornecer uma solução completa com um
único ficheiro de configuração. Por favor veja
Locale::Po4a::TransTractor(3pm) para mais detalhes.
Aqui está uma lista bem parcial de projetos que usam po4a na
produção para a documentação deles. Se quiser
adicionar o seu projeto à lista, basta nos enviar um e-mail (ou uma
merge request).
- •
- adduser (man): ferramenta de gestão de utilizadores
e grupos.
- •
- apt (man, docbook): Gestor de pacotes do Debian.
- •
- aptitude (docbook, svg): Gestor de pacotes em interface de
texto para Debian
- •
- Site do F-Droid
<https://gitlab.com/fdroid/fdroid-website> (markdown):
catálogo instalável de aplicações FOSS
(abreviação de software livre e de código aberto)
para a plataforma Android.
- •
- git <https://github.com/jnavila/git-manpages-l10n>
(asciidoc): sistema de controle de versão distribuído para
alterações de rastreamento em código-fonte.
- •
- Páginas man do Linux
<https://salsa.debian.org/manpages-l10n-team/manpages-l10n> (man)
Este projeto fornece uma infraestrutura para traduzir muitas páginas
man para diferentes idiomas, prontas para integração em
várias grandes distribuições (Arch Linux, Debian e
derivados, Fedora).
- •
- Stellarium <https://github.com/Stellarium/stellarium>
(HTML): um planetário de código aberto e livre para o seu
computador. po4a é usado para traduzir as descrições
da cultura do céu.
- •
- Outro item para resolver:
<https://gitlab.com/fdroid/fdroid-website/>
<https://github.com/fsfe/reuse-docs/pull/61>
Pessoalmente vocalizo-o como pouah <
https://en.wiktionary.org/wiki/pouah>,
que é um onomatopaico francês que usamos no lugar de
"eca" :) posso ter um senso de humor estranho :)
There are a few of them. Here is a possibly incomplete list, and more tools are
coming at the horizon.
- poxml
- Esta é a ferramenta desenvolvida por pessoas do KDE
para lidar com DocBook XML. AFAIK, ele foi o primeiro programa para
extrair cadeias 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.
- xml2po.py
- Used by the GIMP Documentation Team since 2004, works quite
well even if, as the name suggests, only with XML files and needs
specially configured makefiles.
- Sphinx
- The Sphinx Documentation Project also uses gettext
extensively to manage its translations. Unfortunately, it works only for a
few text formats, rest and markdown, although it is perhaps the only tool
that does this managing the whole translation process.
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.
- •
- 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 não precisa de compreender os
internos para o usar). Dessa forma não precisamos de reinventar a
roda e, porque o uso dele é 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 a nova
sintaxe de ficheiros e os editores de ficheiros PO favoritos deles (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
encontram-se nestes endereços:
- https://docs.kde.org/stable5/pt_BR/kdesdk/lokalize/project-view.html
- 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.
- •
- Adendos são… estranhos à primeira
vista.
- •
- Não pode adaptar o texto traduzido as suas
preferências, como a dividir um parágrafo aqui e, a juntar
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.
Um dos meus sonhos seria integrar de alguma forma po4a ao Gtranslator ou
Lokalize. Quando um ficheiro de documento fosse aberto, as cadeias seriam
automaticamente extraídas e um ficheiro traduzido + ficheiro po
poderia ser gravado no disco. Se conseguirmos fazer um módulo para
MS Word (TM) (ou pelo menos RTF), tradutores profissionais podem
até mesmo usá-lo.
- •
- A documentação da ferramenta multifuncional
que deve usar: po4a(1).
- •
- A documentação dos scripts individuais do
po4a: po4a-gettextize(1), po4a-updatepo(1),
po4a-translate(1), po4a-normalize(1).
- •
- Os scripts de ajuda adicionais: msguntypot(1),
po4a-display-man(1), po4a-display-pod(1).
- •
- Os analisadores de cada formato, particularmente para ver
as opções aceitas por cada um deles:
Locale::Po4a::AsciiDoc(3pm) Locale::Po4a::Dia(3pm),
Locale::Po4a::Guide(3pm), Locale::Po4a::Ini(3pm),
Locale::Po4a::KernelHelp(3pm), Locale::Po4a::Man(3pm),
Locale::Po4a::RubyDoc(3pm), Locale::Po4a::Texinfo(3pm),
Locale::Po4a::Text(3pm), Locale::Po4a::Xhtml(3pm),
Locale::Po4a::Yaml(3pm), Locale::Po4a::BibTeX(3pm),
Locale::Po4a::Docbook(3pm), Locale::Po4a::Halibut(3pm),
Locale::Po4a::LaTeX(3pm), Locale::Po4a::Pod(3pm),
Locale::Po4a::Sgml(3pm), Locale::Po4a::TeX(3pm),
Locale::Po4a::Wml(3pm), Locale::Po4a::Xml(3pm).
- •
- A implementação da infraestrutura principal:
Locale::Po4a::TransTractor(3pm) (particularmente importante para
entender a organização do código),
Locale::Po4a::Chooser(3pm), Locale::Po4a::Po(3pm),
Locale::Po4a::Common(3pm). Por favor, verifique também o
ficheiro CONTRIBUTING.md na árvore de fonts.
Denis Barbier <barbier,linuxfr.org>
Martin Quinson (mquinson#debian.org)