.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "PO4A 7" .TH PO4A 7 "2023-01-03" "Ferramentas Po4a" "Ferramentas Po4a" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NOME" .IX Header "NOME" po4a \- quadro para traduzir a documentação e outros materiais .SH "Introdução" .IX Header "Introdução" po4a (\s-1PO\s0 for anything) facilita a manutenção da traduções de documentação a usar as ferramentas gettext clássicas. A característica principal do po4a é que dissocia a tradução do conteúdo da estrutura documental dele. .PP Este documento serve como uma introdução ao projeto po4a, com foco nos utilizadores em potencial, a considerar a possibilidade de usar essa ferramenta e no desejo curioso de entender por que as coisas são do jeito que são. .SH "Por que o po4a?" .IX Header "Por que o po4a?" A filosofia do Software Livre é fazer a tecnologia verdadeiramente disponível a todos. Mas o licenciamento não é a única consideração: software livre não traduzido é inútil para quem não fala inglês. Portanto, ainda temos algum trabalho a fazer para fazer o software disponível a todos. .PP 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. .PP Felizmente, o software Open Source é, na verdade, muito bem traduzido a usar o conjunto de ferramentas gettext. Essas ferramentas são usadas para extrair as cadeias a traduzir de um programa e apresentar as cadeias a traduzir num formato padronizado (chamado de ficheiros \s-1PO\s0 ou catálogos de tradução). Todo um ecossistema de ferramentas surgiu para ajudar os tradutores a realmente traduzir esses ficheiros \s-1PO. O\s0 resultado é então utilizado pela gettext em tempo de execução para exibir as mensagens traduzidas para os utilizadores finais. .PP Em relação à documentação, no entanto, a situação ainda é um pouco decepcionante. No início, traduzir a documentação pode parecer mais fácil do que traduzir um programa, pois parece que apenas precisa de copiar o ficheiro-fonte da documentação e começar a traduzir o conteúdo. No entanto, quando a documentação original é modificada, manter-se a par das modificações rapidamente transforma-se num pesadelo para os tradutores. Se for realizada manualmente, esta tarefa é desagradável e propensa a erros. .PP Traduções desatualizadas geralmente são piores do que nenhuma tradução. Os utilizadores finais podem ser enganados pela documentação que descreve um comportamento antigo do programa. Além disso, eles não podem interagir diretamente com os mantenedores, pois não falam inglês. Além disso, o mantenedor não pode resolver o problema, pois não conhece todos os idiomas em que a documentação deles está traduzida. Essas dificuldades, muitas vezes causadas por ferramentas precárias, podem minar a motivação de tradutores voluntários, a agravar o problema ainda mais. .PP \&\fBO objetivo do projeto po4a é facilitar o trabalho dos tradutores de documentação\fR. Em particular, torna \fImanter\fR traduções de documentações possível. .PP A ideia é de reutilizar e adaptar a abordagem gettext a esse campo. Assim como o gettext, os textos são extraídos dos seus locais originais e apresentados aos tradutores como catálogos de tradução de pedidos. Os tradutores podem aproveitar as ferramentas gettext clássicas para monitorar o trabalho a realizar, colaborar e organizar em equipa. O po4a injeta as traduções diretamente na estrutura da documentação para produzir ficheiros de origem traduzidos que podem ser processados e distribuídos da mesma forma que os ficheiros em inglês. Qualquer parágrafo que não seja traduzido é deixado em inglês no documento resultante, a garantir que os utilizadores finais nunca vejam uma tradução desatualizada na documentação. .PP Isso automatiza a maior parte do trabalho pesado da manutenção da tradução. A descoberta dos parágrafos que precisam de atualização torna-se muito fácil e o processo é completamente automatizado quando os elementos são reordenados sem modificações adicionais. A verificação específica também pode ser usada para reduzir a hipótese de erros de formatação que resultariam num documento quebrado. .PP Por favor, consulte também o \fB\s-1FAQ\s0\fR abaixo neste documento para uma lista mais completa das vantagens e desvantagens desta abordagem. .SS "Formatos suportados" .IX Subsection "Formatos suportados" Atualmente, esta abordagem tem sido implementada com sucesso para vários tipos de formatos de formatação de texto: .IP "man (analisador maduro)" 4 .IX Item "man (analisador maduro)" O bom e velho formato de páginas de manual, usado por muitos programas por aí. Suporte do po4a é muito bem-vindo, a considerar que esse formato é de certa forma difícil de usar e não mesmo amigável para novatos. .Sp O módulo \fBLocale::Po4a::Man\fR\|(3pm) também possui suporte do formato mdoc usado pelas páginas man do \s-1BSD\s0 (elas também são bastante comuns no Linux). .IP "AsciiDoc (analisador maduro)" 4 .IX Item "AsciiDoc (analisador maduro)" Esse formato é um formato de markup leve, destinado a facilitar a criação da documentação. Por exemplo, é usado para documentar o sistema git. Essas páginas man são traduzidas a usar po4a. .Sp Veja Locale::Po4a::AsciiDoc para detalhes. .IP "pod (analisador maduro)" 4 .IX Item "pod (analisador maduro)" Este é o formato de Documentação Perl Online. A linguagem e as próprias extensões são documentadas a usar este formato, além da maioria dos scripts Perl existentes. Torna fácil manter a documentação perto do código real, a incorpora-los ambos no mesmo ficheiro. Torna a vida do programador mais fácil, mas infelizmente não a do tradutor, até que use o po4a. .Sp Veja Locale::Po4a::Pod para detalhes. .IP "sgml (analisador maduro)" 4 .IX Item "sgml (analisador maduro)" Mesmo que hoje em dia seja substituído pelo \s-1XML,\s0 este formato ainda é utilizado para documentos com o comprimento de mais do que alguns ecrãs. Pode até mesmo ser usado para livros inteiros. Pode ser muito desafiador de atualizar documentos deste tamanho. \fBdiff\fR frequentemente revela-se inútil quando o texto original foi reintroduzido após a atualização. Felizmente, o po4a pode ajudá\-lo após esse processo. .Sp Atualmente, apenas o DebianDoc e DocBook são suportados, mas a acrescentar suporte para um novo, é muito simples. É até possível usar po4a num \s-1SGML DTD\s0 desconhecido sem alterar o código, a fornecer as necessárias informações sobre a linha de comando. Veja \fBLocale::Po4a::Sgml\fR\|(3pm) para obter mais detalhes. .IP "TeX / LaTeX (analisador maduro)" 4 .IX Item "TeX / LaTeX (analisador maduro)" O formato LaTeX é o formato de documentação principal usado nas publicações de Software Livre mundiais. .Sp O módulo \fBLocale::Po4a::LaTeX\fR\|(3pm) foi testado com a documentação Python, um livro e algumas apresentações. .IP "text (analisador maduro)" 4 .IX Item "text (analisador maduro)" O formato Text é of formato base para muitos formatos que incluem longos blocos de texto, incluindo Markdown, fortunes, secção de página de rotos \s-1YAML,\s0 debian/changelog e debian/control. .Sp Este possui suporte do formato comum usado em geradores de sites estáticos, READMEs e outros sistemas de documentação. Consulte \fBLocale::Po4a::Text\fR\|(3pm) para detalhes. .IP "xml e \s-1XHMTL\s0 (analisador provavelmente maduro)" 4 .IX Item "xml e XHMTL (analisador provavelmente maduro)" O formato \s-1XML\s0 é um formato de base para muitos formatos de documentação. .Sp Atualmente, o DocBook \s-1DTD\s0 (veja \fBLocale::Po4a::Docbook\fR\|(3pm) para detalhes) e o \s-1XHTML\s0 são suportados pelo po4a. .IP "BibTex (analisador provavelmente maduro)" 4 .IX Item "BibTex (analisador provavelmente maduro)" O formato BibTex é usado junto com o LaTex para formatar listas de referências (bibliografias). .Sp Veja Locale::Po4a::BibTex para detalhes. .IP "Docbook (analisador provavelmente maduro)" 4 .IX Item "Docbook (analisador provavelmente maduro)" Uma linguagem de marcação baseada em \s-1XML\s0 que usa tags semânticas para descrever documentos. .Sp Veja Locale::Po4a:Docbook para mais detalhes. .IP "Guide \s-1XML\s0 (analisador provavelmente maduro)" 4 .IX Item "Guide XML (analisador provavelmente maduro)" Um formato de documentação \s-1XML.\s0 Este módulo foi desenvolvido especificamente para ajudar no suporte e manutenção de traduções da documentação do Gentoo Linux até pelo menos março de 2016 (baseado na máquina Wayback). Desde então, o Gentoo mudou para o formato DevBook \s-1XML.\s0 .Sp Veja Locale::Po4a:Guide para mais detalhes. .IP "Wml (analisador provavelmente maduro)" 4 .IX Item "Wml (analisador provavelmente maduro)" A Web Markup Language, não confunda \s-1WML\s0 com o material \s-1WAP\s0 usado em telefones celulares. Este módulo depende do módulo Xhtml, que por sua vez depende do módulo XmL. .Sp Veja Locale::Po4a::Wml para mais detalhes. .IP "Yaml (analisador provavelmente maduro)" 4 .IX Item "Yaml (analisador provavelmente maduro)" Um superconjunto estrito de \s-1JSON. YAML\s0 é frequentemente usado como sistemas ou projetos de configuração. \s-1YAML\s0 está no cerne do Ansible da Red Hat. .Sp Veja Locale::Po4a::Yaml para mais detalhes. .IP "RubyDoc (analisador provavelmente maduro)" 4 .IX Item "RubyDoc (analisador provavelmente maduro)" O formato Ruby Document (\s-1RD\s0), originalmente o formato de documentação padrão para Ruby e projetos Ruby antes de ser convertido para RDoc em 2002. Embora aparentemente a versão japonesa do Manual de Referência Ruby ainda use \s-1RD.\s0 .Sp Veja Locale::Po4a::RubyDoc para mais detalhes. .IP "Halibut (analisador altamente experimental)" 4 .IX Item "Halibut (analisador altamente experimental)" Um sistema de produção de documentação, com elementos semelhantes ao TeX, debiandoc-sgml, TeXinfo e outros, desenvolvido por Simon Tatham, o programador do PuTTY. .Sp Veja Locale::Po4a:Halibut para mais detalhes. .IP "Ini (analisador altamente experimental)" 4 .IX Item "Ini (analisador altamente experimental)" Formato de ficheiro de configuração popularizado pelo MS-DOS. .Sp Veja Locale::Po4a::Ini para mais detalhes. .IP "texinfo (analisador altamente experimental)" 4 .IX Item "texinfo (analisador altamente experimental)" Toda a documentação \s-1GNU\s0 está escrita neste formato (ainda é um dos requisitos para um projeto \s-1GNU\s0 se tornar oficial). O apoio para \fBLocale::Po4a::Texinfo\fR\|(3pm) em po4a ainda está no início. Por favor, reporte erros e solicitações de recursos. .IP "Outros formatos suportados" 4 .IX Item "Outros formatos suportados" Po4a também pode manipular alguns formatos mais raros ou especializados, como a documentação de opções de compilação dos kernels Linux 2.4+ (Locale::Po4a::KernelHelp) ou diagramas produzidos pela ferramenta Dia (Locale::Po4a:Dia). A adição de um novo formato é normalmente muito fácil e a tarefa principal é fazer um analisador para o seu formato alvo. Veja \fBLocale::Po4a::TransTractor\fR\|(3pm) para mais informações sobre isso. .IP "Formatos não suportados" 4 .IX Item "Formatos não suportados" Infelizmente, o po4a ainda carece suporte para vários formatos de documentação. Muitos deles facilmente seriam suportados pelo po4a. Isto inclui formatos não apenas usados para documentação, tais como, descrições de pacotes (deb e rpm), questões de scripts de instalação de pacotes, changelogs de pacotes e todos os formatos de ficheiros especializados usados por programas como cenários de jogos ou ficheiros de recursos do wine. .SH "Usar o po4a" .IX Header "Usar o po4a" Historicamente, o po4a foi construído à volta de quatro scripts, cada um a cumprir uma tarefa específica. \fBpo4a\-gettextize\fR\|(1) ajuda na inicialização de traduções e, opcionalmente, na conversão de projetos de tradução existentes em po4a. \fBpo4a\-updatepo\fR\|(1) reflete as alterações na documentação original nos ficheiros po correspondentes. \fBpo4a\-translate\fR\|(1) constrói o ficheiro de origem traduzido do ficheiro original e do ficheiro \s-1PO\s0 correspondente. Além disso, \fBpo4a\-normalize\fR\|(1) é principalmente útil para depurar os analisadores de po4a, pois produz um documento não traduzido do original. Torna mais fácil identificar as falhas introduzidas pelo processo de análise. .PP Most projects only require the features of \fBpo4a\-updatepo\fR\|(1) and \fBpo4a\-translate\fR\|(1), but these scripts proved to be cumbersome and error prone to use. If the documentation to translate is split over several source files, it is difficult to keep the \s-1PO\s0 files up to date and build the documentation files correctly. As an answer, a all-in-one tool was provided: \fBpo4a\fR\|(1). This tool takes a configuration file describing the structure of the translation project: the location of the \s-1PO\s0 files, the list of files to translate, and the options to use, and it fully automates the process. When you invoke \fBpo4a\fR\|(1), it both updates the \s-1PO\s0 files and regenerate the translation files that need to. If everything is already up to date, \fBpo4a\fR\|(1) does not change any file. .PP O restante desta secção fornece uma visão geral de como usar a interface de scripts do po4a. A maioria dos utilizadores provavelmente preferirá usar a ferramenta multifuncional, descrita na documentação de \fBpo4a\fR\|(1). .SS "Visão geral gráfica dos scripts do po4a" .IX Subsection "Visão geral gráfica dos scripts do po4a" O esquema a seguir fornece uma visão geral de como cada script po4a pode ser usado. Aqui, \fImaster.doc\fR é um nome de exemplo para a documentação a ser traduzida; \fI\s-1XX\s0.doc\fR é o mesmo documento traduzido no idioma \s-1XX,\s0 enquanto \fIdoc.XX.po\fR é o catálogo de traduções desse documento no idioma \s-1XX.\s0 Os autores da documentação se preocuparão principalmente com \fImaster.doc\fR (que pode ser uma página man, um documento \s-1XML,\s0 um ficheiro asciidoc ou semelhante); os tradutores se preocuparão principalmente com o ficheiro \s-1PO,\s0 enquanto os utilizadores finais verão apenas o ficheiro \fI\s-1XX\s0.doc\fR. .PP .Vb 10 \& original.doc \& | \& V \& +<\-\-\-\-\-<\-\-\-\-+<\-\-\-\-\-<\-\-\-\-\-<\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\->\-\-\-\-\-\-\-\->\-\-\-\-\-\-\-+ \& : | | : \& {tradução} | { actualização do original.doc } : \& : | | : \& XX.doc | V V \&(opcional) | original.doc \->\-\-\-\-\-\-\-\->\-\-\-\-\-\->+ \& : | (novo) | \& V V | | \& [po4a\-gettextize] doc.XX.po\-\-\->+ | | \& | (antigo) | | | \& | ^ V V | \& | | [po4a\-atualizar po] | \& V | | V \& tradução.pot ^ V | \& | | doc.XX.po | \& | | (impreciso) | \& {tradução} | | | \& | ^ V V \& | | {edição manual} | \& | | | | \& V | V V \& doc.XX.po \-\-\->\-\-\-\->+<\-\-\-<\-\-\-\- doc.XX.po adenda original.doc \& (inicial) (atualizado) (optional) (atualizado) \& : | | | \& : V | | \& +\-\-\-\-\->\-\-\-\-\->\-\-\-\-\->\-\-\-\-\-\-> + | | \& | | | \& V V V \& +\-\-\-\-\-\->\-\-\-\-\-+\-\-\-\-\-\-<\-\-\-\-\-\-+ \& | \& V \& [po4a\-traduzido] \& | \& V \& XX.doc \& (atualizado) .Ve .PP Esse esquema é complicado, mas na prática apenas a parte correta (a envolver \fBpo4a\-updatepo\fR\|(1) e \fBpo4a\-translate\fR\|(1)) é usada depois que o projeto é instalado e configurado. .PP A parte esquerda mostra como \fBpo4a\-gettextize\fR\|(1) pode ser usado para converter um projeto de tradução existente para a infraestrutura do po4a. Este script leva um documento original e o equivalente traduzido e tenta construir o ficheiro \s-1PO\s0 correspondente. Tal conversão manual é um pouco trabalhosa (veja a documentação \fBpo4a\-gettextize\fR\|(1) para mais detalhes), mas só é necessária uma vez para converter as suas traduções existentes. Se não tiver nenhuma tradução para converter, pode esquecer-se disto e focar na parte certa do esquema. .PP Na parte superior direita, a ação do autor original é retratada, a atualizar a documentação. Na parte do meio, à direita, as ações automáticas de \fBpo4a\-updatepo\fR\|(1) são representadas. O novo material é extraído e comparado com a tradução de saída. A tradução anterior é utilizada para as partes que não mudaram, enquanto as partes parcialmente modificadas são ligadas à tradução anterior com um marcador \*(L"fuzzy\*(R" a indicar que a tradução deve ser atualizada. O material novo ou fortemente modificado não é traduzido. .PP A seguir, a \fIedição manual\fR relatada representa a ação dos tradutores, que modificam os ficheiro \s-1PO\s0 para fornecer traduções para todas as cadeias e os parágrafos originais. Isso pode ser feito a usar um editor específico, como o \fBEditor de Tradução do \s-1GNOME\s0\fR, o \fBLokalize\fR do \s-1KDE\s0 ou \fBpoedit\fR ou a usar uma plataforma de localização online como o \fBweblate\fR ou \fBpootle\fR. O resultado da tradução é um conjunto de ficheiros \s-1PO,\s0 um por idioma. Consulte a documentação gettext para mais detalhes. .PP A parte inferior da figura mostra como \fBpo4a\-translate\fR\|(1) cria um documento fonte traduzido do documento original \fImaster.doc\fR e do catálogo de traduções \fIdoc.XX.po\fR que foram atualizados pelos tradutores . A estrutura do documento é reutilizada, enquanto o conteúdo original é substituído pela contraparte dele traduzida. Opcionalmente, um adendo pode ser usado para adicionar textos à tradução. Isso geralmente é usado para adicionar o nome do tradutor ao documento final. Veja abaixo os detalhes. .PP Como observado anteriormente, o programa \fBpo4a\fR\|(1) combina os efeitos dos scripts separados, a atualizar os ficheiros \s-1PO\s0 e o documento traduzido numa chamada. A lógica subjacente permanece a mesma. .SS "Iniciar uma nova tradução" .IX Subsection "Iniciar uma nova tradução" Se usar \fBpo4a\fR\|(1), não há etapas específicas para iniciar uma tradução. Apenas precisa listar os idiomas no ficheiro de configuração e os ficheiros \s-1PO\s0 ausentes são criados automaticamente. Naturalmente, o tradutor deve fornecer traduções para todos os conteúdos usados nos seus documentos. \fBpo4a\fR\|(1) também cria um ficheiro \s-1POT,\s0 que é um ficheiro de modelo de \s-1PO.\s0 Tradutores possíveis podem traduzir o seu projeto a um novo idioma a renomear esse ficheiro e a fornecer as traduções no idioma deles. .PP Se preferir usar os scripts individuais separadamente, use \fBpo4a\-gettextize\fR\|(1) da maniera seguinte para criar o ficheiro \s-1POT.\s0 Este ficheiro pode ser copiado em \fI\s-1XX\s0.po\fR para iniciar uma nova tradução. .PP .Vb 1 \& $ po4a\-gettextize \-\-format \-\-master \-\-po .Ve .PP O documento mestre é usado na entrada, enquanto o ficheiro \s-1PO\s0 é a saída deste processo. .SS "Integrar alterações ao documento original" .IX Subsection "Integrar alterações ao documento original" O script a ser usado para isso é \fBpo4a\-updatepo\fR\|(1) (consulte a documentação para obter detalhes): .PP .Vb 1 \& $ po4a\-updatepo \-\-format \-\-master \-\-po .Ve .PP O documento mestre é usado na entrada, enquanto o ficheiro \s-1PO\s0 é atualizado: ele é usado tanto na entrada quanto na saída. .SS "Geração de um documento traduzido" .IX Subsection "Geração de um documento traduzido" Uma vez que acabou com a tradução, deseja obter a documentação traduzida e distribuí\-la aos utilizadores com o original. Para isso, use o programa \fBpo4a\-translate\fR\|(1) como a seguir: .PP .Vb 1 \& $ po4a\-translate \-\-format \-\-master \-\-po \-\-localized .Ve .PP Os ficheiros mestre e \s-1PO\s0 são usados na entrada, enquanto o ficheiro localizado é a saída desse processo. .SS "Usando adendos para adicionar textos às traduções" .IX Subsection "Usando adendos para adicionar textos às traduções" Adicionar novos textos à tradução é provavelmente a única coisa mais fácil a longo prazo quando traduz ficheiros manualmente :). Isso acontece quando deseja adicionar uma secção adicional ao documento traduzido, que não corresponde a nenhum conteúdo no documento original. O caso de uso clássico é dar mérito à equipa de tradução e indicar como relatar problemas específicos da tradução. .PP Com o po4a, é necessário especificar os ficheiros \fBaddendum\fR, que podem ser vistos conceitualmente como patches aplicados ao documento localizado após o processamento. Cada adendo deve ser fornecido como um ficheiro separado, cujo formato é, no entanto, muito diferente dos patches clássicos. A primeira linha é uma \fIlinha de cabeçalho\fR, a definir o ponto de inserção do adendo (com uma sintaxe infelizmente enigmática \*(-- veja abaixo) enquanto o restante do ficheiro é adicionado literalmente na posição determinada. .PP A linha do cabeçalho deve começar com a cadeia \fB\s-1PO4A\-HEADER:\s0\fR, seguida por uma lista separada por ponto e vírgula dos campos \fIchave\fR\fB=\fR\fIvalor\fR. .PP Por exemplo, o cabeçalho a seguir declara um adendo que deve ser posto bem no final da tradução. .PP .Vb 1 \& PO4A\-HEADER: mode=eof .Ve .PP As coisas ficam mais complexas quando deseja adicionar o seu conteúdo adicional no meio do documento. O cabeçalho a seguir declara um adendo que deve ser posto após a secção \s-1XML\s0 que contém a cadeia \f(CW\*(C`Sobre este documento\*(C'\fR na tradução. .PP .Vb 1 \& PO4A\-HEADER: position=About this document; mode=after; endboundary= .Ve .PP Na prática, ao tentar aplicar um adendo, o po4a pesquisa a primeira linha correspondente ao argumento \f(CW\*(C`position\*(C'\fR (isso pode ser um regexp). Não se esqueça que o po4a considera o documento \fBtranslated\fR aqui. Esta documentação é em inglês, mas a sua linha provavelmente deve ser a seguinte, se pretende que o seu adendo se aplique à tradução do documento em francês. .PP .Vb 1 \& PO4A\-HEADER: position=À propos de ce document; mode=after; endboundary= .Ve .PP Depois que a \f(CW\*(C`position\*(C'\fR foi encontrada no documento de destino, o po4a procura a próxima linha após a \f(CW\*(C`position\*(C'\fR que corresponde ao \f(CW\*(C`endboundary\*(C'\fR fornecido. O adendo é adicionado à direita \fBafter\fR essa linha (porque fornecemos um \fIendboundary\fR, ou seja, um limite que termina a secção atual). .PP O exato mesmo efeito pode ser obtido com o cabeçalho seguinte, que é equivalente: .PP .Vb 1 \& PO4A\-HEADER: position=Sobre este documento; mode=after; beginboundary=
.Ve .PP Aqui, o po4a pesquisa a primeira linha correspondente a \f(CW\*(C` após a linha correspondente a \f(CW\*(C`About this document\*(C'\fR na tradução e adiciona o adendo \fBbefore\fR dessa linha, pois fornecemos um \fIbeginboundary\fR, ou seja, um limite que marca o início da próxima secção. Portanto, essa linha de cabeçalho exige a inserção do adendo após a secção que contém \f(CW\*(C`About this document\*(C'\fR e instrui o po4a que uma secção começa com uma linha que contém a marcação \f(CW\*(C`. Isso é equivalente ao exemplo anterior, porque o que realmente deseja é adicionar este adendo após \f(CW\*(C`/section\*(C'\fR> ou antes de \f(CW\*(C`. .PP Também pode definir a inserção \fImodo\fR como o valor \f(CW\*(C`before\*(C'\fR, com uma semântica semelhante: a combinação de \f(CW\*(C`mode=before\*(C'\fR com um \f(CW\*(C`endboundary\*(C'\fR pôrá o adendo apenas \fBafter\fR o limite correspondente, que a última linha limite potencial antes da \f(CW\*(C`position\*(C'\fR. Combinar \f(CW\*(C`mode=before\*(C'\fR com um \f(CW\*(C`beginboundary\*(C'\fR pôrá o adendo apenas \fBbefore\fR do limite correspondente, que é a última linha limite potencial antes da \f(CW\*(C`position\*(C'\fR. .PP .Vb 7 \& Modo | Tipo de limite | Limite usado | Ponto de inserção am comparação ao limite \& ========|================|============================|========================================== \& \*(Aqbefore\*(Aq| \*(Aqendboundary\*(Aq | último antes de \*(Aqposition\*(Aq | Logo após o limite selecionado \& \*(Aqbefore\*(Aq|\*(Aqbeginboundary\*(Aq | último antes de \*(Aqposition\*(Aq | Logo antes do limite selecionado \& \*(Aqafter\*(Aq | \*(Aqendboundary\*(Aq | primeiro após \*(Aqposition\*(Aq | Logo após o limite selecionado \& \*(Aqafter\*(Aq |\*(Aqbeginboundary\*(Aq | primeiro após \*(Aqposition\*(Aq | Logo antes do limite selecionado \& \*(Aqeof\*(Aq | (none) | n/d | Fim do ficheiro .Ve .PP \fIDicas e truques sobre adendos\fR .IX Subsection "Dicas e truques sobre adendos" .IP "\(bu" 4 Lembre-se que estes são regexp. Por exemplo, se quiser combinar o final de uma secção nroff a terminar com a linha \f(CW\*(C`.fi\*(C'\fR, não use \f(CW\*(C`.fi\*(C'\fR como \fBendboundary\fR, porque ele irá combinar com \f(CW\*(C`the[ fi]le\*(C'\fR, que obviamente não é o que espera. O \fBendboundary\fR correto, nesse caso, é: \f(CW\*(C`^^.fi$\*(C'\fR. .IP "\(bu" 4 Espaços em branco SÃO importantes no conteúdo da \f(CW\*(C`position\*(C'\fR e limites. Portanto, as duas linhas seguintes \fBsão diferentes\fR. O segundo só será encontrado se houver espaços suficientes à direita no documento traduzido. .Sp .Vb 2 \& PO4A\-HEADER: position=Acerca deste documento; mode=after; beginboundary=
\& PO4A\-HEADER: position=Acerca deste documento ; mode=after; beginboundary=
.Ve .IP "\(bu" 4 Embora essa pesquisa de contexto possa ser a operar cerca de cada linha do documento \fBtraduzido\fR, realmente opera na cadeia de dados interna do documento traduzido. Essa cadeia de dados interna pode ser um texto a abranger um parágrafo que contem várias linhas ou pode ser uma marcação \s-1XML\s0 sozinha. O exato \fIponto de inserção\fR do adendo deve ser anterior ou posterior à sequência de dados interna e não pode estar dentro da cadeia de dados interna. .IP "\(bu" 4 Passe o argumento \fB\-vv\fR para po4a para entender como os adendos são adicionados à tradução. Também pode ajudar a executar po4a no modo de depuração para ver a cadeia de dados interna real quando o seu adendo não se aplica. .PP \fIExemplos de adendos\fR .IX Subsection "Exemplos de adendos" .IP "\(bu" 4 Se quiser acrescentar algo depois na secção seguinte nroff: .Sp .Vb 1 \& .SH "AUTORES" .Ve .Sp Deve selecionar a abordagem em duas etapas a configurar \fBmode=after\fR. Em seguida, deve restringir a pesquisa à linha após \fB\s-1AUTHORS\s0\fR com a regex de argumento \fBposition\fR. Depois deve combinar o início da próxima secção (isto é, \fB^ \e. \s-1SH\s0\fR) com a regex de argumento \fBbeginboundary\fR. Isso é para dizer: .Sp .Vb 1 \& PO4A\-HEADER:mode=after;position=AUTORES;beginboundary=\e.SH .Ve .IP "\(bu" 4 Se quiser adicionar algo logo após uma determinada linha (por exemplo, após a linha \*(L"Copyright Big Dude\*(R"), use uma \fBposition\fR a corresponder a esta linha, \fBmode=after\fR e dê um \fBbeginboundary\fR a corresponder a qualquer linha. .Sp .Vb 1 \& PO4A\-HEADER:mode=after;position=Copyright Big Dude, 2004;beginboundary=^ .Ve .IP "\(bu" 4 Se quiser adicionar alguma coisa no final do documento, dê uma \fBposition\fR correspondente a qualquer linha do seu documento (mas apenas uma linha, po4a não continuará se não é única) e dê uma \fBendboundary\fR sem corresponder a nada. Aqui não use cadeias simples como \fB\*(L"\s-1EOF\*(R"\s0\fR, mas prefira as que têm menos hipótese estar no seu documento. .Sp .Vb 1 \& PO4A\-HEADER:mode=after;position=Sobre este documento;beginboundary=FakePo4aBoundary .Ve .PP \fIExemplo mais detalhado\fR .IX Subsection "Exemplo mais detalhado" .PP Documento original (\s-1POD\s0 formatado): .PP .Vb 7 \& |=head1 NOME \& | \& |fictício \- um programa fictício \& | \& |=head1 AUTOR \& | \& |eu .Ve .PP Então, a adenda a seguir irá garantir que uma secção (em francês) sobre o tradutor é adicionado no final do processo (em francês, \*(L"\s-1TRADUCTEUR\*(R"\s0 significa \*(L"tradutor\*(R" e, \*(L"moi\*(R" significa \*(L"eu\*(R"). .PP .Vb 6 \& |PO4A\-HEADER:mode=after;position=AUTOR;beginboundary=^=head \& | \& |=head1 TRADUTOR \& | \& |eu \& | .Ve .PP Para posicionar a sua adenda antes do \s-1AUTOR,\s0 use o seguinte cabeçalho: .PP .Vb 1 \& PO4A\-HEADER:mode=after;position=NOM;beginboundary=^=head1 .Ve .PP Isso funciona porque a próxima linha a corresponder ao \fBbeginboundary\fR /^=head1/ após a secção \*(L"\s-1NAME\*(R"\s0 (traduzido para \*(L"\s-1NOM\*(R"\s0 em Francês) é aquela a declarar os autores. Então, o adendo será posto entre as duas secções. Note que se outra secção for adicionada entre as secções \s-1NAME\s0 e \s-1AUTHOR\s0 posteriormente, po4a pôrá o adendo equivocadamente antes da nova secção. .PP Para evitar isto, pode realizar o mesmo a usar \fBmode\fR=\fIbefore\fR: .PP .Vb 1 \& PO4A\-HEADER:mode=before;position=^=head1 AUTEUR .Ve .SH "Como é que funciona?" .IX Header "Como é que funciona?" Este capítulo dá\-nos uma visão geral interna do po4a, de modo que possa sentir-se mais confiante para nos ajudar a manter e a melhorar. Pode também ajudá\-lo a entender por que ele não faz o que esperava e como resolver os seus problemas. .PP A arquitetura do po4a é orientada a objetos. A \fBLocale::Po4a::TransTractor\fR\|(3pm) class é o ancestral comum a todos os analisadores do po4a. Este estranho nome vem do facto de ser ao mesmo tempo responsável pela tradução de documentos e pela extração de cadeias. .PP Mais formalmente, é preciso um documento para traduzir mais um ficheiro \s-1PO\s0 que contém as traduções para usar como entrada, enquanto produz duas saídas separadas: Outro ficheiro \s-1PO\s0 (resultante da extração das sequências traduzíveis no documento de entrada) e um documento traduzido (com a mesma estrutura do que a entrada, mas com todas as sequências de cadeias traduzíveis substituídos com o conteúdo de entrada \s-1PO\s0). Aqui é uma representação gráfica deste: .PP .Vb 6 \& entrada documento \-\-\e /\-\-\-> saída documento \& \e TransTractor:: / (traduzido) \& +\-\->\-\- analise() \-\-\-\-\-\-\-\-+ \& / \e \& entrada PO \-\-\-\-\-\-\-\-/ \e\-\-\-> saída PO \& (extraido) .Ve .PP Este pequeno osso é o núcleo de toda a arquitetura do po4a. Se omitir o \s-1PO\s0 de entrada e o documento de saída, obtém \fBpo4a\-gettextize\fR. Se fornecer ambos ficheiros de entrada e desconsiderar o \s-1PO\s0 de saída, obtém \fBpo4a\-translate\fR. O \fBpo4a\fR chama o TransTractor duas vezes e chama \fBmsgmerge \-U\fR entre essas chamadas do TransTractor para fornecer uma solução completa com um único ficheiro de configuração. Por favor veja \fBLocale::Po4a::TransTractor\fR\|(3pm) para mais detalhes. .SH "Projetos de código aberto que usam o po4a" .IX Header "Projetos de código aberto que usam o po4a" Aqui está uma lista bem parcial de projetos que usam po4a na produção para a documentação deles. Se quiser adicionar o seu projeto à lista, basta nos enviar um e\-mail (ou uma merge request). .IP "\(bu" 4 adduser (man): ferramenta de gestão de utilizadores e grupos. .IP "\(bu" 4 apt (man, docbook): Gestor de pacotes do Debian. .IP "\(bu" 4 aptitude (docbook, svg): Gestor de pacotes em interface de texto para Debian .IP "\(bu" 4 Site do F\-Droid (markdown): catálogo instalável de aplicações \s-1FOSS\s0 (abreviação de software livre e de código aberto) para a plataforma Android. .IP "\(bu" 4 git (asciidoc): sistema de controle de versão distribuído para alterações de rastreamento em código\-fonte. .IP "\(bu" 4 Páginas man do Linux (man) .Sp 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). .IP "\(bu" 4 Stellarium (\s-1HTML\s0): um planetário de código aberto e livre para o seu computador. po4a é usado para traduzir as descrições da cultura do céu. .IP "\(bu" 4 Outro item para resolver: .SH "PERGUNTAS MAIS FREQUENTES" .IX Header "PERGUNTAS MAIS FREQUENTES" .SS "Como se pronuncia po4a?" .IX Subsection "Como se pronuncia po4a?" Pessoalmente vocalizo-o como pouah , que é um onomatopaico francês que usamos no lugar de \*(L"eca\*(R" :) posso ter um senso de humor estranho :) .SS "E sobre as outras ferramentas de tradução para documentação a usar gettext?" .IX Subsection "E sobre as outras ferramentas de tradução para documentação a usar gettext?" There are a few of them. Here is a possibly incomplete list, and more tools are coming at the horizon. .IP "\fBpoxml\fR" 4 .IX Item "poxml" Esta é a ferramenta desenvolvida por pessoas do \s-1KDE\s0 para lidar com DocBook \s-1XML. AFAIK,\s0 ele foi o primeiro programa para extrair cadeias para traduzir de documentação para ficheiros \s-1PO\s0 e injetá\-las de volta depois de tradução. .Sp Só pode lidar com \s-1XML\s0 e apenas um \s-1DTD\s0 particular. Estou muito descontente com a manipulação de listas, que terminam com um identificador de mensagem (msgid) grande. Quando a lista se torna enorme, o bloco torna-se mais difícil de absorver. .IP "\fBpo-debiandoc\fR" 4 .IX Item "po-debiandoc" Este programa feito por Denis Barbier é uma espécie de precursor do módulo po4a \s-1SGML,\s0 que mais ou menos o despreza. Como o nome diz, ele trata apenas o DebianDoc \s-1DTD,\s0 que é mais ou menos um \s-1DTD\s0 obsoleto. .IP "\fBxml2po.py\fR" 4 .IX Item "xml2po.py" Used by the \s-1GIMP\s0 Documentation Team since 2004, works quite well even if, as the name suggests, only with \s-1XML\s0 files and needs specially configured makefiles. .IP "\fBSphinx\fR" 4 .IX Item "Sphinx" The Sphinx Documentation Project also uses gettext extensively to manage its translations. Unfortunately, it works only for a few text formats, rest and markdown, although it is perhaps the only tool that does this managing the whole translation process. .PP As principais vantagens de po4a sobre eles, são a facilidade de adição de conteúdos extra (que é pior ainda lá) e a capacidade de atingir gettextization. .SS "SUMÁRIO de vantagens da aproximação de base ao gettext" .IX Subsection "SUMÁRIO de vantagens da aproximação de base ao gettext" .IP "\(bu" 2 As traduções não são armazenadas com o original, o que torna possível detetar se as traduções estão desatualizadas. .IP "\(bu" 2 As traduções estão armazenadas em ficheiros separados a partir de cada um, o que previne os tradutores de idiomas diferentes de intervirem, em ambos, quando submetem os seus fragmentos (patches) e no nível do ficheiro codificado. .IP "\(bu" 2 É baseado em \fBgettext\fR (mas \fBpo4a\fR oferece uma interface muito simples assim não precisa de compreender os internos para o usar). Dessa forma não precisamos de reinventar a roda e, porque o uso dele é mundial, podemos pensar que estas ferramentas estão mais ou menos livres de erros. .IP "\(bu" 2 Nada muda para o utilizador final (além do fato das traduções serem, como esperamos, melhor mantidas). O ficheiro de documentação resultante é exatamente o mesmo. .IP "\(bu" 2 Os tradutores não precisam de aprender a nova sintaxe de ficheiros e os editores de ficheiros \s-1PO\s0 favoritos deles (como o modo \s-1PO\s0 do Emacs, Lokalize ou Gtranslator) irão trabalhar bem. .IP "\(bu" 2 gettext oferece uma maneira simples de obter estatísticas acerca do que é feito, o que deveria ser revisto e atualizado e, o que ainda está por fazer. Alguns exemplos encontram-se nestes endereços: .Sp .Vb 2 \& \- https://docs.kde.org/stable5/pt_BR/kdesdk/lokalize/project\-view.html \& \- http://www.debian.org/intl/l10n/ .Ve .PP Mas não é tudo verde e, esta aproximação tem também algumas desvantagens com que temos de lidar. .IP "\(bu" 2 Adendos são… estranhos à primeira vista. .IP "\(bu" 2 Não pode adaptar o texto traduzido as suas preferências, como a dividir um parágrafo aqui e, a juntar outros dois ali. Mas em certo sentido, se existe um problema com o original, deve ser reportado como um erro de qualquer maneira. .IP "\(bu" 2 Mesmo com um interface fácil, continua a ser ferramenta nova que as pessoas têm que aprender. .Sp Um dos meus sonhos seria integrar de alguma forma po4a ao Gtranslator ou Lokalize. Quando um ficheiro de documento fosse aberto, as cadeias seriam automaticamente extraídas e um ficheiro traduzido + ficheiro po poderia ser gravado no disco. Se conseguirmos fazer um módulo para \s-1MS\s0 Word (\s-1TM\s0) (ou pelo menos \s-1RTF\s0), tradutores profissionais podem até mesmo usá\-lo. .SH "VER TAMBÉM" .IX Header "VER TAMBÉM" .IP "\(bu" 4 A documentação da ferramenta multifuncional que deve usar: \fBpo4a\fR\|(1). .IP "\(bu" 4 A documentação dos scripts individuais do po4a: \fBpo4a\-gettextize\fR\|(1), \fBpo4a\-updatepo\fR\|(1), \fBpo4a\-translate\fR\|(1), \fBpo4a\-normalize\fR\|(1). .IP "\(bu" 4 Os scripts de ajuda adicionais: \fBmsguntypot\fR\|(1), \fBpo4a\-display\-man\fR\|(1), \fBpo4a\-display\-pod\fR\|(1). .IP "\(bu" 4 Os analisadores de cada formato, particularmente para ver as opções aceitas por cada um deles:\fBLocale::Po4a::AsciiDoc\fR\|(3pm) \fBLocale::Po4a::Dia\fR\|(3pm), \fBLocale::Po4a::Guide\fR\|(3pm), \fBLocale::Po4a::Ini\fR\|(3pm), \fBLocale::Po4a::KernelHelp\fR\|(3pm), \fBLocale::Po4a::Man\fR\|(3pm), \fBLocale::Po4a::RubyDoc\fR\|(3pm), \fBLocale::Po4a::Texinfo\fR\|(3pm), \fBLocale::Po4a::Text\fR\|(3pm), \fBLocale::Po4a::Xhtml\fR\|(3pm), \fBLocale::Po4a::Yaml\fR\|(3pm), \fBLocale::Po4a::BibTeX\fR\|(3pm), \fBLocale::Po4a::Docbook\fR\|(3pm), \fBLocale::Po4a::Halibut\fR\|(3pm), \fBLocale::Po4a::LaTeX\fR\|(3pm), \fBLocale::Po4a::Pod\fR\|(3pm), \fBLocale::Po4a::Sgml\fR\|(3pm), \fBLocale::Po4a::TeX\fR\|(3pm), \fBLocale::Po4a::Wml\fR\|(3pm), \fBLocale::Po4a::Xml\fR\|(3pm). .IP "\(bu" 4 A implementação da infraestrutura principal: \fBLocale::Po4a::TransTractor\fR\|(3pm) (particularmente importante para entender a organização do código), \fBLocale::Po4a::Chooser\fR\|(3pm), \fBLocale::Po4a::Po\fR\|(3pm), \fBLocale::Po4a::Common\fR\|(3pm). Por favor, verifique também o ficheiro \fI\s-1CONTRIBUTING\s0.md\fR na árvore de fonts. .SH "AUTORES" .IX Header "AUTORES" .Vb 2 \& Denis Barbier \& Martin Quinson (mquinson#debian.org) .Ve