.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) .\" .\" 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 .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" ======================================================================== .\" .IX Title "PO4A 7" .TH PO4A 7 "2018-12-17" "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" O objetivo do projeto po4a (\s-1PO\s0 para tudo) é facilitar traduções (e mais interessante, a manutenção das traduções) usando ferramentas gettext em áreas onde eles não eram esperados como documentação. .SH "Tabela de conteúdo" .IX Header "Tabela de conteúdo" Este documento está organizado da seguinte forma: .IP "1 Porque deveria eu usar po4a? É bom para quê?" 4 .IX Item "1 Porque deveria eu usar po4a? É bom para quê?" Este capítulo de introdução explica a motivação do projeto e sua filosofia. Você deve lê\-lo primeiro, se você está no processo de avaliação do po4a para suas próprias traduções. .IP "2 Como usar po4a?" 4 .IX Item "2 Como usar po4a?" Este capítulo é uma espécie de manual de referência, tentando responder às perguntas dos utilizadores e dar-lhes uma melhor compreensão de todo o processo. Este introduz o modo de fazer as coisas com po4a e serve como uma apresentação à documentação das ferramentas específicas. .RS 4 .IP "\s-1COMO\s0 começar uma nova tradução?" 4 .IX Item "COMO começar uma nova tradução?" .PD 0 .IP "\s-1COMO\s0 mudar a tradução de volta para um ficheiro de documentação?" 4 .IX Item "COMO mudar a tradução de volta para um ficheiro de documentação?" .IP "\s-1COMO\s0 atualizar uma tradução po4a?" 4 .IX Item "COMO atualizar uma tradução po4a?" .IP "\s-1COMO\s0 converter uma tradução pré\-existente para po4a?" 4 .IX Item "COMO converter uma tradução pré-existente para po4a?" .IP "\s-1COMO\s0 adicionar texto extra para traduções (como o nome do tradutor)?" 4 .IX Item "COMO adicionar texto extra para traduções (como o nome do tradutor)?" .IP "\s-1COMO\s0 fazer tudo numa invocação de programa?" 4 .IX Item "COMO fazer tudo numa invocação de programa?" .IP "\s-1COMO\s0 personalizar po4a?" 4 .IX Item "COMO personalizar po4a?" .RE .RS 4 .RE .IP "3 Como é que funciona?" 4 .IX Item "3 Como é que funciona?" .PD Este capítulo dá\-nos uma visão geral interna do po4a, de modo a que você se possa sentir 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 você esperava, e como resolver os seus problemas. .IP "4 \s-1FAQ\s0" 4 .IX Item "4 FAQ" This chapter groups the Frequently Asked Questions. In fact, most of the questions for now could be formulated that way: \*(L"Why is it designed this way, and not that one?\*(R" If you think po4a isn't the right answer to documentation translation, you should consider reading this section. If it does not answer your question, please contact us on the mailing list. We love feedback. .IP "5 Notas específicas sobre módulos" 4 .IX Item "5 Notas específicas sobre módulos" Este capítulo apresenta as especificidades de cada módulo a partir do ponto vista do tradutor e do autor original. Leia este capítulo para aprender a sintaxe que você irá encontrar ao traduzir coisas neste módulo, ou as regras que deve seguir no seu documento original para tornar a vida dos tradutores mais fácil. .Sp Na verdade, esta secção não é realmente parte deste documento. Ao invés disso, é colocada na documentação de cada módulo. Isto ajuda a garantir que a informação é atualizada, mantendo a documentação e o código juntos. .SH "Porque deveria eu usar po4a? Para que é bom?" .IX Header "Porque deveria eu usar po4a? Para que é bom?" Eu gosto da idéia de software de código aberto, tornando possível para todos o acesso ao software e seu código fonte. Mas, sendo francês, eu estou bem ciente que O licenciamento não é a única restrição à abertura do software: software livre não traduzido é inútil para quem não fala inglês, e nós ainda temos algum trabalho para realmente torná\-lo disponível para todo o mundo. .PP A percepção desta situação por parte dos atores do código aberto melhorou drasticamente recentemente. Nós, como tradutores, ganhamos a primeira batalha e convencemos todo mundo da importância das traduções. Mas infelizmente, foi a parte fácil. Agora, temos que fazer o trabalho e realmente traduzir todas estas coisas. .PP Atualmente, o software de código aberto beneficia de um nível decente de tradução, graças ao conjunto maravilhoso de ferramentas gettext. Ele é capaz de extrair as sequências a traduzir do programa, apresentar um formato uniforme aos tradutores, e depois usar o resultado de seus trabalhos em tempo de execução para exibir mensagens traduzidas para o utilizador. .PP But the situation is rather different when it comes to documentation. Too often, the translated documentation is not visible enough (not distributed as a part of the program), only partial, or not up to date. This last situation is by far the worst possible one. Outdated translation can turn out to be worse than no translation at all to the users by describing old program behavior which are not in use anymore. .SS "O problema para resolver" .IX Subsection "O problema para resolver" Traduzindo documentação não é muito difícil em si mesmo. Os textos são muito mais longos do que as mensagens do programa e assim, levar mais tempo a ser alcançado, mas nenhuma habilidade técnica é realmente necessária para fazê\-lo. A parte difícil vem quando você tem que manter o seu trabalho. Detectar em quais partes fez a mudança e precisam ser atualizadas é muito difícil, propenso a erros e altamente desagradável. Eu acho que isso explica por que é que há tanta documentação traduzida ultrapassada. .SS "As respostas po4a" .IX Subsection "As respostas po4a" Então, todo o ponto de po4a é fazer a tradução da documentação \&\fImaintainable\fR. A ideia é reutilizar a metodologia gettext para esse novo campo. Como em gettext, os textos são extraídos dos seus locais originais em ordem a serem apresentado num formato uniforme para os tradutores. As ferramentas clássicas gettext ajuda-os a atualizar as suas obras quando uma nova versão do original sai. Mas com a diferença do modelo clássico gettext, as traduções são re-injetadas na estrutura do documento original de modo que podem ser processadas ​​e distribuídas como a verão inglesa. .PP Graças a isso, descobrir quais partes do documento foram alteradas e precisam de uma atualização torna-se muito fácil. Outro ponto positivo é que as ferramentas fazem quase todo o trabalho quando a estrutura do documento original fica fundamentalmente reorganizado e quando alguns capítulos são movimentados, fundidos ou divididos. Ao extrair o texto para traduzir de uma estrutura do documento, você mantém\-se longe da complexidade de formatação de texto e reduz as suas chances de obter um documento partido (mesmo se não o impedir completamente de o fazer). .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: .PP \fImanual\fR .IX Subsection "manual" .PP O bom e velho formato de páginas de manual, usado por muitos programas por aí. O suporte po4a é muito bem-vindo aqui, pois este formato é um pouco difícil de usar e não é muito amigável para os novatos. O módulo \&\fILocale::Po4a::Man\fR\|(3pm) também suporta o formato mdoc, usado por aspáginas de manual \s-1BSD \s0(também elas são bastante comuns no Linux). .PP \fIpod\fR .IX Subsection "pod" .PP Este é o formato de Documentação Perl Online. A linguagem e as extensões em si são documentados desta maneira, assim como a maior parte dos scripts Perl existentes. Isso torna-se fácil de manter a documentação junto ao código atual por incorporação de ambos no mesmo ficheiro. Isso torna mais fácil a vida mais fácil ao programador, mas infelizmente, não ao tradutor. .PP \fIsgml\fR .IX Subsection "sgml" .PP Mesmo que um pouco substituído por \s-1XML\s0 hoje em dia, este formato é ainda com frequência bastante usado para documentos que são mais do que alguns ecrans de comprimento. Ele permite-lhe fazer livros completos. Atualizando assim a tradução de documentos longos pode revelar-se um verdadeiro pesadelo. \fBdiff\fR revela-se muitas vezes inútil, quando o texto original foi recortado após a atualização. Felizmente, po4a pode ajudá\-lo nesse processo. .PP Atualmente, são suportados apenas o DebianDoc e DocBook, mas acrescentando suporte para um novo, é muito simples. É até possível usar po4a num \s-1SGML DTD\s0 desconhecido sem alterar o código, fornecendo as necessárias informações sobre a linha de comando. Veja \fILocale::Po4a::Sgml\fR\|(3pm) para obter mais detalhes. .PP \fITeX / LaTeX\fR .IX Subsection "TeX / LaTeX" .PP O formato LaTeX é o principal formato de documentação usado nas publicações de Software Livre mundiais. O módulo \fILocale::Po4a::LaTeX\fR\|(3pm) foi testado com documentação Python, um livro e algumas apresentações. .PP \fItexinfo\fR .IX Subsection "texinfo" .PP Toda a documentação \s-1GNU\s0 está escrita neste formato (que é ainda um dosrequisito para um projeto \s-1GNU\s0 se tornar oficial). O apoio para \&\fILocale::Po4a::Texinfo\fR\|(3pm) em po4a ainda está no início.Por favor, reporte erros e solicitações de recursos. .PP \fIxml\fR .IX Subsection "xml" .PP O formato \s-1XML\s0 é um formato de base para muitos formatos de documentação .PP Atualmente, o DocBook \s-1DTD\s0 é suportado por po4a. Veja\fILocale::Po4a::Docbook\fR\|(3pm) para obter mais detalhes. .PP \fIoutros\fR .IX Subsection "outros" .PP Po4a também pode lidar com alguns formatos mais raros ou especializados, como a documentação de opções de compilação para os kernels 2.4+ ou os diagramas produzidos pela ferramenta Dia. Adicionar um novo é muitas vezes bastante fácil e a tarefa principal é chegar com um analisador de seu formato de destino. Consulte \fILocale::Po4a::TransTractor\fR\|(3pm) para obter mais informações sobre isso. .SS "Formatos não suportados" .IX Subsection "Formatos não suportados" Infelizmente, po4a ainda carece de suporte para diversos formatos de documentação. .PP Há um monte de outros formatos que gostaríamos que fossem suportados em po4a e não só os de documentação. De fato, pretendemos ligar todos os \*(L"market holes\*(R" deixados pelas ferramentas clássicas gettext. Abranger descrições de pacotes (deb e rpm), scripts de perguntas de pacotes de instalação, pacotes com registos das modificações (changelogs), e todos os formatos de ficheiros especializados utilizados pelos programas como cenários de jogos ou ficheiros de recursos do Wine. .SH "Como usar po4a?" .IX Header "Como usar po4a?" Este capítulo é uma espécie de manual de referência, tentando responder às perguntas dos utilizadores e dar-lhes uma melhor compreensão de todo o processo. Este introduz o modo de fazer as coisas com po4a e serve como uma apresentação à documentação das ferramentas específicas. .SS "Visão geral gráfica" .IX Subsection "Visão geral gráfica" O esquema a seguir dá uma visão geral do processo de tradução de documentação usando po4a. Não tenha medo da sua aparente complexidade, vem do fato de que o processo \fIwhole\fR é representado aqui. Uma vez que você converteu seu projeto para po4a, apenas a parte direita do gráfico é relevante. .PP Note that \fImaster.doc\fR is taken as an example for the documentation to be translated and \fItranslation.doc\fR is the corresponding translated text. The suffix could be \fI.pod\fR, \fI.xml\fR, or \fI.sgml\fR depending on its format. Each part of the picture will be detailed in the next sections. .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 On the left part, the conversion of a translation not using po4a to this system is shown. On the top of the right part, the action of the original author is depicted (updating the documentation). The middle of the right part is where the automatic actions of po4a are depicted. The new material are extracted, and compared against the exiting translation. Parts which didn't change are found, and previous translation is used. Parts which were partially modified are also connected to the previous translation, but with a specific marker indicating that the translation must be updated. The bottom of the figure shows how a formatted document is built. .PP Actually, as a translator, the only manual operation you have to do is the part marked {manual editing}. Yeah, I'm sorry, but po4a helps you translate. It does not translate anything for you… .SS "\s-1COMO\s0 começar uma nova tradução?" .IX Subsection "COMO começar uma nova tradução?" Esta secção apresenta os passos necessários requeridos para começar uma nova tradução com po4a. os refinamentos envolvidos na conversão de um projeto existente para este sistema estão detalhados na secção relevante. .PP Para começar uma nova tradução usando po4a, você tem que fazer os seguintes passos: .IP "\-" 2 Extrair o texto que tem que ser traduzido a partir do original <\fImaster.doc\fR> documento num novo modelo de nova tradução <\fItranslation.pot\fR> ficheiro (o formato gettext). Para isso, use oprograma \fBpo4a\-gettextize\fR desta maneira: .Sp .Vb 1 \& $ po4a\-gettextize \-f \-m \-p .Ve .Sp <\fIformato\fR> é naturalmente o formato usado no documento \&\fImaster.doc\fR. Como esperado, a saída vai para \fItranslation.pot\fR. Por favor referir para \fIpo4a\-gettextize\fR\|(1) para obter mais detalhes sobre as opções existentes. .IP "\-" 2 Na verdade, traduzir o que deve ser traduzido. Para isso, você tem que mudar o nome do ficheiro \s-1POT,\s0 por exemplo para \fIdoc.XX.po\fR (onde \fIxx\fR é o código de \s-1ISO 639\-1\s0 do idioma em que está a traduzir, por exemplo, para \fBfr\fR francês), e editar o ficheiro resultante. Muitas vezes, é uma boa idéia para não nomear o ficheiro \fI\s-1XX\s0.po\fR para evitar confusão com a tradução das mensagens do programa, mas esta invocação é sua. Não se esqueça de atualizar os cabeçalhos dos ficheiros \s-1PO,\s0 eles são importantes. .Sp A tradução real pode ser feita utilizando-se os modos Emacs ou Vi \s-1PO,\s0 Lokalize (baseado em \s-1KDE\s0), gTranslator (baseado em \s-1GNOME\s0) ou qualquer programa que você prefira usar em vez destes (por exemplo Virtaal). .Sp Se você quiser saber mais sobre isto, definitivamente precisa de consultar a documentação gettext, disponível no pacote \fBgettext-doc\fR. .SS "\s-1COMO\s0 mudar a tradução de volta para um ficheiro de documentação?" .IX Subsection "COMO mudar a tradução de volta para um ficheiro de documentação?" Uma vez que você acabou a sua tradução, deseja obter a documentação traduzida e distribuí\-la aos utilizadores, juntamente com o original. Para isso, use o programa \fIpo4a\-translate\fR\|(1) assim (onde \fIxx\fR é o código de linguagem): .PP .Vb 1 \& $ po4a\-translate \-f \-m \-p \-l .Ve .PP As before, <\fIformat\fR> is the format used in the \fImaster.doc\fR document. But this time, the \s-1PO\s0 file provided with the \fB\-p\fR flag is part of the input. This is your translation. The output goes into \fI\s-1XX\s0.doc\fR. .PP Por favor, consulte \fIpo4a\-translate\fR\|(1) para mais detalhes. .SS "\s-1COMO\s0 atualizar uma tradução po4a?" .IX Subsection "COMO atualizar uma tradução po4a?" Para atualizar a sua tradução quando o ficheiro original \fImaster.doc\fR mudou, use o programa \fIpo4a\-updatepo\fR\|(1) assim: .PP .Vb 1 \& $ po4a\-updatepo \-f \-m \-p .Ve .PP (Por favor, consulte \fIpo4a\-updatepo\fR\|(1) para mais detalhes) .PP Naturalmente, o novo parágrafo no documento não será magicamente traduzido no ficheiro \s-1PO\s0 com esta operação, e você precisa atualizar o ficheiro \s-1PO\s0 manualmente. Da mesma forma, pode ter que refazer a tradução de parágrafos que foram um pouco modificados. Para se certificar de que não vai perder nenhum deles, eles são marcados como \*(L"fuzzy\*(R" durante o processo e tem que remover esse marcador antes da tradução poder ser usada por \&\fBpo4a\-translate\fR. Quanto à tradução inicial, o melhor é usar o seu editor favorito \s-1PO\s0 aqui. .PP Depois que o ficheiro \s-1PO\s0 é atualizado de novo, sem qualquer falta de sequência não traduzida ou imprecisa (fuzzy), você pode gerar um ficheiro de documentação traduzida, como explicado na secção anterior. .SS "\s-1COMO\s0 converter uma tradução pré\-existente para po4a?" .IX Subsection "COMO converter uma tradução pré-existente para po4a?" Muitas vezes, você alegremente traduziu manualmente o documento até uma grande reorganização do documento original \fImaster.doc\fR aconteceu. Então, depois algumas tentativas desagradáveis ​​com \fBdiff\fR ou ferramentas similares, você deseja converter em po4a. Mas, claro, você não quer perder sua tradução existente no processo. não se preocupe, neste caso, também é tratado por ferramentas po4a e é chamado gettextization. .PP O importante aqui é para ter a mesma estrutura no documento traduzido e no original, de modo que as ferramentas possam combinar o conteúdo adequadamente. .PP Se você tiver sorte (ou seja, se as estruturas de ambos os documentos se adequarem perfeitamente), vai funcionar perfeitamente e vai ser definido em poucos segundos. Caso contrário, você pode entender porque este processo tem um nome feio, e é melhor estar preparado para algum trabalho duro aqui. Em qualquer caso, lembre-se que é o preço a pagar para ter o conforto de po4a depois. E o bom é que tem que fazer isso apenas uma vez. .PP Não posso enfatizar demasiado. A fim de facilitar o processo, é assim importante que você encontre a versão exata onde foram utilizados para fazer a tradução. A melhor situação é quando anotou a revisão do \s-1VCS\s0 usado para a tradução e não o modificou no processo de tradução, por isso pode usá\-lo. .PP Isso não vai funcionar bem quando você usa o texto original atualizado com a tradução antiga. Continua a ser possível, mas é mais difícil e realmente deve ser evitado se possível. Na verdade, eu acho que se não encontrar o texto original novamente, a melhor solução é encontrar alguém para lhe fazer a gettextization (mas, por favor, eu não ;). .PP Talvez seja muito dramático aqui. Mesmo quando as coisas estão erradas, restam maneiras mais rápidas do que traduzir tudo de novo. Eu era capaz de gettextizar a tradução francesa existente da documentação Perl num dia, até mesmo quando as coisas \fBdid\fR estão erradas. Isso foi há mais de dois megabytes de texto, e uma nova tradução teria durado meses ou mais. .PP Deixe-me explicar a base do primeiro procedimento e vou voltar com dicas para o alcançar quando o processo dá errado. Para facilitar a compreensão, Vamos usar o exemplo acima, mais uma vez. .PP Uma vez que você tem o antigo \fImaster.doc\fR outra vez que coincide com a tradução \fI\s-1XX\s0.doc\fR, a gettextização pode ser feita diretamente para o ficheiro \s-1PO \s0\fIdoc.XX.po\fR sem a tradução manual do ficheiro \&\fItranslation.pot\fR: .PP .Vb 1 \& $ po4a\-gettextize \-f \-m \-l \-p .Ve .PP Quando você tiver sorte, é isso. Converteu sua antiga tradução para po4a e pode começar com a tarefa de atualização imediatamente. Basta seguir o procedimento explicado uma secção um pouco atrás para sincronizar seus ficheiros \s-1PO\s0 com o mais novo documento original e, atualizar a tradução em conformidade. .PP Por favor note que, mesmo quando as coisas parecem funcionar corretamente, ainda há espaço para erros neste processo. A questão é que po4a é incapaz de compreender o texto para se certificar de que a tradução coincidir com o original. É por isso que todas as sequências são marcadas como \*(L"fuzzy\*(R" no processo. Você deve verificar cada um cuidadosamente antes de retirar os marcadores. .PP Muitas vezes, as estruturas dos documentos não correspondem exatamente, evitando \fBpo4a\-gettextize\fR de fazer seu trabalho corretamente. Neste ponto, o jogo total é sobre a edição dos ficheiros para obter a harmonia entre as malditas estruturas. .PP Pode ajudar a ler a secção \fBGettextization: como é que funciona?\fR abaixo. Compreender o processo interno vai ajudá\-lo a fazer este trabalho. O bom ponto é que \fBpo4a\-gettextize\fR é bastante detalhado sobre o que deu errado, quando isso acontece. Primeiro, ele aponta nas estruturas dos documentos onde são as discrepâncias. Vai aprender que as sequências não correspondem, a suas posições no texto e, o tipo de cada uma delas. Além disso, o ficheiro \s-1PO\s0 gerado até agora, vai ser despejado para \&\fIgettextization.failed.po\fR. .IP "\-" 4 Remova todas as peças extras das traduções, como a secção em que você dá o nome do tradutor e agradece a todas as pessoas que contribuíram para a tradução. Adenda, que são descritos na secção seguinte, permitirá voltar a adicioná\-los mais tarde. .IP "\-" 4 Não hesite em editar o original e a tradução. A coisa mais importante é obter o ficheiro \s-1PO.\s0 Você será capaz de atualizá\-lo depois. Dito isto, a edição da tradução deve ser preferida quando ambos são possíveis uma vez que torna as coisas mais fáceis quando a gettextization está feita. .IP "\-" 4 Se necessário, mate algumas partes do original, se acontecer não serem traduzidas. Ao sincronizar o \s-1PO\s0 com o documento mais tarde, eles vão voltar de si mesmos. .IP "\-" 4 Se você mudou um pouco a estrutura (para fundir dois parágrafos, ou dividiu uma outra), desfaça as alterações. Se houver problemas no original, deve informar o autor original. Corrigi-los em sua tradução só os corrige para uma parte da comunidade. E, além disso, é impossível quando usando po4a ;) .IP "\-" 4 Sometimes, the paragraph content does match, but their types don't. Fixing it is rather format-dependent. In \s-1POD\s0 and man, it often comes from the fact that one of the two contains a line beginning with a white space where the other doesn't. In those formats, such paragraph cannot be wrapped and thus become a different type. Just remove the space and you are fine. It may also be a typo in the tag name. .Sp Likewise, two paragraphs may get merged together in \s-1POD\s0 when the separating line contains some spaces, or when there is no empty line between the =item line and the content of the item. .IP "\-" 4 Às vezes, há uma dessincronização entre os ficheiros, e a tradução está ligada ao ponto errado original. É o sinal de que o verdadeiro problema estava antes nos ficheiros. Verifique \fIgettextization.failed.po\fR para ver quando a dessincronização começa, e corrigi-la lá. .IP "\-" 4 Sometimes, you get the strong feeling that po4a ate some parts of the text, either the original or the translation. \fIgettextization.failed.po\fR indicates that both of them were gently matching, and then the gettextization fails because it tried to match one paragraph with the one after (or before) the right one, as if the right one disappeared. Curse po4a as I did when it first happened to me. Generously. .Sp Esta situação infeliz acontece quando o mesmo parágrafo é repetido sobre odocumento. Neste caso, não é criada uma nova entrada no ficheiro de \s-1PO,\s0 mas uma nova referência é adicionada ao já existente em seu lugar. .Sp So, when the same paragraph appears twice in the original but both are not translated in the exact same way each time, you will get the feeling that a paragraph of the original disappeared. Just kill the new translation. If you prefer to kill the first translation instead when the second one was actually better, replace the first one with the second. .Sp No contrário, se dois parágrafos semelhantes, mas diferentes foram traduzidos exatamente da mesma maneira, você terá a sensação de que um parágrafo da tradução desapareceu. Uma solução é adicionar uma sequência estúpida ao parágrafo original (como \*(L"Eu sou diferente\*(R"). Não tenha medo, essas coisas vão desaparecer durante a sincronização, e quando o texto adicionado é suficiente curto, gettext irá corresponder a sua tradução para o texto existente (marcando-o como impreciso (fuzzy), mas você realmente não se importa uma vez que todas as sequências são fuzzy depois da gettextization). .PP Esperamos que estas dicas o irão ajudar a fazer o seu trabalho de gettextization e obter o precioso ficheiro \s-1PO.\s0 Agora você está pronto para sincronizar o seu ficheiro e começar a tradução. Note que no texto grande, pode acontecer que a primeira sincronização demore um longo tempo. .PP Por exemplo, o primeiro \fBpo4a\-updatepo\fR da tradução de documentação Perl em francês (ficheiro \s-1PO 5,5\s0 Mb) demorou cerca de dois dias num computador G5 1Ghz. Sim, 48 horas. Mas as subsequentes levam apenas uma dúzia de segundos no meu velho portátil. É assim porque na primeira vez, a maioria das 'msgid' do ficheiro \s-1PO\s0 não correspondem a nenhum dos ficheiros \s-1POT\s0 existentes. Isto força o gettext a procurar o mais próximo, utilizando um caro algoritmo de proximidade de sequências. .SS "\s-1COMO\s0 adicionar texto extra para traduções (como o nome do tradutor)?" .IX Subsection "COMO adicionar texto extra para traduções (como o nome do tradutor)?" Por causa da abordagem ao gettext, fazendo isto torna-se mais difícil em po4a do que era quando a simples edição de um novo ficheiro ao longo do original. Mas continua a ser possível, graças ao chamado \fBaddenda\fR. .PP Pode ajudar a compreensão de considerar adendas como uma espécie de remendos aplicados ao documento localizado após o processamento. Eles são bastante diferentes dos habituais 'patches' (têm apenas uma linha de contexto, que pode incorporar expressão regular Perl, e só podem adicionar novo texto sem remover nenhum), mas as funcionalidades são as mesmas. .PP O seu objetivo é permitir que o tradutor possa adicionar conteúdo extra para o documento que não é traduzido a partir do documento original. O uso mais comum é adicionar uma secção sobre a sua própria tradução, lista de colaboradores e explicando como reportar uma erro contra a tradução. .PP Uma adenda deve ser fornecida como um ficheiro separado. A primeira linha constitui um cabeçalho que indica onde o documento produzido deve ser colocado. O resto do ficheiro adenda será adicionado textualmente em determinada posição do documento resultante. .PP The header line which specify context has a pretty rigid syntax: It must begin with the string \fB\s-1PO4A\-HEADER:\s0\fR, followed by a semi-colon (\fB;\fR) separated list of \fIkey\fR\fB=\fR\fIvalue\fR fields. White spaces \s-1ARE\s0 important. Note that you cannot use the semi-colon char (\fB;\fR) in the value, and that quoting it doesn't help. Optionally, spaces (\fB \fR) may be inserted before \fIkey\fR for readability. .PP Although this context search may be considered to operate roughly on each line of the translated document, it actually operates on the internal data string of the translated document. This internal data string may be a text spanning a paragraph containing multiple lines or may be a \s-1XML\s0 tag itself alone. The exact \fIinsertion point\fR of the addendum must be before or after the internal data string and can not be within the internal data string. .PP The actual internal data string of the translated document can be visualized by executing po4a in debug mode. .PP Mais uma vez, parece assustador, mas os exemplos dados a seguir devem ajudá\-lo a encontrar como escrever a linha de cabeçalho que precisa. Para ilustrar a discussão, assuma que queremos adicionar uma secção chamada \&\*(L"Sobre esta tradução\*(R" depois uma \*(L"Sobre este documento\*(R". .PP Aqui estão as chaves do cabeçalho possíveis: .IP "\fBmode\fR (obrigatório)" 4 .IX Item "mode (obrigatório)" It can be either the string \fBbefore\fR or \fBafter\fR. .Sp If \fBmode=before\fR, the \fIinsertion point\fR is determined by one step regex match specified by the \fBposition\fR argument regex. The \fIinsertion point\fR is immediately before the uniquely matched internal data string of the translated document. .Sp If \fBmode=after\fR, the \fIinsertion point\fR is determined by two step regex matches specified by the \fBposition\fR argument regex; and by the \&\fBbeginboundary\fR or \fBendboundary\fR argument regex. .Sp Since there may be multiple sections for the assumed case, let's use 2 step approach. .Sp .Vb 1 \& mode=after .Ve .IP "\fBposition\fR (obrigatório)" 4 .IX Item "position (obrigatório)" A Perl regexp for specifying the context. .Sp If more than one internal data strings match this expression (or none), the search for the \fIinsertion point\fR and addition of the addendum will fail. It is indeed better to report an error than inserting the addendum at the wrong location. .Sp If \fBmode=before\fR, the \fIinsertion point\fR is specified to be immediately before the internal data string uniquely matching the \fBposition\fR argument regex. .Sp If \fBmode=after\fR, the search for the \fIinsertion point\fR is narrowed down to the data after the internal data string uniquely matching the \fBposition\fR argument regex. The exact \fIinsertion point\fR is further specified by the \&\fBbeginboundary\fR or \fBendboundary\fR. .Sp In our case, we need to skip several preceding sections by narrowing down search using the section title string. .Sp .Vb 1 \& position=About this document .Ve .Sp (In reality, you need to use the translated section title string here, instead.) .IP "\fBbeginboundary\fR (usado somente quando \fBmode=after\fR, e obrigatório neste caso)" 4 .IX Item "beginboundary (usado somente quando mode=after, e obrigatório neste caso)" .PD 0 .IP "\fBendboundary\fR (idem)" 4 .IX Item "endboundary (idem)" .PD A second Perl regexp required only when \fBmode=after\fR. The addendum will be placed immediately before or after the first internal data string matching the \fBbeginboundary\fR or \fBendboundary\fR argument regexp, respectively. .Sp No nosso caso, podemos escolher para indicar o final da secção, nós combinamos por acrescentando: .Sp .Vb 1 \& endboundary= .Ve .Sp ou para indicar o início da próxima secção, indicando: .Sp .Vb 1 \& beginboundary=
.Ve .Sp In both cases, our addendum will be placed after the \fB
\fR and before the \fB
\fR. The first one is better since it will work even if the document gets reorganized. .Sp Ambas as formas existem porque os formatos de documentação são diferentes. Em alguns deles, existe uma forma de marcar o fim duma secção (tal como o \fB
\fR, que utilizamos), enquanto alguns outros não marcam explicitamente o fim da secção (como no manual). No primeiro caso, você quer fazer um \fIboundary\fR correspondente a \fIend de um section\fR, de modo que \fIinsertion point\fR vem depois. Neste último caso, você quer fazer um \fIboundary\fR correspondente ao \fIbeginning of the next section\fR seguinte, de modo que a \fIinsertion point\fR vem pouco antes. .PP Isto pode parecer obscuro, mas espero que os próximos exemplos vão esclarecer. .ie n .IP "Para resumir o exemplo que usamos até agora, a fim de adicionar uma secção chamada""Sobre esta tradução"" depois uma ""Sobre este documento"" num documento \s-1SGML,\s0 você pode usar qualquer uma destas linhas de cabeçalho:" 2 .el .IP "Para resumir o exemplo que usamos até agora, a fim de adicionar uma secção chamada``Sobre esta tradução'' depois uma ``Sobre este documento'' num documento \s-1SGML,\s0 você pode usar qualquer uma destas linhas de cabeçalho:" 2 .IX Item "Para resumir o exemplo que usamos até agora, a fim de adicionar uma secção chamadaSobre esta tradução depois uma Sobre este documento num documento SGML, você pode usar qualquer uma destas linhas de cabeçalho:" .Vb 2 \& PO4A\-HEADER: mode=after; position=Acerca deste documento; endboundary= \& PO4A\-HEADER: mode=after; position=Acerca deste documento; beginboundary=
.Ve .IP "Se você quiser acrescentar algo depois na secção seguinte nroff:" 2 .IX Item "Se você quiser acrescentar algo depois na secção seguinte nroff:" .Vb 1 \& .SH "AUTORES" .Ve .Sp You should select two step approach by setting \fBmode=after\fR. Then you should narrow down search to the line after \fB\s-1AUTHORS\s0\fR with the \fBposition\fR argument regex. Then, you should match the beginning of the next section (i.e., \fB^\e.SH\fR) with the \fBbeginboundary\fR argument regex. That is to say: .Sp .Vb 1 \& PO4A\-HEADER:mode=after;position=AUTORES;beginboundary=\e.SH .Ve .ie n .IP "Se você quiser adicionar algo numa secção (como depois ""Copyright Big Dude"") em vez de adicionar uma secção inteira, dê um \fBposition\fR correspondente a essa linha, e dê um \fBbeginboundary\fR combinando qualquer linha." 2 .el .IP "Se você quiser adicionar algo numa secção (como depois ``Copyright Big Dude'') em vez de adicionar uma secção inteira, dê um \fBposition\fR correspondente a essa linha, e dê um \fBbeginboundary\fR combinando qualquer linha." 2 .IX Item "Se você quiser adicionar algo numa secção (como depois Copyright Big Dude) em vez de adicionar uma secção inteira, dê um position correspondente a essa linha, e dê um beginboundary combinando qualquer linha." .Vb 1 \& PO4A\-HEADER:mode=after;position=Copyright Big Dude, 2004;beginboundary=^ .Ve .ie n .IP "Se você 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 sequências simples como \fB""\s-1EOF""\s0\fR, mas prefira as que têm menos chance estar no seu documento." 2 .el .IP "Se você 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 sequências simples como \fB``\s-1EOF''\s0\fR, mas prefira as que têm menos chance estar no seu documento." 2 .IX Item "Se você quiser adicionar alguma coisa no final do documento, dê uma position correspondente a qualquer linha do seu documento (mas apenas uma linha, po4a não continuará se não é única), e dê uma endboundary sem corresponder a nada. Aqui não use sequências simples como EOF, mas prefira as que têm menos chance estar no seu documento." .Vb 1 \& PO4A\-HEADER:mode=after;position=About this document;beginboundary=FakePo4aBoundary .Ve .PP Em todo caso, lembre-se que estas são expressões regulares. Por exemplo, se você quiser corresponder à extremidade de uma secção nroff terminando com a linha .PP .Vb 1 \& .fi .Ve .PP Não use \fB.fi\fR como \fBendboundary\fR, porque vai coincidir com \*(L"the[ fi]le\*(R", que obviamente não é o que você espera. O \fBendboundary\fR correto nesse caso é: \fB.^\efi$\fR. .PP Se a adenda não for para onde você esperava, tenta passar o argumento \fB\-vv\fR para as ferramentas, para que elas expliquem o que fazem ao colocar a adenda. .PP \fIExemplo mais detalhado\fR .IX Subsection "Exemplo mais detalhado" .PP Documento original (\s-1POD\s0 formatado): .PP |=head1 \s-1NOME\s0 | |fictício \- um programa fictício | |=head1 \s-1AUTOR\s0 | |eu .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 A fim de colocar a seu adenda antes do \s-1AUTOR,\s0 use o seguinte cabeçalho: .PP .Vb 1 \& PO4A\-HEADER:mode=after;position=NOM;beginboundary=^=head1 .Ve .PP This works because the next line matching the \fBbeginboundary\fR /^=head1/ after the section \*(L"\s-1NAME\*(R" \s0(translated to \*(L"\s-1NOM\*(R"\s0 in French), is the one declaring the authors. So, the addendum will be put between both sections. Note that if another section is added between \s-1NAME\s0 and \s-1AUTHOR\s0 sections later, po4a will wrongfully put the addenda before the new section. .PP To avoid this you may accomplish the same using \fBmode\fR=\fIbefore\fR: .PP .Vb 1 \& PO4A\-HEADER:mode=before;position=^=head1 AUTEUR .Ve .SS "\s-1COMO\s0 fazer tudo numa invocação de programa?" .IX Subsection "COMO fazer tudo numa invocação de programa?" O uso de po4a provou ser um erro de pouco propenso para os utilizadores, desde que têm que invocar dois programas diferentes na ordem correta (\fBpo4a\-updatepo\fR e depois \fBpo4a\-translate\fR), cada um deles necessitando de mais de 3 argumentos. Além disso, foi difícil com este sistema utilizar apenas um ficheiro \s-1PO\s0 para todos os seus documentos quando foi usado mais do que um formato. .PP O programa \fIpo4a\fR\|(1) foi projetado para resolver estas dificuldades. Uma vez que seu projeto é convertido para o sistema, você escreve um ficheiro de configuração simples a explicar onde estão seus ficheiros de tradução (\s-1PO\s0 e \&\s-1POT\s0), onde estão os documentos originais, os seus formatos e onde as suas traduções devem ser colocadas. .PP Then, calling \fIpo4a\fR\|(1) on this file ensures that the \s-1PO\s0 files are synchronized against the original document, and that the translated document are generated properly. Of course, you will want to call this program twice: once before editing the \s-1PO\s0 files to update them and once afterward to get a completely updated translated document. But you only need to remember one command line. .SS "\s-1COMO\s0 personalizar po4a?" .IX Subsection "COMO personalizar po4a?" Os módulos po4a têm opções (especificado com a opção \fB\-o\fR) que podem ser usadas para alterar o comportamento do módulo. .PP You can also edit the source code of the existing modules or even write your own modules. To make them visible to po4a, copy your modules into a path called \f(CW\*(C`/bli/blah/blu/lib/Locale/Po4a/\*(C'\fR and then adding the path \&\f(CW\*(C`/bli/blah/blu\*(C'\fR in the \f(CW\*(C`PERLIB\*(C'\fR or \f(CW\*(C`PERL5LIB\*(C'\fR environment variable. For example: .PP .Vb 1 \& PERLLIB=$PWD/lib po4a \-\-previous po4a/po4a.cfg .Ve .PP Nota: o atual nome do diretório lib não é importante .SH "Como é que funciona?" .IX Header "Como é que funciona?" Este capítulo dá\-nos uma visão geral interna do po4a, de modo a que você se possa sentir 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 você esperava, e como resolver os seus problemas. .SS "Qual é a grande imagem aqui?" .IX Subsection "Qual é a grande imagem aqui?" A arquitetura po4a é orientada a objetos (em Perl. Isso não é de bom gosto?). A ancestral e comum a todas as classes de analisadores é chamada TransTractor. Este estranho nome vem do facto de ter a responsabilidade de traduzir documentos e extrair sequências ao mesmo tempo. .PP Mais formalmente, é preciso um documento para traduzir mais um ficheiro \s-1PO\s0 contendo 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 carateres 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 This little bone is the core of all the po4a architecture. If you omit the input \s-1PO\s0 and the output document, you get \fBpo4a\-gettextize\fR. If you provide both input and disregard the output \s-1PO,\s0 you get \fBpo4a\-translate\fR. The \&\fBpo4a\fR calls TransTractor twice and calls \fBmsgmerge \-U\fR between these TransTractor invocations to provide one-stop solution with a single configuration file. .PP \&\fITransTractor::analise()\fR é uma função virtual implementada por cada módulo. Aqui está um pequeno exemplo para mostrar como funciona. Ele analisa uma lista de parágrafos, cada um deles começando com \fB

\fR. .PP .Vb 10 \& 1 sub parse { \& 2 PARAGRAPH: while (1) { \& 3 $my ($paragraph,$pararef,$line,$lref)=("","","",""); \& 4 $my $first=1; \& 5 while (($line,$lref)=$document\->shiftline() && defined($line)) { \& 6 if ($line =~ m/

/ && !$first\-\-; ) { \& 7 $document\->unshiftline($line,$lref); \& 8 \& 9 $paragraph =~ s/^

//s; \& 10 $document\->pushline("

".$document\->translate($paragraph,$pararef)); \& 11 \& 12 next PARAGRAPH; \& 13 } else { \& 14 $paragraph .= $line; \& 15 $pararef = $lref unless(length($pararef)); \& 16 } \& 17 } \& 18 return; # Did not got a defined line? End of input file. \& 19 } \& 20 } .Ve .PP On line 6 and 7, we encounter \f(CW\*(C`shiftline()\*(C'\fR and \f(CW\*(C`unshiftline()\*(C'\fR. These help you to read and unread the head of internal input data stream of master document into the line string and its reference. Here, the reference is provided by a string \f(CW\*(C`$filename:$linenum\*(C'\fR. Please remember Perl only has one dimensional array data structure. So codes handling the internal input data stream line are a bit cryptic. .PP Na linha 6, encontramos \fB

\fR para o segundo tempo. Isso é o sinal do próximo parágrafo. Devemos, portanto, colocar a linha que obtemos de volta no documento original (linha 7) e empurrar o parágrafo construído até agora nas saídas. Depois de retirar o líder \fB

\fR da linha 9, vamos empurrar a concatenação desta etiqueta com a tradução do resto doparágrafo. .PP Esta função 'translate'() é muito fixe. Ela empurra o seu argumento para a saída do ficheiro \s-1PO \s0(extração) e retorna a sua tradução como a encontra no ficheiro \s-1PO\s0 de entrada (tradução). Uma vez que é usada como parte do argumento de 'pushline'(), estas regiões de tradução para o documento de saída. .PP Isn't that cool? It is possible to build a complete po4a module in less than 20 lines when the format is simple enough… .PP Você pode aprender mais sobre isso em \&\fILocale::Po4a::TransTractor\fR\|(3pm). .SS "Gettextization: como é que funciona?" .IX Subsection "Gettextization: como é que funciona?" A ideia aqui é levar o documento original e a sua tradução, e dizer que a enésima sequência extraída da tradução é a tradução da enésima sequência extraída do original. Para isto funcionar, os dois ficheiros devem partilhar exatamente a mesma estrutura. Por exemplo, se os ficheiros têm a seguinte estrutura, é muito pouco provável que a 4ª sequência na tradução (do tipo \&'capítulo') seja a tradução da 4ª sequência no original (do tipo \&'parágrafo'). .PP .Vb 1 \& Original Tradução \& \& capítulo capítulo \& parágrafo parágrafo \& parágrafo parágrafo \& parágrafo capítulo \& capítulo parágrafo \& parágrafo parágrafo .Ve .PP Para isso, os analisadores po4a são usados ​​em ambos os ficheiros, original e a tradução, para extrair ficheiros \s-1PO\s0 e, em seguida um terceiro ficheiro \&\s-1PO\s0 é construído a partir deles tomando as sequências do segundo como a tradução de sequências do primeiro. A fim de verificar que as sequências que são colocadas juntas são realmente as traduções de cada um dos ficheiros, documentos analisados em po4a devem colocar informações sobre o tipo sintático das sequências extraídas do documento (todos os existentes o fazem, o seu também deve). Então, esta informação é usada para certificar que ambos os documentos têm a mesma sintaxe. No exemplo anterior, que nos permitia num caso detetar que a sequência 4 é um parágrafo , e noutro caso um título do capítulo e relatar o problema. .PP Em teoria, seria possível detetar o problema, e voltar a sincronizar os ficheiros depois (como faz \fBdiff\fR). Mas o que devemos fazer das poucas sequências antes da dessincronização não é clara, e iria produzir maus resultados algumas vezes. É por isso que a implementação atual não tenta voltar a sincronizar tudo e falhar com os detalhes quando algo dá errado, exigindo modificação manual dos ficheiros para corrigir o problema. .PP Mesmo com essas precauções, as coisas aqui podem muito facilmente dar errado. É por isso que todas as traduções supostas desta forma são marcadas como imprecisas (fuzzy) para se certificar de que o tradutor as revê e verifica. .SS "Adenda: Como isso funciona?" .IX Subsection "Adenda: Como isso funciona?" Bem, isso é muito fácil aqui. O documento traduzido não é escrito diretamente para o disco, mas mantido na memória até que todas as adendas sejam aplicadas. Os algoritmos envolvidos aqui são bastante simples. Nós olhamos para uma linha que correspondente na posição da expressão regular (regexp), e inserimos a adenda antes, se estamos em\fBmode=before\fR. Se não, vamos procurar a próxima linha correspondente ao limite e inserimos a adenda após esta linha se é um \fBendboundary\fR ou antes se esta linha é um \&\fBbeginboundary\fR. .SH "PERGUNTAS MAIS FREQUENTES" .IX Header "PERGUNTAS MAIS FREQUENTES" This chapter groups the Frequently Asked Questions. In fact, most of the questions for now could be formulated that way: \*(L"Why is it designed this way, and not that one?\*(R" If you think po4a isn't the right answer to documentation translation, you should consider reading this section. If it does not answer your question, please contact us on the mailing list. We love feedback. .SS "Porque se traduz cada parágrafo separadamente?" .IX Subsection "Porque se traduz cada parágrafo separadamente?" Sim, em po4a, cada parágrafo é traduzido separadamente (na verdade, cada módulo decide isso, mas todos os módulos existentes o fazem, e o vossos também devem). Existem são duas vantagens principais para essa abordagem: .IP "\(bu" 2 Quando as partes técnicas do documento estão escondidos da cena, o tradutor não pode mexer com elas. Quanto menos marcadores apresentarmos ao tradutor menos erro que ele pode fazer. .IP "\(bu" 2 Cortar o documento ajuda a isolar as alterações ao documento original. Quando o original é modificado, encontrando que partes da tradução têm necessidade de ser atualizadas, é facilitado por este processo. .PP Mesmo com essas vantagens, algumas pessoas não gostam da ideia de traduzir cada parágrafo separadamente. Aqui estão algumas das respostas que eu posso dar vosso receio: .IP "\(bu" 2 Esta abordagem provou ser sucesso no projeto \s-1KDE\s0 e permite que as pessoas lá produzam o maior 'corpus' de documentação traduzida e atualizada. Eu sei. .IP "\(bu" 2 Os tradutores ainda podem usar o contexto para traduzir, uma vez que as sequências no ficheiro \s-1PO\s0 estão da mesma ordem que no documento original. Traduzindo portanto sequencialmente, é comparável se você usa po4a ou não. E em qualquer caso, a melhor maneira de obter o contexto permanece em converter o documento para um formato de impressão, desde que a formatação do texto não seja realmente legível, \s-1IMHO.\s0 .IP "\(bu" 2 Esta abordagem é a usada por tradutores profissionais. Concordo, de que eles têm objetivos um pouco diferentes dos tradutores de código aberto. A manutenção é por exemplo, muitas vezes menos importante para eles, uma vez que o conteúdo raramente tem mudanças. .SS "Porque não dividir em nível da frase (ou menor)?" .IX Subsection "Porque não dividir em nível da frase (ou menor)?" As ferramentas de tradutor profissional, por vezes, dividem o documento nível da frase, a fim de maximizar a capacidade de reutilização das traduções anteriores e acelerar o seu processo. O problema é que a mesma frase pode ter traduções diversas, dependendo do contexto. .PP Os parágrafos são, por definição, mais longos do que frases. Esperemos garantir que tendo o mesmo número em dois documentos irá ter o mesmo significado (e tradução), independentemente do contexto em cada caso. .PP Dividindo em partes menores do que a frase seria \fBvery bad\fR. Seria um pouco longo para explicar porquê aqui, mas o leitor interessado pode consultar a página do manual \&\fILocale::Maketext::TPJ13\fR\|(3pm) (que vem com a documentação Perl), por exemplo. Para ser curto, cada idioma tem as suas regras de sintaxe específicas, e não há maneira de construir frases agregando partes de frases trabalhando para todos os idiomas existentes (ou mesmo para 5 dos 10 mais falados, ou até menos). .SS "Porque não colocar o original como comentário, juntamente com a tradução (ou vice-versa)?" .IX Subsection "Porque não colocar o original como comentário, juntamente com a tradução (ou vice-versa)?" À primeira vista, gettext não parece ser adaptado a todos os tipos de traduções. Por exemplo, não parecia adaptado para debconf, o interface que todos os pacotes do Debian usam para sua interação com o utilizador durante instalação. Nesse caso, os textos para traduzir eram muito curtos (uma dúzia de linhas para cada pacote), e foi difícil colocar a tradução num ficheiro especializado uma vez que tem de estar disponível antes do pacote instalação. .PP É por isso que o developer debconf decidiu implementar outra solução, onde as traduções são colocados no mesmo ficheiro que o original. Isto é bastante atraente. Alguém poderia até querer fazer isso para \s-1XML,\s0 por exemplo. Ficaria assim: .PP .Vb 3 \&

\& My title \& Mon titre \& \& \& My text. \& Mon texte. \& \&
.Ve .PP Mas foi tão problemático que uma abordagem baseada em \s-1PO\s0 é usada agora. Apenas o original pode ser editado no ficheiro, e as traduções devem ter lugar em ficheiros \s-1PO\s0 extraídos do modelo principal (e colocado de volta no pacote de compilação na hora). O sistema antigo foi substituído por causa de várias questões: .IP "\(bu" 4 Problemas de manutenção .Sp Se vários tradutores fornecerem um fragmento ao mesmo tempo, fica difícil fundi-los. .Sp Como você vai detectar alterações ao original, que precisam ser aplicadas àstraduções? Se usar 'diff', você tem que anotar que versão do original você traduziu. Ou seja, você precisa de um ficheiro \s-1PO\s0 em seu ficheiro ;) .IP "\(bu" 4 Problemas de codificação .Sp Esta solução é viável quando são envolvidos apenas os idiomas europeus, mas a introdução de coreano, russo e/ou árabe realmente complicaram o quadro. \s-1UTF\s0 poderia ser uma solução, mas ainda há alguns problemas com ele. .Sp Além disso, esses problemas são difíceis de detetar (ou seja, apenas os leitores coreanos irão detetar que a codificação de coreano está partida [por causa do tradutor russo]). .PP Gettext resolve todos os problemas em conjunto. .SS "Mas gettext não foi projetado para esse uso!" .IX Subsection "Mas gettext não foi projetado para esse uso!" Isso é verdade, mas até agora ninguém apareceu com uma solução melhor. A única alternativa conhecida é a tradução manual, com todos os problemas de manutenção. .SS "E sobre as outras ferramentas de tradução para documentação usando gettext?" .IX Subsection "E sobre as outras ferramentas de tradução para documentação usando gettext?" Tanto quanto eu sei, existem apenas duas delas: .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 sequências 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. .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 "Educar os developers sobre tradução" .IX Subsection "Educar os developers sobre tradução" Quando você tenta traduzir a documentação ou programas, você enfrenta três tipos de problemas; Linguística (nem toda a gente fala duas línguas), técnicas (é por isso que existe po4a) e relacional/humano. Nem todos os developers entendem a necessidade de traduzir o material. Mesmo quando de boa vontade, eles podem ignorar como facilitar o trabalho dos tradutores. Para ajudar com isso, po4a vem em muita documentação que pode ser referida. .PP Outro ponto importante é que cada ficheiro traduzido começa com um curto comentário indicando o que o ficheiro é e como usá\-lo. Isso deve ajudar a os pobres developers inundados com toneladas de ficheiros em diferentes idiomas que eles dificilmente falam e, ajudá\-los a lidar corretamente com ele. .PP In the po4a project, translated documents are not source files anymore, in the sense that these files are not the preferred form of the work for making modifications to it. Since this is rather unconventional, that's a source of easy mistakes. That's why all files present this header: .PP .Vb 10 \& | ***************************************************** \&| * FICHEIRO GERADO, NÃO EDITE * \&| * NÃO É UM FICHEIRO FONTE, MAS UMA COMPILAÇÃO * \&| ***************************************************** \&| \&| Este ficheiro foi gerado por po4a\-translate(1). Não o guarde (em VCS, \&| por exemplo), mas armazene o ficheiro PO usado como ficheiro de origem por po4a\-translate. \&| \&| De fato, considere isso como um binário, e o ficheiro PO como um ficheiro fonte regular: \&| Se o PO se perde, manter esta tradução atualizada será mais difícil ;) .Ve .PP Da mesma forma, os ficheiros \s-1PO\s0 regulares do gettext só precisam ser copiados para o diretório \fIpo/\fR. Mas \fBeste não é um dos casos manipulados por po4a\fR. O grande risco aqui é que um developer apaga a tradução existente do seu programa com a tradução de sua documentação. (Ambos não podem ser armazenados no mesmo ficheiro \s-1PO,\s0 porque o programa precisa para instalar o sua tradução como um ficheiro mo enquanto a documentação só usa a sua tradução na hora de compilação). É por isso que os ficheiros \s-1PO\s0 produzidos pelo módulo po-debiandoc contêm o seguinte cabeçalho: .PP .Vb 10 \& # \& # AVISO PARA developers: \& # \- não precisam de editar manualmente os ficheiros POT e PO. \& # \- este ficheiro contém a tradução do seu modelo debconf. \& # Não substitua a tradução do seu programa com isto !! \& # (ou os seus tradutores irão ficar muito chateados) \& # \& # AVISO PARA TRADUTORES: \& # Se não está familiarizado com o formato PO, é melhor ler documentação \& # gettext, especialmente secções dedicadas a este formato. \& # Por exemplo, corra: \& # info \-n \*(Aq(gettext)Ficheiros PO\*(Aq \& # info \-n \*(Aq(gettext)Cabeçalho de Entrada\*(Aq \& # \& # Alguma informação específica para po\-debconf está disponível em \& # /usr/share/doc/po\-debconf/README\-trans \& # ou http://www.debian.org/intl/l10n/po\-debconf/README\-trans \& # .Ve .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 você não precisa de compreender os internos para o usar).Dessa maneira, não precisamos de reinventar a roda e, porque o seu uso é 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 nova sintaxe de ficheiros e os seus editores de ficheiros \s-1PO\s0 favoritos (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 podem ser encontrados nestes endereços: .Sp .Vb 2 \& \- https://docs.kde.org/stable5/en/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 Addenda are… strange at the first glance. .IP "\(bu" 2 Não pode adaptar o texto traduzido as suas preferências, como dividindo um parágrafo aqui e, juntando 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 One of my dreams would be to integrate somehow po4a to Gtranslator or Lokalize. When a documentation file is opened, the strings are automatically extracted, and a translated file + po file can be written to disk. If we manage to do an \s-1MS\s0 Word (\s-1TM\s0) module (or at least \s-1RTF\s0) professional translators may even use it. .SH "AUTORES" .IX Header "AUTORES" .Vb 2 \& Denis Barbier \& Martin Quinson (mquinson#debian.org) .Ve