| PO4A.7(1) | User Contributed Perl Documentation | PO4A.7(1) |
po4a - framework para traduzir documentação e outros materiais
po4a (PO for anything) facilita a manutenção da tradução de documentação usando as ferramentas gettext clássicas. A principal característica do po4a é que ele dissocia a tradução do conteúdo de sua estrutura documental.
Este documento serve como uma introdução ao projeto po4a, com foco nos usuários em potencial, considerando 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 é tornar a tecnologia verdadeiramente disponível para todos. Mas o licenciamento não é a única consideração: o software livre não traduzido é inútil para quem não fala inglês. Portanto, ainda temos algum trabalho a fazer para disponibilizar o software para 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 de código aberto é realmente muito bem traduzido usando o conjunto de ferramentas gettext. Essas ferramentas são usadas para extrair as strings a serem traduzidas de um programa e apresentar as strings em um formato padronizado (chamado de arquivos PO ou catálogos de tradução). Um ecossistema inteiro de ferramentas surgiu para ajudar os tradutores a traduzir esses arquivos PO. O resultado é usado pelo gettext no tempo de execução para exibir mensagens traduzidas para os usuários 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 você apenas precisa copiar o arquivo-fonte da documentação e começar a traduzir o conteúdo. No entanto, quando a documentação original é modificada, acompanhar as modificações rapidamente se transforma em um pesadelo para os tradutores. Se realizada manualmente, esta tarefa é desagradável e propensa a erros.
Traduções desatualizadas geralmente são piores do que nenhuma tradução. Os usuários 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 sua documentação está traduzida. Essas dificuldades, muitas vezes causadas por ferramentas precárias, podem minar a motivação de tradutores voluntários, agravando ainda mais o problema.
O objetivo do projeto po4a é facilitar o trabalho dos tradutores de documentação. Em particular, ele torna possível manter traduções de documentações.
A ideia é reutilizar e adaptar a abordagem gettext a esse campo. Assim como o gettext, os textos são extraídos de 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 equipe. O po4a injeta as traduções diretamente na estrutura da documentação para produzir arquivos de origem traduzidos que podem ser processados e distribuídos da mesma forma que os arquivos em inglês. Qualquer parágrafo que não seja traduzido é deixado em inglês no documento resultante, garantindo que os usuários 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 se torna 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 chance de erros de formatação que resultariam em um documento quebrado.
Por favor, veja também o FAQ abaixo neste documento para uma lista mais completa de vantagens e desvantagens desta abordagem.
Atualmente, essa abordagem tem sido implementada com sucesso em vários formatos de formatação de texto:
O módulo Locale::Po4a::Man(3pm) também possui suporte ao 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, há suporte apenas ao DebianDoc e o DocBook DTD, mas a adição de suporte a um novo é realmente fácil. É possível até mesmo usar po4a em um SGML DTD desconhecido sem alterar o código, desde que sejam fornecidas as informações necessárias na linha de comando. Veja Locale::Po4a::Sgml(3pm) para mais detalhes.
O módulo Locale::Po4a::LaTeX(3pm) foi testado com a documentação do Python, um livro e algumas apresentações.
Este possui suporte ao 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 mais detalhes) e 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.
A maneira mais fácil de usar esta ferramenta em seu projeto é escrever um arquivo de configuração para o programa po4a e interagir apenas com este programa. Consulte sua documentação, em po4a(1). O restante desta seção fornece mais detalhes para os usuários avançados do po4a que desejam aprofundar sua compreensão.
Certifique-se de ler po4a(1) antes desta seção excessivamente detalhada para obter uma visão geral simplificada do fluxo de trabalho do po4a. Volte aqui quando quiser ver a imagem assustadora completa, com quase todos os detalhes.
No esquema a seguir, mestre.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 mestre.doc (que pode ser uma página man, um documento XML, um arquivo AsciiDoc etc.); os tradutores se preocuparão principalmente com o arquivo PO, enquanto os usuários finais verão apenas o arquivo XX.doc.
Transições com colchetes, como "[po4a atualiza po]", representam a execução de uma ferramenta po4a, enquanto transições com chaves, como "{atualização do mestre.doc}", representam uma modificação manual dos arquivos do projeto.
mestre.doc
|
V
+<-----<----+<-----<-----<--------+------->-------->-------+
: | | :
{tradução} | {atualização de mestre.doc} :
: | | :
XX.doc | V V
(opcional) | mestre.doc ->-------->------>+
: | (novo) |
V V | |
[po4a-gettextize] doc.XX.po---->+ | |
| (velho) | | |
| ^ V V |
| | [po4a atualiza po] |
V | | V
tradução.pot ^ V |
| | doc.XX.po |
| | (incerto) |
{tradução} | | |
| ^ V V
| | {edição manual} |
| | | |
V | V V
doc.XX.po --->---->+<---<-- doc.XX.po adendo mestre.doc
(inicial) (atualizado) (opcional) (atualizado)
: | | |
: V | |
+----->----->----->------> + | |
| | |
V V V
+------>-----+------<------+
|
V
[po4a atualiza traduções]
|
V
XX.doc
(atualizado)
Novamente, esse esquema é excessivamente complicado. Confira po4a(1) para uma visão geral simplificada.
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 pega um documento original e seu equivalente traduzido, e tenta construir o arquivo 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 suas traduções existentes. Se você não tem nenhuma tradução para converter, você pode esquecer isso e focar na parte certa do esquema.
Na parte superior direita, a ação do autor original está descrita, atualização da documentação. A parte do meio, à direita, representa as atualizações automáticas dos arquivos de tradução: os novos materiais são extraídos e comparados com a tradução existente. A tradução anterior é usado para as partes que não foram alteradas, enquanto partes parcialmente modificadas também são conectadas à tradução anterior com uma marcação "fuzzy" indicando que a tradução deve ser atualizada. Material novo ou muito modificado é deixado sem tradução.
Then, the manual editing block depicts the action of the translators, that modify the PO files to provide translations to every original string and paragraph. This can be done using either a specific editor such as the GNOME Translation Editor, KDE's Lokalize or poedit, or using an online localization platform such as weblate or pootle. The translation result is a set of PO files, one per language. Please refer to the gettext documentation for more details.
A parte inferior da figura mostra como po4a cria um documento fonte traduzido do documento original mestre.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 por sua contraparte traduzida. Opcionalmente, um adendo pode ser usado para adicionar um texto extra à tradução. Isso geralmente é usado para adicionar o nome do tradutor ao documento final. Veja abaixo os detalhes.
Após a invocação, po4a atualiza automaticamente os arquivos de tradução e os arquivos de documentação traduzidos.
Se você começa do zero, basta escrever um arquivo de configuração para po4a e pronto. Os modelos relevantes são criados para os arquivos ausentes, permitindo que seus colaboradores traduzam seu projeto para o idioma deles. Consulte po4a(1) para um tutorial de início rápido e para todos os detalhes.
Se você já possui uma tradução, ou seja, um arquivo de documentação que foi traduzido manualmente, você pode integrar seu conteúdo em seu fluxo de trabalho po4a usando po4a-gettextize. Esta tarefa é um pouco complicada (conforme descrito na página de manual da ferramenta), mas assim que seu projeto for convertido para o fluxo de trabalho po4a, tudo será atualizado automaticamente.
Após a configuração, invocar po4a é suficiente para atualizar os arquivos PO de tradução e os documentos traduzidos. Você pode passar o "--no-translations" para po4a para não atualizar as traduções (atualizando apenas os arquivos PO) ou "--no-update" para não atualizar os arquivos PO (atualizando apenas as traduções). Isso corresponde aproximadamente aos scripts individuais po4a-updatepo e po4a-translate que agora foram descontinuados (veja "Por que os scripts individuais foram descontinuados" no FAQ abaixo).
Adicionar novo texto à tradução é provavelmente a única coisa mais fácil a longo prazo quando você traduz arquivos manualmente :). Isso acontece quando você deseja adicionar uma seção extra ao documento traduzido, que não corresponde a nenhum conteúdo no documento original. O caso de uso clássico é dar créditos à equipe de tradução e indicar como relatar problemas específicos da tradução.
Com o po4a, é necessário especificar os arquivos addendum, que podem ser vistos conceitualmente como patches aplicados ao documento localizado após o processamento. Cada adendo deve ser fornecido como um arquivo separado, cujo formato é, no entanto, muito diferente dos patches clássicos. A primeira linha é uma linha de cabeçalho, definindo o ponto de inserção do adendo (com uma sintaxe infelizmente enigmática -- veja abaixo) enquanto o restante do arquivo é adicionado literalmente na posição determinada.
A linha do cabeçalho deve começar com a string 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 colocado bem no final da tradução.
PO4A-HEADER: mode=eof
As coisas ficam mais complexas quando você deseja adicionar seu conteúdo extra no meio do documento. O cabeçalho a seguir declara um adendo que deve ser colocado após a seção XML que contém a string "Sobre este documento" na tradução.
PO4A-HEADER: position=Sobre este documento; 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 esqueça que o po4a considera o documento translated aqui. Esta documentação está em inglês, mas sua linha provavelmente deve ser a seguinte, se você pretende que seu adendo se aplique à tradução em francês do documento.
PO4A-HEADER: position=À propos de ce document; mode=after; endboundary=</section>
Depois que a "position" é 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 seção atual).
O exato mesmo efeito pode ser obtido com o seguinte cabeçalho, que é equivalente:
PO4A-HEADER: position=About this document; 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 adicione o adendo before dessa linha, pois fornecemos um beginboundary, ou seja, um limite que marca o início da próxima seção. Portanto, essa linha de cabeçalho exige a inserção do adendo após a seção que contém "About this document" e instrui o po4a que uma seção começa com uma linha que contém a tag "<section>". Isso é equivalente ao exemplo anterior, porque o que você realmente deseja é adicionar este adendo após "</section>" ou antes de "<section>".
You can also set the insertion mode to the value "before", with a similar semantic: combining "mode=before" with an "endboundary" will put the addendum just after the matched boundary, that is the last potential boundary line before the "position". Combining "mode=before" with an "beginboundary" will put the addendum just before the matched boundary, that is the last potential boundary line before the "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 arquivo
Dicas e truques sobre adendos
PO4A-HEADER: position=Sobre este documento; mode=after; beginboundary=<section>
PO4A-HEADER: position=Sobre este documento; mode=after; beginboundary=<section>
Exemplos de adendos
.SH "AUTHORS"
Você deve selecionar uma abordagem em duas etapas configurando mode=after. Em seguida, você deve restringir a pesquisa à linha após AUTHORS com a regex de argumento position. Então, você deve combinar o início da próxima seção (isto é, ^ \. SH) com a regex de argumento beginboundary. Isso é para dizer:
PO4A-HEADER:mode=after;position=AUTHORS;beginboundary=\.SH
PO4A-HEADER:mode=after;position=Copyright Grande Cara, 2004;beginboundary=^
PO4A-HEADER:mode=after;position=Sobre este documento;beginboundary=FakePo4aBoundary
Exemplo mais detalhado
Documento original (formatado em POD):
|=head1 NAME | |dummy - a dummy program | |=head1 AUTHOR | |me
Então, o adendo a seguir vai assegurar que a seção (em Francês) sobre o tradutor seja adicionado ao final do arquivo (em Francês, "TRADUCTEUR" significa "TRADUTOR", e "moi" significa "eu").
|PO4A-HEADER:mode=after;position=AUTEUR;beginboundary=^=head | |=head1 TRADUCTEUR | |moi |
Para colocar seu adendo antes do AUTHOR, use o seguinte cabeçalho:
PO4A-HEADER:mode=after;position=NOM;beginboundary=^=head1
Isso funciona porque a próxima linha correspondendo ao beginboundary "/^=head1/" após a seção "NAME" (traduzido para "NOM" em Francês) é aquela declarando os autores. Então, o adendo será colocado entre as duas seções. Note que se outra seção for adicionada entre as seções NAME e AUTHOR posteriormente, po4a colocará o adendo equivocadamente antes da nova seção.
Para evitar isto, você pode realizar o mesmo usando mode=before:
PO4A-HEADER:mode=before;position=^=head1 AUTEUR
Este capítulo dá a você uma visão geral da parte interna do po4a, de forma que você pode se sentir mais confiante para nos ajudar a mantê-lo e melhorá-lo. Ele também pode ajudá-lo a entender o porquê de ele não funcionar da forma que você esperava, e como resolver seus problemas.
No centro do projeto do po4a, a classe Locale::Po4a::TransTractor(3pm) é um antepassado comum para todos analisadores do po4a. Esse nome estranho vem do fato que ele é ao mesmo tempo o encarregado por tradução de documento e extração de strings.
Mais formalmente, ele pega um documento para traduzir mais um arquivo PO contendo as traduções para usar como entrada, enquanto produz duas saídas separadas: outro arquivo PO (resultante da extração das strings traduzíveis do documento de entrada) e um documento traduzido (com a mesma estrutura que a da entrada, mas com todas as strings traduzíveis substituídas com o conteúdo do PO de entrada). Aqui está uma representação gráfica disso:
Doc. de entrada --\ /---> Doc. de saída
\ TransTractor:: / (traduzido)
+-->-- parse() --------+
/ \
PO de entrada ----/ \---> PO de saída
(extraído)
Este ossinho é o núcleo de toda a arquitetura po4a. Se você fornecer a entrada e desconsiderar o PO de saída, obterá po4a-translate. Se você desconsiderar o documento de saída, obterá po4a-updatepo. O po4a usa um primeiro TransTractor para obter um arquivo POT de saída atualizado (desconsiderando os documentos de saída), chama msgmerge -U para atualizar os arquivos PO de tradução no disco e constrói um segundo TransTractor com estes arquivos PO atualizados para atualizar os documentos de saída. Resumindo, po4a fornece uma solução completa para atualizar o que precisa ser, usando um único arquivo de configuração.
po4a-gettextize também usa dois TransTractors, mas de outra forma: ele constrói um TransTractor por idioma e então constrói um novo arquivo PO usando os msgids do documento original como msgids, e os msgids do documento traduzido como msgstrs. É necessário muito cuidado para garantir que as strings correspondidas desta forma realmente correspondam, conforme descrito em po4a-gettextize(1).
Todos os analisadores de formato po4a são implementados no TransTractor. Alguns deles são muito simples, como os Text, Markdown e AsciiDoc. Eles carregam as linhas uma por uma usando TransTractor::shiftline(), acumulam o conteúdo dos parágrafos ou algo assim. Depois que uma string é completamente analisada, o analisador usa TransTractor::translate() para (1) adicionar essa string ao arquivo PO de saída e (2) obter a tradução do arquivo PO de entrada. O analisador então envia o resultado para o arquivo de saída usando TransTractor::pushline().
Alguns outros analisadores são mais complexos porque dependem de um analisador externo para analisar o documento de entrada. Os analisadores Xml, HTML, SGML e Pod são construídos com base nos analisadores SAX. Eles declaram retornos de chamada para eventos como "Encontrei um novo título cujo conteúdo é o seguinte" para atualizar o documento de saída e gerar arquivos POT de acordo com o conteúdo de entrada usando TransTractor::translate() e TransTractor::pushline(). O analisador Yaml é semelhante, mas diferente: ele serializa uma estrutura de dados produzida pelo analisador YAML::Tiny. É por isso que o módulo Yaml do po4a falha ao declarar as linhas de referência: a localização de cada string no arquivo de entrada não é mantida pelo analisador, então só podemos fornecer "$filename:1" como localização da string. Os analisadores orientados a SAX usam globais e outros truques para salvar o nome do arquivo e os números de linha das referências.
One specific issue arises from file encodings and BOM markers. Simple parsers can forget about this issue, that is handled by TransTractor::read() (used internally to get the lines of an input document), but the modules relying on an external parser must ensure that all files are read with an appropriate PerlIO decoding layer. The easiest is to open the file yourself, and provide an filehandle or directly the full string to your external parser. Check on Pod::read() and Pod::parse() for an example. The content read by the TransTractor is ignored, but a fresh filehandle is passed to the external parser. The important part is the "<:encoding($charset)" mode that is passed to the open() perl function.
A classe Locale::Po4a::Po(3pm) é responsável por carregar e utilizar arquivos PO e POT. Basicamente, você pode ler um arquivo, adicionar entradas, obter traduções com o método gettext(), gravar o PO em um arquivo. Recursos mais avançados, como mesclar um arquivo PO com um arquivo POT ou validar um arquivo, são delegados a msgmerge e msgfmt respectivamente.
Mesmo que você nunca tenha contribuído para nenhum projeto de código aberto no passado, você é bem-vindo: estamos dispostos a ajudá-lo e orientá-lo aqui. po4a é melhor mantido por seus usuários hoje em dia. Como não temos mão de obra, procuramos tornar o projeto acolhedor melhorando a documentação e os testes automáticos para que você tenha confiança em contribuir com o projeto. Consulte o arquivo CONTRIBUTING.md para obter mais detalhes.
Aqui está uma lista bem parcial de projetos que usam po4a na produção para sua documentação. Se você quiser adicionar 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).
Eu pessoalmente vocalizo-o como pouah <https://en.wiktionary.org/wiki/pouah>, que é um onomatopoético francês que usamos no lugar de "eca" :) eu posso ter um senso de humor estranho :)
De fato, po4a-updatepo e po4a-translate foram descontinuados em favor de po4a. A razão é que, embora po4a possa ser usado como um substituto imediato para esses scripts, há muita duplicação de código aqui. Os scripts individuais duram cerca de 150 linhas de códigos, enquanto o programa po4a dura 1200 linhas, então eles fazem muito além dos internos comuns. A duplicação de código resulta em bugs ocorrendo em ambas as versões e necessitando de duas correções. Um exemplo dessa duplicação são os bugs #1022216 no Debian e o issue #442 no GitHub que tiveram exatamente a mesma correção, mas um em po4a e outro em po4a-updatepo.
No longo prazo, gostaria de descartar os scripts individuais e manter apenas uma versão deste código. O certo é que os scripts individuais não serão mais melhorados, então apenas po4a receberá os novos recursos. Dito isto, não há urgência na remoção. Pretendo manter os scripts individuais pelo maior tempo possível e pelo menos até 2030. Se o seu projeto ainda usa po4a-updatepo e po4a-translate em 2030, você pode ter um problema.
Também podemos remover a descontinuação desses scripts em algum momento, se uma refatoração reduzir a duplicação de código a zero. Se você tem uma ideia (ou melhor: um patch), sua ajuda é bem-vinda.
Existem alguns deles. Aqui está uma lista possivelmente incompleta e mais ferramentas estão surgindo no horizonte.
Ela só consegue manipular XML e apenas um DTD em particular. Eu fico, particularmente, não gosto das listas de manipulação, que acabam com um grande msgid. Quando a lista fica grande, o fragmento se torna mais difícil de engolir.
As principais vantagens do po4a sobre eles é a facilidade de adição de conteúdo extra (o que é bem pior lá) e a habilidade de alcançar gettextização.
- https://docs.kde.org/stable5/pt_BR/kdesdk/lokalize/project-view.html
- http://www.debian.org/intl/l10n/
Mas tudo tem seu lado negativo, e essa abordagem tem algumas desvantagens com as quais nós temos que lidar.
Um dos meus sonhos seria integrar de alguma forma po4a ao Gtranslator ou Lokalize. Quando um arquivo de documento fosse aberto, as strings seriam automaticamente extraídas e um arquivo traduzido + arquivo po poderia ser gravado no disco. Se nós conseguirmos fazer um módulo para MS Word (TM) (ou pelo menos RTF), tradutores profissionais podem até mesmo usá-lo.
Denis Barbier <barbier,linuxfr.org> Martin Quinson (mquinson#debian.org)
| 2024-08-06 | perl v5.38.2 |