| PO4A(7) | Ferramentas Po4a | PO4A(7) |
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:
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).
Veja Locale::Po4a::AsciiDoc para detalhes.
Veja Locale::Po4a::Pod para detalhes.
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.
O módulo Locale::Po4a::LaTeX(3pm) foi testado com a documentação Python, um livro e algumas apresentações.
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.
Atualmente, o DocBook DTD (veja Locale::Po4a::Docbook(3pm) para detalhes) e o XHTML são suportados pelo po4a.
Veja Locale::Po4a::BibTex para detalhes.
Veja Locale::Po4a:Docbook para mais detalhes.
Veja Locale::Po4a:Guide para mais detalhes.
Veja Locale::Po4a::Wml para mais detalhes.
Veja Locale::Po4a::Yaml para mais detalhes.
Veja Locale::Po4a::RubyDoc para mais detalhes.
Veja Locale::Po4a:Halibut para mais detalhes.
Veja Locale::Po4a::Ini para mais detalhes.
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
PO4A-HEADER: position=Acerca deste documento; mode=after; beginboundary=<section>
PO4A-HEADER: position=Acerca deste documento ; mode=after; beginboundary=<section>
Exemplos de adendos
.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
PO4A-HEADER:mode=after;position=Copyright Big Dude, 2004;beginboundary=^
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).
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).
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.
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.
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.
- 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.
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.
Denis Barbier <barbier,linuxfr.org> Martin Quinson (mquinson#debian.org)
| 2023-01-03 | Ferramentas Po4a |