PO4A.7(1) User Contributed Perl Documentation PO4A.7(1) NOME po4a - infraestrutura para traduzir documentacao e outros materiais Introducao po4a (PO for anything) facilita a manutencao da traducoes de documentacao a usar as ferramentas gettext classicas. A caracteristica principal do po4a e que dissocia a traducao do conteudo da estrutura documental dele. Este documento serve como uma introducao ao projeto po4a focado em potenciais utilizadores que considerem a possibilidade de usar essa ferramenta e no desejo curioso de perceber por que as coisas sao como sao. Porque o po4a? A filosofia do Software Livre e fazer a tecnologia verdadeiramente disponivel a todos. Mas o licenciamento nao e a unica consideracao: software livre nao traduzido e inutil para quem nao fala ingles. Portanto, ainda temos algum trabalho a fazer para fazer o software disponivel a 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 Open Source e, na verdade, muito bem traduzido a usar o conjunto de ferramentas gettext. Essas ferramentas sao usadas para extrair as cadeias a traduzir de um programa e apresentar as cadeias a traduzir num formato padronizado (chamado de ficheiros PO ou catalogos de traducao). Todo um ecossistema de ferramentas surgiu para ajudar os tradutores a realmente traduzir esses ficheiros PO. O resultado e entao utilizado pela gettext em tempo de execucao para exibir as mensagens traduzidas para os utilizadores 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 apenas precisa copiar o ficheiro-fonte da documentacao e comecar a traduzir o conteudo. No entanto, quando a documentacao original e modificada, acompanhar as modificacoes rapidamente se transforma num 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 utilizadores 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 a documentacao deles esta traduzida. Essas dificuldades, muitas vezes causadas por ferramentas precarias, podem minar a motivacao de tradutores voluntarios, a agravar o problema ainda mais. O objetivo do projeto po4a e facilitar o trabalho dos tradutores de documentacao. Em particular, torna as traducoes de documentacoes possiveis de manter. A ideia e de reutilizar e adaptar a abordagem gettext a esse campo. Assim como o gettext, os textos sao extraidos dos 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 equipa. O po4a injeta as traducoes diretamente na estrutura da documentacao para produzir ficheiros de origem traduzidos que podem ser processados e distribuidos da mesma forma que os ficheiros em ingles. Qualquer paragrafo que nao seja traduzido e deixado em ingles no documento resultante, a garantir que os utilizadores 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 torna-se 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 hipotese de erros de formatacao que resultariam num documento quebrado. Por favor, consulte tambem o FAQ abaixo neste documento para uma lista mais completa das vantagens e desvantagens desta abordagem. Formatos suportados Atualmente, esta abordagem tem sido implementada com sucesso para varios tipos de formatos de formatacao de texto: man (analisador maduro) O bom e velho formato de paginas de manual, usado por muitos programas por ai. O suporte ao po4a e muito bem-vindo pois este formato e de certa forma dificil de usar e realmente nao amigavel para novatos. O modulo Locale::Po4a::Man(3pm) tambem possui suporte do formato mdoc usado pelas paginas man do BSD (elas tambem sao bastante comuns no Linux). AsciiDoc (analisador maduro) Esse formato e um formato de markup 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) Este e o formato de Documentacao Perl Online. A linguagem e as proprias extensoes sao documentadas a usar este formato, alem da maioria dos scripts Perl existentes. Torna facil manter a documentacao perto do codigo real, a incorpora-los ambos no mesmo ficheiro. Torna a vida do programador mais facil, mas infelizmente nao a do tradutor, ate que use o po4a. Veja Locale::Po4a::Pod para detalhes. sgml (analisador maduro) Mesmo que hoje em dia seja substituido pelo XML, este formato ainda e utilizado para documentos com o comprimento de mais do que alguns ecras. Pode ate mesmo ser usado para livros inteiros. Pode ser muito desafiador de atualizar documentos deste tamanho. diff frequentemente revela-se inutil quando o texto original foi reintroduzido apos a atualizacao. Felizmente, o po4a pode ajuda-lo apos esse processo. Atualmente, apenas os DTD DebianDoc e DocBook sao suportados, mas a acrescentar suporte para um novo e muito simples. E ate possivel usar po4a num SGML DTD desconhecido sem alterar o codigo, a fornecer as necessarias informacoes sobre a linha de comando. Veja Locale::Po4a::Sgml(3pm) para mais detalhes. TeX / LaTeX (analisador maduro) O formato LaTeX e o formato de documentacao principal usado nas publicacoes de Software Livre mundiais. O modulo Locale::Po4a::LaTeX(3pm) foi testado com a documentacao Python, um livro e algumas apresentacoes. text (analisador maduro) O formato Text e o formato base para muitos formatos que incluem longos blocos de texto, incluindo Markdown, fortunes, seccao de pagina de rotos YAML, debian/changelog e debian/control. Este possui suporte do 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 detalhes) e o 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 etiquetas 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 nucleo 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 provavelmente experimental) Um sistema de producao de documentacao, 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 provavelmente experimental) Formato de ficheiro de configuracao popularizado pelo MS-DOS. Veja Locale::Po4a::Ini para mais detalhes. texinfo (analisador altamente experimental) Toda a documentacao GNU esta escrita neste formato (ainda e um dos requisitos para um projeto GNU se tornar oficial). O apoio para Locale::Po4a::Texinfo(3pm) em po4a ainda esta no inicio. Por favor, reporte erros e solicitacoes de 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 encontrar alguma coisa, registe um relatorio de bug ou uma solicitacao de recurso. org (analisador altamente experimental) O formato de documento usado pelo modo Org. Apoio para este modulo em po4a continua na sua infancia. Se encontrar alguma coisa, por favor crie um bug ou uma solicitacao de recurso. vimhelp (analisador altamente experimental) O formato usado para ficheiros de ajuda do Vim (e alguma documentacao do plugin de terceiros). O suporte para este formato em po4a ainda esta na sua infancia. Se encontrar algo, por favor envie um relatorio de bug ou uma solicitacao de recurso. simplepod (analisador altamente experimental) Semelhante ao anteriormente mencionado pod, este adota o novo Pod::Simple como seu analisador. Como e criacao recente, sao esperados alguns bugs. Se voce notar qualquer comportamento estranho, por favor diga-nos. Eventualmente, este modulo ira substituir o pod. Outros formatos suportados 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 o seu formato alvo. Veja Locale::Po4a::TransTractor(3pm) para mais informacoes sobre isto. Formatos nao suportados Infelizmente, o po4a ainda carece suporte para varios formatos de documentacao. Muitos deles facilmente seriam suportados pelo po4a. Isto inclui formatos nao apenas usados para documentacao, tais como, descricoes de pacotes (deb e rpm), questoes de scripts de instalacao de pacotes, changelogs de pacotes e todos os formatos de ficheiros especializados usados por programas como cenarios de jogos ou ficheiros de recursos do wine. Usar o po4a A maneira mais facil de usar esta ferramenta no seu projeto e escrever um ficheiro de configuracao para o programa po4a e interagir apenas com este programa. Consulte a sua documentacao, em po4a(1). O restante desta seccao fornece mais pormenores para os utilizadores avancados do po4a que desejam aprofundar a sua compreensao. Esquema detalhado do fluxo de trabalho do po4a Certifique-se de ler po4a(1) antes desta seccao 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 pormenores. No esquema a seguir, master.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 master.doc (que pode ser uma pagina man, um documento XML, um ficheiro AsciiDoc etc.); os tradutores se preocuparao principalmente com o ficheiro PO, enquanto os utilizadores finais verao apenas o ficheiro XX.doc. Transicoes com parenteses retos, como "[po4a atualiza po]", representam a execucao de uma ferramenta po4a, enquanto transicoes com chavetas, como "{atualizacao do mestre.doc}", representam uma modificacao manual dos ficheiros 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, este 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 leva um documento original e o equivalente traduzido e tenta construir o ficheiro 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 as suas traducoes existentes. Se nao tiver nenhuma traducao para converter, pode esquecer-se disto e focar-se 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 ficheiros de traducao: os novos materiais sao extraidos e comparados com a traducao existente. A traducao anterior e usada 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 ficheiro PO para fornecer traducoes para toda cadeias e paragrafo originais. Isto 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 ficheiros PO, um por idioma. Consulte a documentacao gettext para mais pormenores. A parte inferior da figura mostra como po4a cria um documento fonte traduzido do documento original master.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 pela contraparte dele traduzida. Opcionalmente, um adendo pode ser usado para adicionar textos 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 ficheiros de traducao e os ficheiros de documentacao traduzidos. Iniciar um novo projeto de traducao Se comeca do zero, basta escrever um ficheiro de configuracao para po4a e pronto. Os modelos relevantes sao criados para os ficheiros ausentes, permitindo que os seus colaboradores traduzam o seu projeto para o idioma deles. Consulte po4a(1) para um tutorial de inicio rapido e para todos os pormenores. Se ja possui uma traducao, ou seja, um ficheiro de documentacao que foi traduzido manualmente, pode integrar o seu conteudo no seu fluxo de trabalho po4a usando po4a-gettextize. Esta tarefa e um pouco complicada (conforme descrito no manual da ferramenta), mas assim que o seu projeto for convertido para o fluxo de trabalho po4a, tudo sera atualizado automaticamente. Atualizar as traducoes e os documentos Apos a configuracao, invocar po4a e suficiente para atualizar os ficheiros PO de traducao e os documentos traduzidos. Pode passar o "--no-translations" para po4a para nao atualizar as traducoes (atualizando apenas os ficheiros PO) ou "--no-update" para nao atualizar os ficheiros PO (atualizando apenas as traducoes). Isto 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 textos as traducoes Adicionar novos textos a traducao e provavelmente a unica coisa mais facil a longo prazo quando traduz ficheiros manualmente :). Isso acontece quando deseja adicionar uma seccao adicional ao documento traduzido, que nao corresponde a nenhum conteudo no documento original. O caso de uso classico e dar merito a equipa de traducao e indicar como relatar problemas especificos da traducao. Com o po4a, e necessario especificar os ficheiros addendum, que podem ser vistos conceitualmente como patches aplicados ao documento localizado apos o processamento. Cada adendo deve ser fornecido como um ficheiro separado, cujo formato e, no entanto, muito diferente dos patches classicos. A primeira linha e uma linha de cabecalho, a definir o ponto de insercao do adendo (com uma sintaxe infelizmente enigmatica -- veja abaixo) enquanto o restante do ficheiro e adicionado literalmente na posicao determinada. A linha do cabecalho deve comecar com a cadeia 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 posto bem no final da traducao. PO4A-HEADER: mode=eof As coisas ficam mais complexas quando deseja adicionar o seu conteudo adicional no meio do documento. O cabecalho a seguir declara um adendo que deve ser posto apos a seccao XML que contem a cadeia "About this document" na traducao. PO4A-HEADER: position=Acerca deste 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 se esqueca que o po4a considera o documento translated aqui. Esta documentacao e em Ingles, mas a sua linha provavelmente deve ser a seguinte, se pretende que o seu adendo se aplique a traducao do documento em Frances. PO4A-HEADER: position=A propos de ce document; mode=after; endboundary= Depois que a "position" foi 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 seccao atual). O exato mesmo efeito pode ser obtido com o cabecalho seguinte, que e equivalente: PO4A-HEADER: position=Sobre este documento; 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 seccao. Portanto, esta linha de cabecalho exige a insercao do adendo apos a seccao que contem "About this document" e instrui o po4a que uma seccao comeca com uma linha que contem a tag "
". Isto e equivalente ao exemplo anterior, porque o que realmente deseja e adicionar este adendo apos "
" ou antes de "
". Tambem pode definir a insercao modo como o valor "before", com uma semantica semelhante: a combinacao de "mode=before" com um "endboundary" pora o adendo apenas after o limite correspondente, que e a ultima linha limite potencial antes da "position". Combinar "mode=before" com um "beginboundary" pora 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 ficheiro Dicas e truques sobre adendos o Lembre-se que estes sao regexp. Por exemplo, se quiser combinar o final de uma seccao nroff a terminar com a linha ".fi", nao use ".fi" como endboundary, porque ele ira combinar com "the[ fi]le", que obviamente nao e o que espera. O endboundary correto, nesse caso, e: "^\.fi$". o Espacos em branco SAO importantes no conteudo da "position" e limites. Portanto, as duas linhas seguintes are different. O segundo so sera encontrado se houver espacos suficientes a direita no documento traduzido. PO4A-HEADER: position=Acerca deste documento; mode=after; beginboundary=
PO4A-HEADER: position=Acerca deste documento ; mode=after; beginboundary=
o Embora essa pesquisa de contexto possa ser considerada para 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 paragrafo que contem varias linhas ou pode ser uma marcacao 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 perceber como os adendos sao adicionados a traducao. Tambem pode ajudar a executar po4a no modo de depuracao para ver a cadeia de dados interna real quando o seu adendo nao se aplica. Exemplos de adendos o Se quiser acrescentar algo depois na seccao seguinte nroff: .SH "AUTORES" Deve selecionar uma abordagem em duas etapas configurando mode=after. Em seguida, deve restringir a pesquisa a linha apos AUTHORS com a regex de argumento position. Entao, deve combinar o inicio da proxima seccao (isto e, ^\.SH) com a regex de argumento beginboundary. E para dizer: PO4A-HEADER:mode=after;position=AUTORES;beginboundary=\.SH o Se quiser adicionar algo logo apos uma determinada linha (por exemplo, apos a linha "Copyright Big Dude"), use uma position a corresponder a esta linha, mode=after e de um beginboundary a corresponder a qualquer linha. PO4A-HEADER:mode=after;position=Copyright Big Dude, 2004;beginboundary=^ o Se quiser adicionar alguma coisa no final do documento, de uma position correspondente a qualquer linha do seu documento (mas apenas uma linha, po4a nao continuara se nao e unica) e de uma endboundary sem corresponder a nada. Aqui nao use cadeias simples como "EOF", mas prefira as que tem menos hipotese de estar no seu documento. PO4A-HEADER:mode=after;position=Sobre este documento;beginboundary=FakePo4aBoundary Exemplo mais detalhado Documento original (POD formatado): |=head1 NOME | |ficticio - um programa ficticio | |=head1 AUTOR | |eu Entao, a adenda a seguir ira garantir que uma seccao (em frances) sobre o tradutor e adicionado no final do processo (em frances, "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 cabecalho: PO4A-HEADER:mode=after;position=NOM;beginboundary=^=head1 Isto funciona porque a proxima linha correspondendo ao beginboundary "/^=head1/" apos a seccao "NAME" (traduzido para "NOM" em Frances) e aquela declarando os autores. Entao, o adendo sera posto entre as duas seccoes. Note que se outra seccao for adicionada entre as seccoes NAME e AUTHOR posteriormente, po4a pora o adendo equivocadamente antes da nova seccao. Para evitar isto, pode realizar o mesmo a usar mode=before: PO4A-HEADER:mode=before;position=^=head1 AUTEUR Como e que funciona? Este capitulo da a uma visao geral da parte interna do po4a, de forma que pode sentir-se mais confiante para nos ajudar a mante-lo e melhora-lo. Ele tambem pode ajuda-lo a perceber o porque de ele nao funcionar da forma que esperava e como resolver os 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. Este nome estranho vem do fato que ele e ao mesmo tempo o encarregado por traducao de documento e extracao de cadeias. Mais formalmente, ele leva um documento para traduzir mais um ficheiro PO contendo as traducoes para usar como entrada, enquanto produz duas saidas separadas: outro ficheiro PO (resultante da extracao das cadeias traduziveis do documento de entrada) e um documento traduzido (com a mesma estrutura que a da entrada, mas com todas as cadeias 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 fornecer a entrada e desconsiderar o PO de saida, obtera po4a-translate. Se desconsiderar o documento de saida, obtera po4a-updatepo. O po4a usa um primeiro TransTractor para obter um ficheiro POT de saida atualizado (desconsiderando os documentos de saida), chama msgmerge -U para atualizar os ficheiros PO de traducao no disco e constroi um segundo TransTractor com estes ficheiros PO atualizados para atualizar os documentos de saida. Resumindo, po4a fornece uma solucao completa para atualizar o que precisa ser, usando um unico ficheiro de configuracao. po4a-gettextize tambem usa dois TransTractors, mas de outra forma: ele constroi um TransTractor por idioma e entao constroi um novo ficheiro 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 cadeias 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 cadeia e completamente analisada, o analisador usa TransTractor::translate() para (1) adicionar esta cadeia ao ficheiro PO de saida e (2) obter a traducao do ficheiro PO de entrada. O analisador entao envia o resultado para o ficheiro 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 ficheiros 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 cadeia no ficheiro de entrada nao e mantida pelo analisador, entao so podemos fornecer "$filename:1" como localizacao da cadeia. Os analisadores orientados a SAX usam globais e outros truques para gravar o nome do ficheiro e os numeros de linha das referencias. Um problema especifico surge das codificacoes de ficheiros e dos marcadores BOM. Analisadores simples podem esquecer este 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 ficheiros sejam lidos com uma camada de descodificacao PerlIO apropriada. O mais facil e abrir o ficheiro mesmo e fornecer um identificador de ficheiro ou diretamente a cadeia completa para o 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 ficheiro 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 ficheiros PO e POT. Basicamente, pode ler um ficheiro, adicionar entradas, obter traducoes com o metodo gettext(), gravar o PO num ficheiro. Recursos mais avancados, como mesclar um ficheiro PO com um ficheiro POT ou validar um ficheiro, sao delegados a msgmerge e msgfmt respectivamente. Contribuir para o po4a Mesmo que nunca tenha contribuido para nenhum projeto de codigo aberto no passado, e bem-vindo: estamos dispostos a ajuda-lo e orienta-lo aqui. po4a e melhor mantido pelos seus utilizadores hoje em dia. Como nao temos mao de obra, procuramos tornar o projeto acolhedor melhorando a documentacao e os testes automaticos para que tenha confianca em contribuir com o projeto. Consulte o ficheiro CONTRIBUTING.md para obter mais pormenores. Projetos de codigo aberto que usam o po4a Aqui esta uma lista bem parcial de projetos que usam po4a na producao para a documentacao deles. Se quiser adicionar o seu projeto a lista, basta nos enviar um e-mail (ou um Pedido de Fusao). o adduser (man): ferramenta de gestao de utilizadores e grupos. o apt (man, docbook): Gestor de pacotes do Debian. o aptitude (docbook, svg): Gestor de pacotes em interface de texto para Debian o F-Droid website (markdown): catalogo instalavel de aplicacoes 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 Linux manpages (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 aplicacao FOSS para jamming online em tempo real. A documentacao do site e mantida em varios idiomas usando po4a. o Outro item para ordenar: PERGUNTAS MAIS FREQUENTES Como se pronuncia po4a? Pessoalmente vocalizo-o como pouah , que e um onomatopaico frances que usamos no lugar de "eca" :) 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 estes 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 usar po4a-updatepo e po4a-translate em 2030, 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 tem uma ideia (ou melhor: um patch), a sua ajuda e bem-vinda. E sobre as outras ferramentas de traducao para documentacao a usar gettext? Existem alguns deles. Aqui esta uma lista possivelmente incompleta e mais ferramentas estao surgindo no horizonte. poxml Esta e a ferramenta desenvolvida por pessoas do KDE para lidar com DocBook XML. AFAIK, ele foi o primeiro programa para extrair cadeias para traduzir de documentacao para ficheiros PO e injeta-las de volta depois da traducao. So pode lidar com XML e apenas um DTD particular. Estou muito descontente com a manipulacao de listas, que terminam com um identificador de mensagem (msgid) grande. Quando a lista se torna enorme, o bloco torna-se mais dificil de absorver. po-debiandoc Este programa feito por Denis Barbier e uma especie de precursor do modulo po4a SGML, que mais ou menos o descontinua. Como o nome diz, ele trata apenas o DebianDoc DTD, que e mais ou menos um DTD obsoleto. xml2po.py Usado pela equipa de documentacao do GIMP desde 2004, funciona muito bem mesmo que, como o nome sugere, apenas com ficheiros XML e precise de makefiles especialmente configurados. Sphinx O Projeto de Documentacao Sphinx tambem usa gettext extensivamente para gerir as suas traducoes. Infelizmente funciona apenas para alguns formatos de texto, rest e markdown, embora seja talvez a unica ferramenta que faz isto a gerir todo o processo de traducao. As principais vantagens de po4a sobre eles, sao a facilidade de adicao de conteudos extra (que e pior ainda la) e a capacidade de atingir gettextization. SUMARIO de vantagens da abordagem baseada em gettext o As traducoes nao sao armazenadas com o original, o que torna possivel detetar se as traducoes estao desatualizadas. o As traducoes estao 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 nivel do ficheiro codificado. o E baseado em gettext (mas po4a oferece uma interface muito simples assim nao precisa de compreender os internos para o usar). Dessa forma nao precisamos de reinventar a roda e, porque o uso dele e mundial, podemos pensar que estas ferramentas estao mais ou menos livres de erros. o Nada muda para o utilizador final (alem do fato das traducoes serem, como esperamos, melhor mantidas). O ficheiro de documentacao resultante e exatamente o mesmo. o Os tradutores nao 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) irao trabalhar bem. o gettext oferece uma maneira simples de obter estatisticas acerca do que e feito, o que deveria ser revisto e atualizado e, o que ainda esta por fazer. Alguns exemplos encontram-se nestes enderecos: - https://docs.kde.org/stable5/en/kdesdk/lokalize/project-view.html - http://www.debian.org/intl/l10n/ Mas nao e tudo verde e, esta aproximacao tem tambem algumas desvantagens com que temos de lidar. o Os adendos sao um pouco estranhos a primeira vista. o Nao pode adaptar o texto traduzido as suas preferencias, como a dividir um paragrafo 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. o Mesmo com um interface facil, continua a ser ferramenta nova que as pessoas tem 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 extraidas e um ficheiro traduzido + ficheiro po poderia ser gravado no disco. Se 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 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 The parsers of each formats, in particular to see the options accepted by each of them: 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 ficheiro CONTRIBUTING.md na arvore fonte. AUTORES Denis Barbier Martin Quinson (mquinson#debian.org) perl v5.42.0 2025-11-22 PO4A.7(1)