.\" 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 do Po4a" "Ferramentas do 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 \- framework para traduzir documentação e outros materiais .SH "Introdução" .IX Header "Introdução" po4a (\s-1PO\s0 for anything) facilita a manutenção da tradução de documentação usando as ferramentas gettext clássicas. A principal característica do po4a é que ele dissocia a tradução do conteúdo de sua estrutura documental. .PP Este documento serve como uma introdução ao projeto po4a, com foco nos usuários em potencial, considerando a possibilidade de usar essa ferramenta e no desejo curioso de entender por que as coisas são do jeito que são. .SH "Por que o po4a?" .IX Header "Por que o po4a?" A filosofia do software livre é tornar a tecnologia verdadeiramente disponível para todos. Mas o licenciamento não é a única consideração: o software livre não traduzido é inútil para quem não fala inglês. Portanto, ainda temos algum trabalho a fazer para disponibilizar o software para todos. .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 de código aberto é realmente muito bem traduzido usando o conjunto de ferramentas gettext. Essas ferramentas são usadas para extrair as strings a serem traduzidas de um programa e apresentar as strings em um formato padronizado (chamado de arquivos \s-1PO\s0 ou catálogos de tradução). Um ecossistema inteiro de ferramentas surgiu para ajudar os tradutores a traduzir esses arquivos \s-1PO. O\s0 resultado é usado pelo gettext no tempo de execução para exibir mensagens traduzidas para os usuários 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 você apenas precisa copiar o arquivo-fonte da documentação e começar a traduzir o conteúdo. No entanto, quando a documentação original é modificada, acompanhar as modificações rapidamente se transforma em um pesadelo para os tradutores. Se realizada manualmente, esta tarefa é desagradável e propensa a erros. .PP Traduções desatualizadas geralmente são piores do que nenhuma tradução. Os usuários finais podem ser enganados pela documentação que descreve um comportamento antigo do programa. Além disso, eles não podem interagir diretamente com os mantenedores, pois não falam inglês. Além disso, o mantenedor não pode resolver o problema, pois não conhece todos os idiomas em que sua documentação está traduzida. Essas dificuldades, muitas vezes causadas por ferramentas precárias, podem minar a motivação de tradutores voluntários, agravando ainda mais o problema. .PP \&\fBO objetivo do projeto po4a é facilitar o trabalho dos tradutores de documentação\fR. Em particular, ele torna possível \fImanter\fR traduções de documentações. .PP A ideia é reutilizar e adaptar a abordagem gettext a esse campo. Assim como o gettext, os textos são extraídos de seus locais originais e apresentados aos tradutores como catálogos de tradução de pedidos. Os tradutores podem aproveitar as ferramentas gettext clássicas para monitorar o trabalho a realizar, colaborar e organizar em equipe. O po4a injeta as traduções diretamente na estrutura da documentação para produzir arquivos de origem traduzidos que podem ser processados e distribuídos da mesma forma que os arquivos em inglês. Qualquer parágrafo que não seja traduzido é deixado em inglês no documento resultante, garantindo que os usuários finais nunca vejam uma tradução desatualizada na documentação. .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 se torna muito fácil e o processo é completamente automatizado quando os elementos são reordenados sem modificações adicionais. A verificação específica também pode ser usada para reduzir a chance de erros de formatação que resultariam em um documento quebrado. .PP Por favor, veja também o \fB\s-1FAQ\s0\fR abaixo neste documento para uma lista mais completa de vantagens e desvantagens desta abordagem. .SS "Formatos suportados" .IX Subsection "Formatos suportados" Atualmente, essa abordagem tem sido implementada com sucesso em vários 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, considerando que esse formato é de certa forma difícil de usar e não exatamente amigável para novatos. .Sp O módulo \fBLocale::Po4a::Man\fR\|(3pm) também possui suporte ao 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 marcação 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 usando po4a. .Sp Veja Locale::Po4a::AsciiDoc para detalhes. .IP "pod (analisador maduro)" 4 .IX Item "pod (analisador maduro)" Esse é o formato da documentação online de Perl, ou Perl Online Documentation. A própria linguagem e extensões são documentadas usando este formato além da maioria dos scripts Perl existentes. Isso facilita a manter a documentação ferto do real código embutindo-os no mesmo arquivo. Isso torna a vida dos programadores mais fácil, mas infelizmente, não a do tradutor, até você usar o po4a. .Sp Veja Locale::Po4a::Pod para detalhes. .IP "sgml (analisador maduro)" 4 .IX Item "sgml (analisador maduro)" Mesmo que substituído pelo \s-1XML\s0 hoje em dia, esse formato ainda é usado para documentos que têm mais de algumas telas. Pode até ser usado para livros completos. Documentos deste comprimento podem ser muito desafiadores para atualizar. \fBdiff\fR muitas vezes revela inútil quando o texto original era recuado novamente após a atualização. Felizmente, po4a pode lhe ajudar depois desse processo. .Sp Atualmente, há suporte apenas ao DebianDoc e o DocBook \s-1DTD,\s0 mas a adição de suporte a um novo é realmente fácil. É possível até mesmo usar po4a em um \s-1SGML DTD\s0 desconhecido sem alterar o código, desde que sejam fornecidas as informações necessárias na linha de comando. Veja \fBLocale::Po4a::Sgml\fR\|(3pm) para mais detalhes. .IP "TeX / LaTeX (analisador maduro)" 4 .IX Item "TeX / LaTeX (analisador maduro)" O formato LaTeX é um formato de documentação mais usado no mundo de software livre e para publicações. .Sp O módulo \fBLocale::Po4a::LaTeX\fR\|(3pm) foi testado com a documentação do 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, seção de página de rotos \s-1YAML,\s0 debian/changelog e debian/control. .Sp Este possui suporte ao 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 base para muitos formatos de documentação. .Sp Atualmente, o DocBook \s-1DTD\s0 (veja \fBLocale::Po4a::Docbook\fR\|(3pm) para mais detalhes) e \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 desenvolvedor do PuTTY. .Sp Veja Locale::Po4a:Halibut para mais detalhes. .IP "Ini (analisador altamente experimental)" 4 .IX Item "Ini (analisador altamente experimental)" Formato de arquivo 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 do \s-1GNU\s0 é escrita neste formato (esse é até mesmo um dos requisitos para se tornar um projeto \s-1GNU\s0 oficial). O suporte a \fBLocale::Po4a::Texinfo\fR\|(3pm) no po4a ainda está nas fases iniciais. Por favor relate eventuais erros e requisição por recursos. .IP "Outros formatos com suporte" 4 .IX Item "Outros formatos com suporte" 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 seu formato alvo. Veja \fBLocale::Po4a::TransTractor\fR\|(3pm) para mais informações sobre isso. .IP "Formatos sem suporte" 4 .IX Item "Formatos sem suporte" Infelizmente, po4a ainda carece de suporte para vários formatos de documentação. Muitos deles seriam fáceis de dar suporte no po4a. Isso inclui formatos não apenas usados para documentação, como, descrições de pacotes (deb e rpm), perguntas sobre scripts de instalação de pacotes, changelogs de pacotes e todos os formatos de arquivo especializados usados por programas como cenários de jogos ou arquivos de recursos de vinho. .SH "Usando po4a" .IX Header "Usando po4a" Historicamente, o po4a foi construído em torno de quatro scripts, cada um cumprindo 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 arquivos po correspondentes. \fBpo4a\-translate\fR\|(1) constrói o arquivo de origem traduzido a partir do arquivo original e do arquivo \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 seção fornece uma visão geral de como usar a interface de scripts do po4a. A maioria dos usuários 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 arquivo asciidoc ou semelhante); os tradutores se preocuparão principalmente com o arquivo \s-1PO,\s0 enquanto os usuários finais verão apenas o arquivo \fI\s-1XX\s0.doc\fR. .PP .Vb 10 \& mestre.doc \& | \& V \& +<\-\-\-\-\-<\-\-\-\-+<\-\-\-\-\-<\-\-\-\-\-<\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\->\-\-\-\-\-\-\-\->\-\-\-\-\-\-\-+ \& : | | : \& {tradução} | { atualização de mestre.doc } : \& : | | : \& XX.doc | V V \& (opcional) | mestre.doc \->\-\-\-\-\-\-\-\->\-\-\-\-\-\->+ \& : | (novo) | \& V V | | \& [po4a\-gettextize] doc.XX.po\-\-\-\->+ | | \& | (velho) | | | \& | ^ V V | \& | | [po4a\-updatepo] | \& V | | V \& tradução.pot ^ V | \& | | doc.XX.po | \& | | (incerto) | \& { tradução } | | | \& | ^ V V \& | | {edição manual} | \& | | | | \& V | V V \& doc.XX.po \-\-\->\-\-\-\->+<\-\-\-<\-\- doc.XX.po adendo mestre.doc \& (inicial) (atualizado) (opcional) (atualizado) \& : | | | \& : V | | \& +\-\-\-\-\->\-\-\-\-\->\-\-\-\-\->\-\-\-\-\-\-> + | | \& | | | \& V V V \& +\-\-\-\-\-\->\-\-\-\-\-+\-\-\-\-\-\-<\-\-\-\-\-\-+ \& | \& V \& [po4a\-translate] \& | \& V \& XX.doc \& (atualizado) .Ve .PP Esse esquema é complicado, mas na prática apenas a parte correta (envolvendo \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 pega um documento original e seu equivalente traduzido, e tenta construir o arquivo \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 suas traduções existentes. Se você não tem nenhuma tradução para converter, você pode esquecer isso e focar na parte certa do esquema. .PP Na parte superior direita, a ação do autor original está descrita, atualização da documentação. A parte do meio, à direita, representa as ações automáticas do \fBpo4a\-updatepo\fR\|(1). Os novos materiais são extraídos e comparados com a tradução existente. A tradução anterior é usado para as partes que não foram alteradas, enquanto partes parcialmente modificadas também são conectadas à tradução anterior com uma marcação \*(L"fuzzy\*(R" indicando que a tradução deve ser atualizada. Material novo ou muito modificado é deixado sem tradução. .PP Então, a \fIedição manual\fR relatada representa a ação dos tradutores, que modificam os arquivo \s-1PO\s0 para fornecer traduções para toda string e parágrafo originais. Isso pode ser feito usando 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 usando uma plataforma de localização online como o \fBweblate\fR ou \fBpootle\fR. O resultado da tradução é um conjunto de arquivos \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 por sua contraparte traduzida. Opcionalmente, um adendo pode ser usado para adicionar um texto extra à tradução. Isso geralmente é usado para adicionar o nome do tradutor ao documento final. Veja abaixo os detalhes. .PP Como observado anteriormente, o programa \fBpo4a\fR\|(1) combina os efeitos dos scripts separados, atualizando os arquivos \s-1PO\s0 e o documento traduzido em uma chamada. A lógica subjacente permanece a mesma. .SS "Iniciando uma nova tradução" .IX Subsection "Iniciando uma nova tradução" Se você usar \fBpo4a\fR\|(1), não há etapa específica para iniciar uma tradução. Você apenas precisa listar os idiomas no arquivo de configuração, e os arquivos \s-1PO\s0 ausentes são criados automaticamente. Naturalmente, o tradutor deve fornecer traduções para todos os conteúdos usados em seus documentos. \fBpo4a\fR\|(1) também cria um arquivo \s-1POT,\s0 que é um arquivo de modelo de \s-1PO.\s0 Tradutores em potencial podem traduzir seu projeto para um novo idioma renomeando esse arquivo e fornecendo as traduções no idioma deles. .PP Se você preferir usar os scripts individuais separadamente, use \fBpo4a\-gettextize\fR\|(1) da seguinte maneira para criar o arquivo \s-1POT.\s0 Este arquivo 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 arquivo \s-1PO\s0 é a saída deste processo. .SS "Integrando alterações ao documento original" .IX Subsection "Integrando 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 arquivo \s-1PO\s0 é atualizado: ele é usado tanto na entrada quanto na saída. .SS "Gerando um documento traduzido" .IX Subsection "Gerando um documento traduzido" Assim que você finalizar com a tradução, você quer pegar a documentação traduzida e distribuí\-la para os usuários junto com o original. Para isso, use o programa \fBpo4a\-translate\fR\|(1) da seguinte forma: .PP .Vb 1 \& $ po4a\-translate \-\-format \-\-master \-\-po \-\-localized .Ve .PP Os arquivos mestre e \s-1PO\s0 são usados na entrada, enquanto o arquivo localizado é a saída desse processo. .SS "Usando adendos para adicionar texto extra às traduções" .IX Subsection "Usando adendos para adicionar texto extra às traduções" Adicionar novo texto à tradução é provavelmente a única coisa mais fácil a longo prazo quando você traduz arquivos manualmente :). Isso acontece quando você deseja adicionar uma seção extra ao documento traduzido, que não corresponde a nenhum conteúdo no documento original. O caso de uso clássico é dar créditos à equipe de tradução e indicar como relatar problemas específicos da tradução. .PP Com o po4a, é necessário especificar os arquivos \fBaddendum\fR, que podem ser vistos conceitualmente como patches aplicados ao documento localizado após o processamento. Cada adendo deve ser fornecido como um arquivo separado, cujo formato é, no entanto, muito diferente dos patches clássicos. A primeira linha é uma \fIlinha de cabeçalho\fR, definindo o ponto de inserção do adendo (com uma sintaxe infelizmente enigmática \*(-- veja abaixo) enquanto o restante do arquivo é adicionado literalmente na posição determinada. .PP A linha do cabeçalho deve começar com a string \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 colocado bem no final da tradução. .PP .Vb 1 \& PO4A\-HEADER: mode=eof .Ve .PP As coisas ficam mais complexas quando você deseja adicionar seu conteúdo extra no meio do documento. O cabeçalho a seguir declara um adendo que deve ser colocado após a seção \s-1XML\s0 que contém a string \f(CW\*(C`Sobre este documento\*(C'\fR na tradução. .PP .Vb 1 \& PO4A\-HEADER: position=Sobre este documento; 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 esqueça que o po4a considera o documento \fBtranslated\fR aqui. Esta documentação está em inglês, mas sua linha provavelmente deve ser a seguinte, se você pretende que seu adendo se aplique à tradução em francês do documento. .PP .Vb 1 \& PO4A\-HEADER: position=À propos de ce document; mode=after; endboundary= .Ve .PP Depois que a \f(CW\*(C`position\*(C'\fR é 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 seção atual). .PP O exato mesmo efeito pode ser obtido com o seguinte cabeçalho, que é equivalente: .PP .Vb 1 \& PO4A\-HEADER: position=About this document; 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 adicione o adendo \fBbefore\fR dessa linha, pois fornecemos um \fIbeginboundary\fR, ou seja, um limite que marca o início da próxima seção. Portanto, essa linha de cabeçalho exige a inserção do adendo após a seção que contém \f(CW\*(C`About this document\*(C'\fR e instrui o po4a que uma seção começa com uma linha que contém a tag \f(CW\*(C`. Isso é equivalente ao exemplo anterior, porque o que você realmente deseja é adicionar este adendo após \f(CW\*(C`/section\*(C'\fR> ou antes de \f(CW\*(C`. .PP Você 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 colocará 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 colocará 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 arquivo .Ve .PP \fIDicas e truques sobre adendos\fR .IX Subsection "Dicas e truques sobre adendos" .IP "\(bu" 4 Lembre-se de que estes são regexp. Por exemplo, se você deseja combinar o final de uma seção nroff que termina com a linha \f(CW\*(C`.fi\*(C'\fR, não use \f(CW\*(C`.fi\*(C'\fR como \fBendboundary\fR porque ele vai corresponder a \f(CW\*(C`the[ fi]le\*(C'\fR, o que obviamente não é o que está esperando. O \fBendboundary\fR correto neste caso é: \f(CW\*(C`^\e.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 à direita suficientes no documento traduzido. .Sp .Vb 2 \& PO4A\-HEADER: position=Sobre este documento; mode=after; beginboundary=
\& PO4A\-HEADER: position=Sobre este documento; mode=after; beginboundary=
.Ve .IP "\(bu" 4 Embora essa pesquisa de contexto possa ser considerada como operando aproximadamente em cada linha do documento \fBtraduzido\fR, ela realmente opera na cadeia de dados interna do documento traduzido. Essa cadeia de dados interna pode ser um texto abrangendo um parágrafo contendo várias linhas ou pode ser uma tag \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 string 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 você quiser adicionar alguma coisa após a seção nroff a seguir: .Sp .Vb 1 \& .SH "AUTHORS" .Ve .Sp Você deve selecionar uma abordagem em duas etapas configurando \fBmode=after\fR. Em seguida, você deve restringir a pesquisa à linha após \fB\s-1AUTHORS\s0\fR com a regex de argumento \fBposition\fR. Então, você deve combinar o início da próxima seçã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=AUTHORS;beginboundary=\e.SH .Ve .IP "\(bu" 4 Se você quiser adicionar alguma coisa após a linha dada (ex,. após a linha \*(L"Copyright Grande Cara\*(R") use um \fBposition\fR correspondendo a esta linha, \fBmode=after\fR e forneça um \fBbeginboundary\fR correspondendo a qualquer linha. .Sp .Vb 1 \& PO4A\-HEADER:mode=after;position=Copyright Grande Cara, 2004;beginboundary=^ .Ve .IP "\(bu" 4 Se você quiser adicionar alguma coisa ao final do documento, forneça um \fBposition\fR correspondendo a qualquer linha do seu documento (mas apenas uma linha. Po4a não vai proceder se ela não for única), e forneça um \fBendboundary\fR correspondendo a nada. Não use strings simples aqui como \fB\*(L"\s-1EOF\*(R"\s0\fR, e sim prefira aquelas que possuem menos chance de 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 (formatado em \s-1POD\s0): .PP .Vb 7 \& |=head1 NAME \& | \& |dummy \- a dummy program \& | \& |=head1 AUTHOR \& | \& |me .Ve .PP Então, o adendo a seguir vai assegurar que a seção (em Francês) sobre o tradutor seja adicionado ao final do arquivo (em Francês, \*(L"\s-1TRADUCTEUR\*(R"\s0 significa \*(L"\s-1TRADUTOR\*(R",\s0 e \*(L"moi\*(R" significa \*(L"eu\*(R"). .PP .Vb 6 \& |PO4A\-HEADER:mode=after;position=AUTEUR;beginboundary=^=head \& | \& |=head1 TRADUCTEUR \& | \& |moi \& | .Ve .PP Para colocar seu adendo antes do \s-1AUTHOR,\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 correspondendo ao \fBbeginboundary\fR /^=head1/ após a seção \*(L"\s-1NAME\*(R"\s0 (traduzido para \*(L"\s-1NOM\*(R"\s0 em Francês) é aquela declarando os autores. Então, o adendo será colocado entre as duas seções. Note que se outra seção for adicionada entre as seções \s-1NAME\s0 e \s-1AUTHOR\s0 posteriormente, po4a colocará o adendo equivocadamente antes da nova seção. .PP Para evitar isto, você pode realizar o mesmo usando \fBmode\fR=\fIbefore\fR: .PP .Vb 1 \& PO4A\-HEADER:mode=before;position=^=head1 AUTEUR .Ve .SH "Como ele funciona?" .IX Header "Como ele funciona?" Este capítulo dá a você uma visão geral da parte interna do po4a, de forma que você pode se sentir mais confiante para nos ajudar a manter e melhorá\-lo. ele também pode ajudá\-lo a entender o porquê de ele não funcionar da forma que você esperava, e como resolver seus problemas. .PP A arquitetura do po4a é orientada a objeto. A classe \fBLocale::Po4a::TransTractor\fR\|(3pm) é um antepassado comum para todos analisadores do po4a. Esse nome estranho vem do fato que ele é ao mesmo tempo o encarregado por tradução de documento e extração de strings. .PP Mais formalmente, ele pega um documento para traduzir mais um arquivo \s-1PO\s0 contendo as traduções para usar como entrada, enquanto produz duas saídas separadas: outro arquivo \s-1PO\s0 (resultante da extração das strings traduzíveis do documento de entrada) e um documento traduzido (com a mesma estrutura daquele de entrada, mas com todas as strings traduzíveis substituídas com o conteúdo do \s-1PO\s0 de entrada). Aqui está uma representação gráfica disso: .PP .Vb 6 \& Doc. de entrada \-\-\e /\-\-\-> Doc. de saída \& \e TransTractor:: / (traduzido) \& +\-\->\-\- parse() \-\-\-\-\-\-\-\-+ \& / \e \& PO de entrada \-\-\-\-/ \e\-\-\-> PO de saída \& (extraído) .Ve .PP Esse pequeno osso é o núcleo de toda arquitetura do po4a. Se você omitir o \s-1PO\s0 de entrada e o documento de saída, você obtém \fBpo4a\-gettextize\fR. Se você fornecer ambos arquivos de entrada e desconsiderar o \s-1PO\s0 de saída, você 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 arquivo 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 sua documentação. Se você quiser adicionar seu projeto à lista, basta nos enviar um e\-mail (ou uma merge request). .IP "\(bu" 4 adduser (man): ferramenta de gerenciamento de usuários e grupos. .IP "\(bu" 4 apt (man, docbook): Gerenciador de pacotes do Debian. .IP "\(bu" 4 aptitude (docbook, svg): Gerenciador de pacotes em interface de texto para Debian .IP "\(bu" 4 Site do F\-Droid (markdown): catálogo instalável de aplicativos \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 "FAQ" .IX Header "FAQ" .SS "Como você pronuncia po4a?" .IX Subsection "Como você pronuncia po4a?" Eu pessoalmente vocalizo-o como pouah , que é um onomatopoético francês que usamos no lugar de \*(L"eca\*(R" :) eu posso ter um senso de humor estranho :) .SS "E as outras ferramentas de tradução para documentação usando gettext?" .IX Subsection "E as outras ferramentas de tradução para documentação usando 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" Essa é a ferramenta desenvolvida pelo pessoal do \s-1KDE\s0 para manipular DocBook \s-1XML.\s0 Até onde eu sei, esse foi o primeiro programa a extrair strings para traduzir de documentação para arquivos \s-1PO,\s0 e a injetá\-las de volta após a tradução. .Sp Ela só consegue manipular \s-1XML\s0 e apenas um \s-1DTD\s0 em particular. Eu fico, particularmente, não gosto das listas de manipulação, que acabam com um grande msgid. Quando a lista fica grande, o fragmento se torna mais difícil de engolir. .IP "\fBpo-debiandoc\fR" 4 .IX Item "po-debiandoc" Esse problema desenvolvido por Denis Barbier é uma espécie de precursor do módulo de \s-1SGML\s0 do po4a, o qual meio que torna-o (po-debiandoc) obsoleto. Como o nome já diz, ele linda apenas o DebianDoc \s-1DTD,\s0 o qual é meio que 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 do po4a sobre eles é a facilidade de adição de conteúdo extra (o que é bem pior lá) e a habilidade de alcançar gettextização. .SS "\s-1RESUMO\s0 das vantagens da abordagem baseada em gettext" .IX Subsection "RESUMO das vantagens da abordagem baseada em gettext" .IP "\(bu" 2 As traduções não são armazenadas junto do original, o que possibilita detectar se as traduções estão desatualizadas. .IP "\(bu" 2 As traduções são armazenadas em arquivos separados um dos outros, o que previne tradutores de idiomas diferentes interferir tanto quando da submissão do patch quanto a nível de codificação do arquivo. .IP "\(bu" 2 Ele é internamente baseado no \fBgettext\fR (mas \fBpo4a\fR oferece uma interface bem simples, de forma que você não precisa entender as especificidades para usá\-lo). Dessa forma, nós não temos que reinventar a roda e, por causa do seu amplo uso, nós podemos pensar que essas ferramentas meio que não tem erros. .IP "\(bu" 2 Nada mudou para o usuário final (além do fato de traduções estarem melhor mantidas, espero). o arquivo de documentação resultante distribuído é exatamente o mesmo. .IP "\(bu" 2 Não há necessidade de tradutores aprenderem um novo arquivo de sintaxe e seu editor de arquivos \s-1PO\s0 (como o modo \s-1PO\s0 do Emacs, Lokalize ou Gtranslator) vão funcionar muito bem. .IP "\(bu" 2 gettext oferece uma forma simples de obter estatísticas sobre o que está feito, o que deveria ser revisto e atualizado e o que ainda deve ser feito. Alguns exemplos podem ser encontrados nesses 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 tudo tem seu lado negativo, e essa abordagem tem algumas desvantagens com as quais nós temos que lidar. .IP "\(bu" 2 Adendos são… estranhos à primeira vista. .IP "\(bu" 2 Você não pode adaptar o texto traduzido às suas preferências, com divisão de um parágrafo aqui e juntar outros dois ali. Mas de certa forma, se há um problema com o original, isso deveria ser relatado como um erro. .IP "\(bu" 2 Até mesmo com uma interface fácil, ainda é uma nova ferramenta que as pessoas precisam aprender. .Sp Um dos meus sonhos seria integrar de alguma forma po4a ao Gtranslator ou Lokalize. Quando um arquivo de documento fosse aberto, as strings seriam automaticamente extraídas e um arquivo traduzido + arquivo po poderia ser gravado no disco. Se nós conseguirmos fazer um módulo para \s-1MS\s0 Word (\s-1TM\s0) (ou pelo menos \s-1RTF\s0), tradutores profissionais podem até mesmo usá\-lo. .SH "VEJA TAMBÉM" .IX Header "VEJA TAMBÉM" .IP "\(bu" 4 A documentação da ferramenta multifuncional que você 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, em particular 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 arquivo \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