PO4A.7(1) User Contributed Perl Documentation PO4A.7(1) NOME po4a - framework para traduzir documentacao e outros materiais Introducao po4a (PO for anything) facilita a manutencao da traducao de documentacao usando as ferramentas gettext classicas. A principal caracteristica do po4a e que ele dissocia a traducao do conteudo de sua estrutura documental. Este documento serve como uma introducao ao projeto po4a, com foco nos usuarios em potencial, considerando a possibilidade de usar essa ferramenta e no desejo curioso de entender por que as coisas sao do jeito que sao. Por que o po4a? A filosofia do software livre e tornar a tecnologia verdadeiramente disponivel para todos. Mas o licenciamento nao e a unica consideracao: o software livre nao traduzido e inutil para quem nao fala ingles. Portanto, ainda temos algum trabalho a fazer para disponibilizar o software para todos. Essa situacao e bem compreendida pela maioria dos projetos e agora todos estao convencidos da necessidade de traduzir tudo. No entanto, as traducoes reais representam um enorme esforco de muitas pessoas, prejudicadas por pequenas dificuldades tecnicas. Felizmente, o software de codigo aberto e realmente muito bem traduzido usando o conjunto de ferramentas gettext. Essas ferramentas sao usadas para extrair as strings a serem traduzidas de um programa e apresentar as strings em um formato padronizado (chamado de arquivos PO ou catalogos de traducao). Um ecossistema inteiro de ferramentas surgiu para ajudar os tradutores a traduzir esses arquivos PO. O resultado e usado pelo gettext no tempo de execucao para exibir mensagens traduzidas para os usuarios finais. Em relacao a documentacao, no entanto, a situacao ainda e um pouco decepcionante. No inicio, traduzir a documentacao pode parecer mais facil do que traduzir um programa, pois parece que voce apenas precisa copiar o arquivo-fonte da documentacao e comecar a traduzir o conteudo. No entanto, quando a documentacao original e modificada, acompanhar as modificacoes rapidamente se transforma em um pesadelo para os tradutores. Se realizada manualmente, esta tarefa e desagradavel e propensa a erros. Traducoes desatualizadas geralmente sao piores do que nenhuma traducao. Os usuarios finais podem ser enganados pela documentacao que descreve um comportamento antigo do programa. Alem disso, eles nao podem interagir diretamente com os mantenedores, pois nao falam ingles. Alem disso, o mantenedor nao pode resolver o problema, pois nao conhece todos os idiomas em que sua documentacao esta traduzida. Essas dificuldades, muitas vezes causadas por ferramentas precarias, podem minar a motivacao de tradutores voluntarios, agravando ainda mais o problema. O objetivo do projeto po4a e facilitar o trabalho dos tradutores de documentacao. Em particular, ele torna possivel manter traducoes de documentacoes. A ideia e reutilizar e adaptar a abordagem gettext a esse campo. Assim como o gettext, os textos sao extraidos de seus locais originais e apresentados aos tradutores como catalogos de traducao de pedidos. Os tradutores podem aproveitar as ferramentas gettext classicas para monitorar o trabalho a realizar, colaborar e organizar em equipe. O po4a injeta as traducoes diretamente na estrutura da documentacao para produzir arquivos de origem traduzidos que podem ser processados e distribuidos da mesma forma que os arquivos em ingles. Qualquer paragrafo que nao seja traduzido e deixado em ingles no documento resultante, garantindo que os usuarios finais nunca vejam uma traducao desatualizada na documentacao. Isso automatiza a maior parte do trabalho pesado da manutencao da traducao. A descoberta dos paragrafos que precisam de atualizacao se torna muito facil e o processo e completamente automatizado quando os elementos sao reordenados sem modificacoes adicionais. A verificacao especifica tambem pode ser usada para reduzir a chance de erros de formatacao que resultariam em um documento quebrado. Por favor, veja tambem o FAQ abaixo neste documento para uma lista mais completa de vantagens e desvantagens desta abordagem. Formatos suportados Atualmente, essa abordagem tem sido implementada com sucesso em varios formatos de formatacao de texto: man (analisador maduro) O bom e velho formato de paginas de manual, usado por muitos programas por ai. Suporte do po4a e muito bem-vindo, considerando que esse formato e de certa forma dificil de usar e nao exatamente amigavel para novatos. O modulo Locale::Po4a::Man(3pm) tambem possui suporte ao formato mdoc usado pelas paginas man do BSD (elas tambem sao bastante comuns no Linux). AsciiDoc (analisador maduro) Esse formato e um formato de marcacao leve, destinado a facilitar a criacao da documentacao. Por exemplo, e usado para documentar o sistema git. Essas paginas man sao traduzidas usando po4a. Veja Locale::Po4a::AsciiDoc para detalhes. pod (analisador maduro) Esse e o formato da documentacao online de Perl, ou Perl Online Documentation. A propria linguagem e extensoes sao documentadas usando este formato alem da maioria dos scripts Perl existentes. Isso facilita a manter a documentacao ferto do real codigo embutindo-os no mesmo arquivo. Isso torna a vida dos programadores mais facil, mas infelizmente, nao a do tradutor, ate voce usar o po4a. Veja Locale::Po4a::Pod para detalhes. sgml (analisador maduro) Mesmo que substituido pelo XML hoje em dia, esse formato ainda e usado para documentos que tem mais de algumas telas. Pode ate ser usado para livros completos. Documentos deste comprimento podem ser muito desafiadores para atualizar. diff muitas vezes revela inutil quando o texto original era recuado novamente apos a atualizacao. Felizmente, po4a pode lhe ajudar depois desse processo. Atualmente, ha suporte apenas ao DebianDoc e o DocBook DTD, mas a adicao de suporte a um novo e realmente facil. E possivel ate mesmo usar po4a em um SGML DTD desconhecido sem alterar o codigo, desde que sejam fornecidas as informacoes necessarias na linha de comando. Veja Locale::Po4a::Sgml(3pm) para mais detalhes. TeX / LaTeX (analisador maduro) O formato LaTeX e um formato de documentacao mais usado no mundo de software livre e para publicacoes. O modulo Locale::Po4a::LaTeX(3pm) foi testado com a documentacao do Python, um livro e algumas apresentacoes. text (analisador maduro) O formato Text e of formato base para muitos formatos que incluem longos blocos de texto, incluindo Markdown, fortunes, secao de pagina de rotos YAML, debian/changelog e debian/control. Este possui suporte ao formato comum usado em geradores de sites estaticos, READMEs e outros sistemas de documentacao. Consulte Locale::Po4a::Text(3pm) para detalhes. xml e XHMTL (analisador provavelmente maduro) O formato XML e um formato base para muitos formatos de documentacao. Atualmente, o DocBook DTD (veja Locale::Po4a::Docbook(3pm) para mais detalhes) e XHTML sao suportados pelo po4a. BibTex (analisador provavelmente maduro) O formato BibTex e usado junto com o LaTex para formatar listas de referencias (bibliografias). Veja Locale::Po4a::BibTex para detalhes. Docbook (analisador provavelmente maduro) Uma linguagem de marcacao baseada em XML que usa tags semanticas para descrever documentos. Veja Locale::Po4a:Docbook para mais detalhes. Guide XML (analisador provavelmente maduro) Um formato de documentacao XML. Este modulo foi desenvolvido especificamente para ajudar no suporte e manutencao de traducoes da documentacao do Gentoo Linux ate pelo menos marco de 2016 (baseado na maquina Wayback). Desde entao, o Gentoo mudou para o formato DevBook XML. Veja Locale::Po4a:Guide para mais detalhes. Wml (analisador provavelmente maduro) A Web Markup Language, nao confunda WML com o material WAP usado em telefones celulares. Este modulo depende do modulo Xhtml, que por sua vez depende do modulo XmL. Veja Locale::Po4a::Wml para mais detalhes. Yaml (analisador provavelmente maduro) Um superconjunto estrito de JSON. YAML e frequentemente usado como sistemas ou projetos de configuracao. YAML esta 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 documentacao padrao para Ruby e projetos Ruby antes de ser convertido para RDoc em 2002. Embora aparentemente a versao japonesa do Manual de Referencia Ruby ainda use RD. Veja Locale::Po4a::RubyDoc para mais detalhes. Halibut (analisador altamente experimental) Um sistema de producao de documentacao, com elementos semelhantes ao TeX, debiandoc-sgml, TeXinfo e outros, desenvolvido por Simon Tatham, o desenvolvedor do PuTTY. Veja Locale::Po4a:Halibut para mais detalhes. Ini (analisador altamente experimental) Formato de arquivo de configuracao popularizado pelo MS-DOS. Veja Locale::Po4a::Ini para mais detalhes. texinfo (analisador altamente experimental) Toda a documentacao do GNU e escrita neste formato (esse e ate mesmo um dos requisitos para se tornar um projeto GNU oficial). O suporte a Locale::Po4a::Texinfo(3pm) no po4a ainda esta nas fases iniciais. Por favor relate eventuais erros e requisicao por recursos. gemtext (analisador altamente experimental) O formato de texto simples nativo do protocolo Gemini. A extensao ".gmi" e comumente usada. O suporte para este modulo no po4a ainda esta em estagio muito inicial. Se voce encontrar alguma coisa, registre um relatorio de bug ou uma solicitacao de recurso. org (analisador altamente experimental) O formato de documento usado pelo modo Org. O suporte para este modulo no po4a ainda esta em estagio muito inicial. Se voce encontrar alguma coisa, registre um relatorio de bug ou uma solicitacao de recurso. vimhelp (analisador altamente experimental) O formato usado para arquivos de ajuda do Vim (e alguma documentacao do plugin de terceiros). O suporte para este formato em po4a ainda esta em sua infancia. Se voce encontrar alguma coisa, por favor, envie um relatorio de bug ou uma solicitacao de recurso. simplepod (analisador altamente experimental) Semelhante ao pod mencionado anteriormente, este adota o novo Pod::Simple como analisador. Como foi criado recentemente, alguns bugs sao esperados. Se notar algum comportamento estranho, por favor, nos avise. Eventualmente, este modulo substituira o pod. Outros formatos com suporte Po4a tambem pode manipular alguns formatos mais raros ou especializados, como a documentacao de opcoes de compilacao dos kernels Linux 2.4+ (Locale::Po4a::KernelHelp) ou diagramas produzidos pela ferramenta Dia (Locale::Po4a::Dia). A adicao de um novo formato e normalmente muito facil e a tarefa principal e fazer um analisador para seu formato alvo. Veja Locale::Po4a::TransTractor(3pm) para mais informacoes sobre isso. Formatos sem suporte Infelizmente, po4a ainda carece de suporte para varios formatos de documentacao. Muitos deles seriam faceis de dar suporte no po4a. Isso inclui formatos nao apenas usados para documentacao, como, descricoes de pacotes (deb e rpm), perguntas sobre scripts de instalacao de pacotes, changelogs de pacotes e todos os formatos de arquivo especializados usados por programas como cenarios de jogos ou arquivos de recursos de vinho. Usando po4a A maneira mais facil de usar esta ferramenta em seu projeto e escrever um arquivo de configuracao para o programa po4a e interagir apenas com este programa. Consulte sua documentacao, em po4a(1). O restante desta secao fornece mais detalhes para os usuarios avancados do po4a que desejam aprofundar sua compreensao. Esquema detalhado do fluxo de trabalho do po4a Certifique-se de ler po4a(1) antes desta secao excessivamente detalhada para obter uma visao 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 e um nome de exemplo para a documentacao a ser traduzida; XX.doc e o mesmo documento traduzido no idioma XX, enquanto doc.XX.po e o catalogo de traducoes desse documento no idioma XX. Os autores da documentacao se preocuparao principalmente com mestre.doc (que pode ser uma pagina man, um documento XML, um arquivo AsciiDoc etc.); os tradutores se preocuparao principalmente com o arquivo PO, enquanto os usuarios finais verao apenas o arquivo XX.doc. Transicoes com colchetes, como "[po4a atualiza po]", representam a execucao de uma ferramenta po4a, enquanto transicoes com chaves, como "{atualizacao do mestre.doc}", representam uma modificacao manual dos arquivos do projeto. mestre.doc | V +<-----<----+<-----<-----<--------+------->-------->-------+ : | | : {traducao} | {atualizacao 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 traducao.pot ^ V | | | doc.XX.po | | | (incerto) | {traducao} | | | | ^ V V | | {edicao manual} | | | | | V | V V doc.XX.po --->---->+<---<-- doc.XX.po adendo mestre.doc (inicial) (atualizado) (opcional) (atualizado) : | | | : V | | +----->----->----->------> + | | | | | V V V +------>-----+------<------+ | V [po4a atualiza traducoes] | V XX.doc (atualizado) Novamente, esse esquema e excessivamente complicado. Confira po4a(1) para uma visao geral simplificada. A parte esquerda mostra como po4a-gettextize(1) pode ser usado para converter um projeto de traducao existente para a infraestrutura do po4a. Este script pega um documento original e seu equivalente traduzido, e tenta construir o arquivo PO correspondente. Tal conversao manual e um pouco trabalhosa (veja a documentacao po4a-gettextize(1) para mais detalhes), mas so e necessaria uma vez para converter suas traducoes existentes. Se voce nao tem nenhuma traducao para converter, voce pode esquecer isso e focar na parte certa do esquema. Na parte superior direita, a acao do autor original esta descrita, atualizacao da documentacao. A parte do meio, a direita, representa as atualizacoes automaticas dos arquivos de traducao: os novos materiais sao extraidos e comparados com a traducao existente. A traducao anterior e usado para as partes que nao foram alteradas, enquanto partes parcialmente modificadas tambem sao conectadas a traducao anterior com uma marcacao "fuzzy" indicando que a traducao deve ser atualizada. Material novo ou muito modificado e deixado sem traducao. Entao, o bloco edicao manual representa a acao dos tradutores, que modificam os arquivo PO para fornecer traducoes para toda string e paragrafo originais. Isso pode ser feito usando um editor especifico, como o Editor de Traducao do GNOME, o Lokalize do KDE ou poedit, ou usando uma plataforma de localizacao online como o weblate ou pootle. O resultado da traducao e um conjunto de arquivos PO, um por idioma. Consulte a documentacao gettext para mais detalhes. A parte inferior da figura mostra como po4a cria um documento fonte traduzido do documento original mestre.doc e do catalogo de traducoes doc.XX.po que foram atualizados pelos tradutores . A estrutura do documento e reutilizada, enquanto o conteudo original e substituido por sua contraparte traduzida. Opcionalmente, um adendo pode ser usado para adicionar um texto extra a traducao. Isso geralmente e usado para adicionar o nome do tradutor ao documento final. Veja abaixo os detalhes. Apos a invocacao, po4a atualiza automaticamente os arquivos de traducao e os arquivos de documentacao traduzidos. Iniciando um novo projeto de traducao Se voce comeca do zero, basta escrever um arquivo de configuracao para po4a e pronto. Os modelos relevantes sao criados para os arquivos ausentes, permitindo que seus colaboradores traduzam seu projeto para o idioma deles. Consulte po4a(1) para um tutorial de inicio rapido e para todos os detalhes. Se voce ja possui uma traducao, ou seja, um arquivo de documentacao que foi traduzido manualmente, voce pode integrar seu conteudo em seu fluxo de trabalho po4a usando po4a-gettextize. Esta tarefa e um pouco complicada (conforme descrito na pagina de manual da ferramenta), mas assim que seu projeto for convertido para o fluxo de trabalho po4a, tudo sera atualizado automaticamente. Atualizando as traducoes e os documentos Apos a configuracao, invocar po4a e suficiente para atualizar os arquivos PO de traducao e os documentos traduzidos. Voce pode passar o "--no-translations" para po4a para nao atualizar as traducoes (atualizando apenas os arquivos PO) ou "--no-update" para nao atualizar os arquivos PO (atualizando apenas as traducoes). 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). Usando adendos para adicionar texto extra as traducoes Adicionar novo texto a traducao e provavelmente a unica coisa mais facil a longo prazo quando voce traduz arquivos manualmente :). Isso acontece quando voce deseja adicionar uma secao extra ao documento traduzido, que nao corresponde a nenhum conteudo no documento original. O caso de uso classico e dar creditos a equipe de traducao e indicar como relatar problemas especificos da traducao. Com o po4a, e necessario especificar os arquivos addendum, que podem ser vistos conceitualmente como patches aplicados ao documento localizado apos o processamento. Cada adendo deve ser fornecido como um arquivo separado, cujo formato e, no entanto, muito diferente dos patches classicos. A primeira linha e uma linha de cabecalho, definindo o ponto de insercao do adendo (com uma sintaxe infelizmente enigmatica -- veja abaixo) enquanto o restante do arquivo e adicionado literalmente na posicao determinada. A linha do cabecalho deve comecar com a string PO4A-HEADER:, seguida por uma lista separada por ponto e virgula dos campos chave=valor. Por exemplo, o cabecalho a seguir declara um adendo que deve ser colocado bem no final da traducao. PO4A-HEADER: mode=eof As coisas ficam mais complexas quando voce deseja adicionar seu conteudo extra no meio do documento. O cabecalho a seguir declara um adendo que deve ser colocado apos a secao XML que contem a string "Sobre este documento" na traducao. PO4A-HEADER: position=Sobre este documento; mode=after; endboundary= Na pratica, ao tentar aplicar um adendo, o po4a pesquisa a primeira linha correspondente ao argumento "position" (isso pode ser um regexp). Nao esqueca que o po4a considera o documento translated aqui. Esta documentacao esta em ingles, mas sua linha provavelmente deve ser a seguinte, se voce pretende que seu adendo se aplique a traducao em frances do documento. PO4A-HEADER: position=A propos de ce document; mode=after; endboundary= Depois que a "position" e encontrada no documento de destino, o po4a procura a proxima linha apos a "position" que corresponde ao "endboundary" fornecido. O adendo e adicionado a direita after essa linha (porque fornecemos um endboundary, ou seja, um limite que termina a secao atual). O exato mesmo efeito pode ser obtido com o seguinte cabecalho, que e equivalente: PO4A-HEADER: position=About this document; mode=after; beginboundary=
Aqui, o po4a pesquisa a primeira linha correspondente a "
" apos a linha correspondente a "About this document" na traducao e adicione o adendo before dessa linha, pois fornecemos um beginboundary, ou seja, um limite que marca o inicio da proxima secao. Portanto, essa linha de cabecalho exige a insercao do adendo apos a secao que contem "About this document" e instrui o po4a que uma secao comeca com uma linha que contem a tag "
". Isso e equivalente ao exemplo anterior, porque o que voce realmente deseja e adicionar este adendo apos "
" ou antes de "
". Voce tambem pode definir a insercao modo como o valor "before", com uma semantica semelhante: a combinacao de "mode=before" com um "endboundary" colocara o adendo apenas after o limite correspondente, que e a ultima linha limite potencial antes da "position". Combinar "mode=before" com um "beginboundary" colocara o adendo apenas before do limite correspondente, que e a ultima linha limite potencial antes da "position". Modo | Tipo de limite | Limite usado | Ponto de insercao am comparacao ao limite ========|================|============================|========================================== 'before'| 'endboundary' | ultimo antes de 'position' | Logo apos o limite selecionado 'before'|'beginboundary' | ultimo antes de 'position' | Logo antes do limite selecionado 'after' | 'endboundary' | primeiro apos 'position' | Logo apos o limite selecionado 'after' |'beginboundary' | primeiro apos 'position' | Logo antes do limite selecionado 'eof' | (none) | n/d | Fim do arquivo Dicas e truques sobre adendos o Lembre-se de que estes sao regexp. Por exemplo, se voce deseja combinar o final de uma secao nroff que termina com a linha ".fi", nao use ".fi" como endboundary porque ele vai corresponder a "the[ fi]le", o que obviamente nao e o que esta esperando. O endboundary correto neste caso e: "^\.fi$". o Espacos em branco SAO importantes no conteudo da "position" e limites. Portanto, as duas linhas seguintes sao diferentes. O segundo so sera encontrado se houver espacos a direita suficientes no documento traduzido. PO4A-HEADER: position=Sobre este documento; mode=after; beginboundary=
PO4A-HEADER: position=Sobre este documento ; mode=after; beginboundary=
o Embora essa pesquisa de contexto possa ser considerada como operando aproximadamente em cada linha do documento traduzido, ela realmente opera na cadeia de dados interna do documento traduzido. Essa cadeia de dados interna pode ser um texto abrangendo um paragrafo contendo varias linhas ou pode ser uma tag XML sozinha. O exato ponto de insercao do adendo deve ser anterior ou posterior a sequencia de dados interna e nao pode estar dentro da cadeia de dados interna. o Passe o argumento "-vv" para o po4a para entender como os adendos sao adicionados a traducao. Tambem pode ajudar a executar po4a no modo de depuracao para ver a string de dados interna real quando o seu adendo nao se aplica. Exemplos de adendos o Se voce quiser adicionar alguma coisa apos a secao nroff a seguir: .SH "AUTHORS" Voce deve selecionar uma abordagem em duas etapas configurando mode=after. Em seguida, voce deve restringir a pesquisa a linha apos AUTHORS com a regex de argumento position. Entao, voce deve combinar o inicio da proxima secao (isto e, ^ \. SH) com a regex de argumento beginboundary. Isso e para dizer: PO4A-HEADER:mode=after;position=AUTORES;beginboundary=\.SH o Se voce quiser adicionar alguma coisa apos a linha dada (ex,. apos a linha "Copyright Grande Cara") use um position correspondendo a esta linha, mode=after e forneca um beginboundary correspondendo a qualquer linha. PO4A-HEADER:mode=after;position=Copyright Grande Cara, 2004;beginboundary=^ o Se voce quiser adicionar alguma coisa ao final do documento, forneca um position correspondendo a qualquer linha do seu documento (mas apenas uma linha. Po4a nao vai proceder se ela nao for unica), e forneca um endboundary correspondendo a nada. Nao use strings simples aqui como "EOF", e sim prefira aquelas que possuem menos chance de estar no seu documento. 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 Entao, o adendo a seguir vai assegurar que a secao (em Frances) sobre o tradutor seja adicionado ao final do arquivo (em Frances, "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 cabecalho: PO4A-HEADER:mode=after;position=NOM;beginboundary=^=head1 Isso funciona porque a proxima linha correspondendo ao beginboundary "/^=head1/" apos a secao "NAME" (traduzido para "NOM" em Frances) e aquela declarando os autores. Entao, o adendo sera colocado entre as duas secoes. Note que se outra secao for adicionada entre as secoes NAME e AUTHOR posteriormente, po4a colocara o adendo equivocadamente antes da nova secao. Para evitar isto, voce pode realizar o mesmo usando mode=before: PO4A-HEADER:mode=before;position=^=head1 AUTEUR Como ele funciona? Este capitulo da a voce uma visao geral da parte interna do po4a, de forma que voce pode se sentir mais confiante para nos ajudar a mante-lo e melhora-lo. Ele tambem pode ajuda-lo a entender o porque de ele nao funcionar da forma que voce esperava, e como resolver seus problemas. TransTractors e arquitetura do projeto No centro do projeto do po4a, a classe Locale::Po4a::TransTractor(3pm) e um antepassado comum para todos analisadores do po4a. Esse nome estranho vem do fato que ele e ao mesmo tempo o encarregado por traducao de documento e extracao de strings. Mais formalmente, ele pega um documento para traduzir mais um arquivo PO contendo as traducoes para usar como entrada, enquanto produz duas saidas separadas: outro arquivo PO (resultante da extracao das strings traduziveis do documento de entrada) e um documento traduzido (com a mesma estrutura que a da entrada, mas com todas as strings traduziveis substituidas com o conteudo do PO de entrada). Aqui esta uma representacao grafica disso: Doc. de entrada --\ /---> Doc. de saida \ TransTractor:: / (traduzido) +-->-- parse() --------+ / \ PO de entrada ----/ \---> PO de saida (extraido) Este ossinho e o nucleo de toda a arquitetura po4a. Se voce fornecer a entrada e desconsiderar o PO de saida, obtera po4a-translate. Se voce desconsiderar o documento de saida, obtera po4a-updatepo. O po4a usa um primeiro TransTractor para obter um arquivo POT de saida atualizado (desconsiderando os documentos de saida), chama msgmerge -U para atualizar os arquivos PO de traducao no disco e constroi um segundo TransTractor com estes arquivos PO atualizados para atualizar os documentos de saida. Resumindo, po4a fornece uma solucao completa para atualizar o que precisa ser, usando um unico arquivo de configuracao. po4a-gettextize tambem usa dois TransTractors, mas de outra forma: ele constroi um TransTractor por idioma e entao constroi um novo arquivo PO usando os msgids do documento original como msgids, e os msgids do documento traduzido como msgstrs. E necessario muito cuidado para garantir que as strings correspondidas desta forma realmente correspondam, conforme descrito em po4a-gettextize(1). Analisadores sintaticos especificos de formatos Todos os analisadores de formato po4a sao implementados no TransTractor. Alguns deles sao muito simples, como os Text, Markdown e AsciiDoc. Eles carregam as linhas uma por uma usando TransTractor::shiftline(), acumulam o conteudo dos paragrafos ou algo assim. Depois que uma string e completamente analisada, o analisador usa TransTractor::translate() para (1) adicionar essa string ao arquivo PO de saida e (2) obter a traducao do arquivo PO de entrada. O analisador entao envia o resultado para o arquivo de saida usando TransTractor::pushline(). Alguns outros analisadores sao mais complexos porque dependem de um analisador externo para analisar o documento de entrada. Os analisadores Xml, HTML, SGML e Pod sao construidos com base nos analisadores SAX. Eles declaram retornos de chamada para eventos como "Encontrei um novo titulo cujo conteudo e o seguinte" para atualizar o documento de saida e gerar arquivos POT de acordo com o conteudo de entrada usando TransTractor::translate() e TransTractor::pushline(). O analisador Yaml e semelhante, mas diferente: ele serializa uma estrutura de dados produzida pelo analisador YAML::Tiny. E por isso que o modulo Yaml do po4a falha ao declarar as linhas de referencia: a localizacao de cada string no arquivo de entrada nao e mantida pelo analisador, entao so podemos fornecer "$filename:1" como localizacao da string. Os analisadores orientados a SAX usam globais e outros truques para salvar o nome do arquivo e os numeros de linha das referencias. Um problema especifico surge das codificacoes de arquivos e dos marcadores BOM. Analisadores simples podem esquecer esse problema, que e tratado por TransTractor::read() (usado internamente para obter as linhas de um documento de entrada), mas os modulos que dependem de um analisador externo devem garantir que todos os arquivos sejam lidos com uma camada de decodificacao PerlIO apropriada. O mais facil e abrir o arquivo voce mesmo e fornecer um identificador de arquivo ou diretamente a string completa para seu analisador externo. Verifique Pod::read() e Pod::parse() para obter um exemplo. O conteudo lido pelo TransTractor e ignorado, mas um novo identificador de arquivo e passado para o analisador externo. A parte importante e o modo "<:encoding($charset)" que e passado para a funcao perl open(). Objetos PO A classe Locale::Po4a::Po(3pm) e responsavel por carregar e utilizar arquivos PO e POT. Basicamente, voce pode ler um arquivo, adicionar entradas, obter traducoes com o metodo gettext(), gravar o PO em um arquivo. Recursos mais avancados, como mesclar um arquivo PO com um arquivo POT ou validar um arquivo, sao delegados a msgmerge e msgfmt respectivamente. Contribuindo para o po4a Mesmo que voce nunca tenha contribuido para nenhum projeto de codigo aberto no passado, voce e bem-vindo: estamos dispostos a ajuda-lo e orienta-lo aqui. po4a e melhor mantido por seus usuarios hoje em dia. Como nao temos mao de obra, procuramos tornar o projeto acolhedor melhorando a documentacao e os testes automaticos para que voce tenha confianca em contribuir com o projeto. Consulte o arquivo CONTRIBUTING.md para obter mais detalhes. Projetos de codigo aberto que usam o po4a Aqui esta uma lista bem parcial de projetos que usam po4a na producao para sua documentacao. Se voce quiser adicionar seu projeto a lista, basta nos enviar um e-mail (ou uma merge request). o adduser (man): ferramenta de gerenciamento de usuarios e grupos. o apt (man, docbook): Gerenciador de pacotes do Debian. o aptitude (docbook, svg): Gerenciador de pacotes em interface de texto para Debian o Site do F-Droid (markdown): catalogo instalavel de aplicativos FOSS (abreviacao de software livre e de codigo aberto) para a plataforma Android. o git (asciidoc): sistema de controle de versao distribuido para alteracoes de rastreamento em codigo-fonte. o Paginas man do Linux (man) Este projeto fornece uma infraestrutura para traduzir muitas paginas man para diferentes idiomas, prontas para integracao em varias grandes distribuicoes (Arch Linux, Debian e derivados, Fedora). o Stellarium (HTML): um planetario de codigo aberto e livre para o seu computador. po4a e usado para traduzir as descricoes da cultura do ceu. o Jamulus (markdown, yaml, HTML): um aplicativo FOSS para jamming online em tempo real. A documentacao do site e mantida em varios idiomas usando po4a. o Outro item para resolver: FAQ Como voce pronuncia po4a? Eu pessoalmente vocalizo-o como pouah , que e um onomatopoetico frances que usamos no lugar de "eca" :) eu posso ter um senso de humor estranho :) Por que os scripts individuais foram descontinuados? De fato, po4a-updatepo e po4a-translate foram descontinuados em favor de po4a. A razao e que, embora po4a possa ser usado como um substituto imediato para esses scripts, ha muita duplicacao de codigo aqui. Os scripts individuais duram cerca de 150 linhas de codigos, enquanto o programa po4a dura 1200 linhas, entao eles fazem muito alem dos internos comuns. A duplicacao de codigo resulta em bugs ocorrendo em ambas as versoes e necessitando de duas correcoes. Um exemplo dessa duplicacao sao os bugs #1022216 no Debian e o issue #442 no GitHub que tiveram exatamente a mesma correcao, mas um em po4a e outro em po4a-updatepo. No longo prazo, gostaria de descartar os scripts individuais e manter apenas uma versao deste codigo. O certo e que os scripts individuais nao serao mais melhorados, entao apenas po4a recebera os novos recursos. Dito isto, nao ha urgencia na remocao. Pretendo manter os scripts individuais pelo maior tempo possivel e pelo menos ate 2030. Se o seu projeto ainda usa po4a-updatepo e po4a-translate em 2030, voce pode ter um problema. Tambem podemos remover a descontinuacao desses scripts em algum momento, se uma refatoracao reduzir a duplicacao de codigo a zero. Se voce tem uma ideia (ou melhor: um patch), sua ajuda e bem-vinda. E as outras ferramentas de traducao para documentacao usando gettext? Existem alguns deles. Aqui esta uma lista possivelmente incompleta e mais ferramentas estao surgindo no horizonte. poxml Essa e a ferramenta desenvolvida pelo pessoal do KDE para manipular DocBook XML. Ate onde eu sei, esse foi o primeiro programa a extrair strings para traduzir de documentacao para arquivos PO, e a injeta-las de volta apos a traducao. Ela so consegue manipular XML e apenas um DTD em particular. Eu fico, particularmente, nao gosto das listas de manipulacao, que acabam com um grande msgid. Quando a lista fica grande, o fragmento se torna mais dificil de engolir. po-debiandoc Esse problema desenvolvido por Denis Barbier e uma especie de precursor do modulo de SGML do po4a, o qual meio que torna-o (po-debiandoc) obsoleto. Como o nome ja diz, ele linda apenas o DebianDoc DTD, o qual e meio que um DTD obsoleto. xml2po.py Usado pela equipe de documentacao do GIMP desde 2004, funciona muito bem mesmo que, como o nome sugere, apenas com arquivos XML e precise de makefiles especialmente configurados. Sphinx O Projeto de Documentacao Sphinx tambem usa gettext extensivamente para gerenciar suas traducoes. Infelizmente funciona apenas para alguns formatos de texto, rest e markdown, embora seja talvez a unica ferramenta que faz isso gerenciando todo o processo de traducao. As principais vantagens do po4a sobre eles e a facilidade de adicao de conteudo extra (o que e bem pior la) e a habilidade de alcancar gettextizacao. RESUMO das vantagens da abordagem baseada em gettext o As traducoes nao sao armazenadas junto do original, o que possibilita detectar se as traducoes estao desatualizadas. o As traducoes sao armazenadas em arquivos separados um dos outros, o que previne tradutores de idiomas diferentes interferir tanto quando da submissao do patch quanto a nivel de codificacao do arquivo. o Ele e internamente baseado no gettext (mas po4a oferece uma interface bem simples, de forma que voce nao precisa entender as especificidades para usa-lo). Dessa forma, nos nao temos que reinventar a roda e, por causa do seu amplo uso, nos podemos pensar que essas ferramentas meio que nao tem erros. o Nada mudou para o usuario final (alem do fato de traducoes estarem melhor mantidas, espero). o arquivo de documentacao resultante distribuido e exatamente o mesmo. o Nao ha necessidade de tradutores aprenderem um novo arquivo de sintaxe e seu editor de arquivos PO (como o modo PO do Emacs, Lokalize ou Gtranslator) vao funcionar muito bem. o gettext oferece uma forma simples de obter estatisticas sobre o que esta feito, o que deveria ser revisto e atualizado e o que ainda deve ser feito. Alguns exemplos podem ser encontrados nesses enderecos: - 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 nos temos que lidar. o Os adendos sao meio que estranhos a primeira vista. o Voce nao pode adaptar o texto traduzido as suas preferencias, com divisao de um paragrafo aqui e juntar outros dois ali. Mas de certa forma, se ha um problema com o original, isso deveria ser relatado como um erro. o Ate mesmo com uma interface facil, ainda e uma nova ferramenta que as pessoas precisam aprender. Um dos meus sonhos seria integrar de alguma forma po4a ao Gtranslator ou Lokalize. Quando um arquivo de documento fosse aberto, as strings seriam automaticamente extraidas e um arquivo traduzido + arquivo po poderia ser gravado no disco. Se nos conseguirmos fazer um modulo para MS Word (TM) (ou pelo menos RTF), tradutores profissionais podem ate mesmo usa-lo. VEJA TAMBEM o A documentacao da ferramenta multifuncional que voce deve usar: po4a(1). o A documentacao dos scripts individuais do po4a: po4a-gettextize(1), po4a-updatepo(1), po4a-translate(1), po4a-normalize(1). o Os scripts de ajuda adicionais: msguntypot(1), po4a-display-man(1), po4a-display-pod(1). o Os analisadores de cada formato, em particular para ver as opcoes aceitas por cada um deles: Locale::Po4a::AsciiDoc(3pm) Locale::Po4a::Dia(3pm), Locale::Po4a::Gemtext(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::Org(3pm), Locale::Po4a::Pod(3pm), Locale::Po4a::SimplePod(3pm), Locale::Po4a::Sgml(3pm), Locale::Po4a::TeX(3pm), Locale::Po4a::VimHelp, Locale::Po4a::Wml(3pm), Locale::Po4a::Xml(3pm). o A implementacao da infraestrutura principal: Locale::Po4a::TransTractor(3pm) (particularmente importante para entender a organizacao do codigo), Locale::Po4a::Chooser(3pm), Locale::Po4a::Po(3pm), Locale::Po4a::Common(3pm). Por favor, verifique tambem o arquivo CONTRIBUTING.md na arvore de fonts. AUTORES Denis Barbier Martin Quinson (mquinson#debian.org) TRADUCAO Luiz Fernando Ranghetti Rafael Fontenelle perl v5.42.0 2025-11-22 PO4A.7(1)