.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" 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-GETTEXTIZE 1p" .TH PO4A-GETTEXTIZE 1p "2020-12-09" "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\-gettextize \- converte um ficheiro original (e a tradução dele) para um ficheiro \s-1PO\s0 .SH "SINOPSE" .IX Header "SINOPSE" \&\fBpo4a\-gettextize\fR \fB\-f\fR \fIfmt\fR \fB\-m\fR \fImaster.doc\fR [\fB\-l\fR \fI\s-1XX\s0.doc\fR] \fB\-p\fR \&\fI\s-1XX\s0.po\fR .PP (\fI\s-1XX\s0.po\fR é a saída, todos os outros são entradas) .SH "DESCRIÇÃO" .IX Header "DESCRIÇÃO" po4a (\s-1PO\s0 for anything) facilita a manutenção de tradução da documentação a usar as ferramentas clássicas do gettext. A característica principal do po4a é que ele dissocia a tradução do conteúdo da estrutura documental. Consulte a página \fBpo4a\fR\|(7) para uma introdução suave a este projeto. .PP O script \fBpo4a\-gettextize\fR é responsável pela conversão de ficheiros de documentação em ficheiros \s-1PO.\s0 Só precisa dele para configurar o seu projeto de tradução com o po4a, nunca depois. .PP Se começar do zero, \fBpo4a\-gettextize\fR extrairá as cadeias traduzíveis da documentação e gravará um ficheiro \s-1POT.\s0 Se fornecer um ficheiro traduzido existente anteriormente com o sinalizador \fB\-l\fR, \fBpo4a\-gettextize\fR tentará usar as traduções que ele contém no ficheiro \s-1PO\s0 produzido. Esse processo permanece tedioso e manual, conforme explicado na Secção \*(L"Converter uma tradução manual em po4a\*(R" abaixo. .PP Se o documento principal tiver caracteres não \s-1ASCII,\s0 o novo ficheiro \s-1PO\s0 gerado estará em \s-1UTF\-8.\s0 Caso contrário (se o documento principal estiver completamente em \s-1ASCII\s0), o \s-1PO\s0 gerado utilizará a codificação do documento de entrada traduzido, ou \s-1UTF\-8\s0 se não for fornecido nenhum documento traduzido. .SH "OPÇÕES" .IX Header "OPÇÕES" .IP "\fB\-f\fR, \fB\-\-format\fR" 4 .IX Item "-f, --format" O formato da documentação que pretende processar. Use a opção \&\fB\-\-help\-format\fR para ver a lista de formatos disponíveis. .IP "\fB\-m\fR, \fB\-\-master\fR" 4 .IX Item "-m, --master" Ficheiro que contem o documento principal para traduzir. Pode usar esta opção várias vezes se quiser 'gettextize' vários documentos. .IP "\fB\-M\fR, \fB\-\-master\-charset\fR" 4 .IX Item "-M, --master-charset" Conjunto de carateres do ficheiro que contém o documento a traduzir. .IP "\fB\-l\fR, \fB\-\-localized\fR" 4 .IX Item "-l, --localized" Ficheiro que contem o documento localizado (traduzido). Se forneceu ficheiros mestres múltiplos, pode fornecer múltiplos ficheiros localizados a usar esta opção mais de uma vez. .IP "\fB\-L\fR, \fB\-\-localized\-charset\fR" 4 .IX Item "-L, --localized-charset" Conjunto de carateres do ficheiro que contém o documento localizado. .IP "\fB\-p\fR, \fB\-\-po\fR" 4 .IX Item "-p, --po" Ficheiro onde o catálogo de mensagens deve ser escrito. Se não for dado, a mensagem catálogo será escrito na saída predefinido. .IP "\fB\-o\fR, \fB\-\-option\fR" 4 .IX Item "-o, --option" Opção/ções adicional/ais para passar ao plugin de formato. Veja a documentação de cada plugin para mais informações sobre as opções válidas e os significados deles. Por exemplo, poderia passar '\-o tablecells' para o analisador AsciiDoc, enquanto o analisador de texto aceitaria '\-o tabs=split'. .IP "\fB\-h\fR, \fB\-\-help\fR" 4 .IX Item "-h, --help" Mostrar uma pequena mensagem de ajuda. .IP "\fB\-\-help\-format\fR" 4 .IX Item "--help-format" Lista os formatos de documentação compreendidos por po4a. .IP "\fB\-V\fR, \fB\-\-version\fR" 4 .IX Item "-V, --version" Mostrar a versão do script e sair. .IP "\fB\-v\fR, \fB\-\-verbose\fR" 4 .IX Item "-v, --verbose" Aumentar o detalhe do programa. .IP "\fB\-d\fR, \fB\-\-debug\fR" 4 .IX Item "-d, --debug" Saída de alguma informação de depuração. .IP "\fB\-\-msgid\-bugs\-address\fR \fIe\-mail@endereço\fR" 4 .IX Item "--msgid-bugs-address e-mail@endereço" Definir o endereço do relatório para msgid bugs. Por predefinição, os ficheiros \s-1POT\s0 criados não têm campos Report-Msgid-bugs-To. .IP "\fB\-\-copyright\-holder\fR \fIstring\fR" 4 .IX Item "--copyright-holder string" Definir o titular dos direitos de autor no cabeçalho \s-1POT. O\s0 valor predefinido é \*(L" Free Software Foundation, Inc.\*(R" .IP "\fB\-\-package\-name\fR \fIstring\fR" 4 .IX Item "--package-name string" Definir o nome do pacote para o cabeçalho \s-1POT. A\s0 predefinição é \*(L"\s-1PACKAGE\*(R".\s0 .IP "\fB\-\-package\-version\fR \fIstring\fR" 4 .IX Item "--package-version string" Definir o nome do pacote para o cabeçalho \s-1POT. A\s0 predefinição é \*(L"\s-1VERSION\*(R".\s0 .SS "Converter a tradução manual para po4a" .IX Subsection "Converter a tradução manual para po4a" \&\fBpo4a\-gettextize\fR tentará extrair o conteúdo de qualquer ficheiro de tradução fornecido e utilizará esse conteúdo como msgstr no ficheiro \s-1PO\s0 produzido. Este processo é muito frágil: a N\-ésima cadeia do ficheiro traduzido deve ser a tradução da N\-ésima cadeia no original. Isto naturalmente não vai funcionar a menos que ambos os ficheiros compartilhem a mesma estrutura. .PP Internamente, cada analisador po4a reporta o tipo sintático de cada cadeia extraída. Esta é a forma como a dessincronização é detetada durante a gettext\-ização. Por exemplo, se os ficheiros têm a seguinte estrutura, é muito improvável que a 4ª cadeia na tradução (do tipo 'capítulo') seja a tradução da 4ª cadeia no original (do tipo 'parágrafo'). É provável que um novo parágrafo tenha sido adicionado ao original ou que dois parágrafos originais tenham sido fundidos na tradução. .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 \&\fBpo4a\-gettextize\fR diagnosticará verbalmente qualquer dessincronização de estrutura detectada. Quando isso acontece, deve editar os ficheiros manualmente (isso provavelmente requer que tenha algumas noções do idioma de destino). Deve adicionar parágrafos falsos ou remover algum conteúdo de um dos documentos (ou ambos) para corrigir as disparidades relatadas, até que a estrutura dos dois documentos corresponda perfeitamente. Alguns truques são dados na próxima secção. .PP Mesmo quando o documento é processado com sucesso, disparidades não detetadas e erros silenciosos ainda são possíveis. É por isso que qualquer tradução associada automaticamente pelo po4a\-gettextize é marcada como \&\fIfuzzy\fR para exigir uma inspeção manual por seres humanos. É preciso verificar se cada msgstr recuperado é realmente a tradução do msgid associado e não a cadeia antes ou depois. .PP Como pode ver, a chave aqui é de ter exatamente a mesma estrutura no documento traduzido e no original. O melhor é fazer a gettextização na versão exata de \fImaster.doc\fR que foi usada para a tradução e atualizar o ficheiro \s-1PO\s0 somente no ficheiro mestre mais recente depois que a gettextização tiver êxito. .PP Se tiver a sorte de ter uma correspondência perfeita nas estruturas do ficheiro, construir um ficheiro \s-1PO\s0 correto é uma questão de segundos. Caso contrário, logo entenderá porque este processo tem um nome tão feio :) Mas lembre-se que este trabalho grunhido é o preço a pagar para ter o conforto de po4a depois. Uma vez convertido, a sincronização entre os documentos mestres e as traduções será sempre totalmente automática. .PP Mesmo quando as coisas correm mal, a gettext\-ização permanece muitas vezes mais rápida do que a tradução de tudo de novo. Consegui fazer a gettext\-ização da tradução francesa existente de toda a documentação Perl num dia, embora a estrutura de muitos documentos tenha sido dessincronizada. Foram mais que dois megabytes de texto original (2 milhões de caracteres): reiniciar a tradução a partir do zero teria exigido vários meses de trabalho. .SS "Dicas e truques para o processo de gettextização" .IX Subsection "Dicas e truques para o processo de gettextização" A gettextização acaba assim que uma dessincronização é detetada. Em teoria, provavelmente seria possível ressincronizar a gettextização posteriormente nos documentos a usar, por exemplo, o mesmo algoritmo que o utilitário \&\fBdiff\fR\|(1). Mas uma intervenção manual ainda seria obrigatória para corresponder aos elementos manualmente que não puderam ser correspondidos automaticamente, a explicar por que a ressincronização automática ainda não foi implementada (ainda?). .PP Quando isso acontece, tudo se resume novamente ao alinhamento das malditas estruturas desses ficheiros através de edições manuais. \fBpo4a\-gettextize\fR é bastante verboso sobre o que deu errado quando isso acontece. Ele relata as cadeias que não correspondem, as posições delas no texto e o tipo de cada uma delas. Além disso, o ficheiro \s-1PO\s0 gerado até o momento é descartado como \&\fIgettextization.failed.po\fR para uma inspeção posterior. .PP Aqui estão alguns outros truques para ajudar-lo neste processo tedioso: .IP "\(bu" 4 Remova todo o conteúdo adicional das traduções, como a secção que dá méritos aos tradutores. Pode adicioná\-lo novamente no po4a posteriormente, a usar um adendo (consulte \fBpo4a\fR\|(7)). .IP "\(bu" 4 Se precisar de editar os ficheiros para alinhar as estruturas deles, deve preferir editar a tradução, se possível. De fato, se as alterações no original forem muito intrusivas, a versão antiga e nova não corresponderão durante a atualização do pedido e a tradução correspondente será despejada de qualquer maneira. Mas não hesite em editar também o documento original, se for necessário: o importante é obter um primeiro ficheiro \s-1PO\s0 para começar. .IP "\(bu" 4 Não hesite em eliminar qualquer conteúdo original que não exista na versão traduzida. Este conteúdo será reintroduzido automaticamente posteriormente, ao sincronizar o ficheiro \s-1PO\s0 com o documento. .IP "\(bu" 4 Provavelmente deve informar o autor original de qualquer mudança estrutural na tradução que pareça justificada. Questões no documento original devem ser relatadas ao autor. Fixá\-los na sua tradução apenas os corrige para uma parte da comunidade. Além disso, é impossível fazê\-lo quando se utiliza o po4a ;) .IP "\(bu" 4 Algumas vezes, o conteúdo do parágrafo não corresponde, mas tipos deles não. Corrigir isso é até dependente do formato. No \s-1POD\s0 e man, frequentemente vem do fato que um deles contém uma linha a começar com espaço em branco, mas a outra não. Naqueles formatos tal parágrafo não pode ser dimensionado e, então, se torna um tipo diferente. Basta remover o espaço e está terminado. Pode ser um erro de escrita no nome da marcação em \s-1XML.\s0 .Sp Da mesma forma, dois parágrafos podem ser mesclados num \s-1POD\s0 quando a linha separadora contém alguns espaços ou quando não há linha vazia entre a linha \&\fB=item\fR e o conteúdo do item. .IP "\(bu" 4 Às vezes a mensagem de dessincronização parece estranha porque a tradução está anexada ao parágrafo original errado. É o sinal de um problema não detetado no início do processo. Procure o ponto real de dessincronização a inspecionar \fIgettextization.failed.po\fR e conserte o problema onde ele realmente está. .IP "\(bu" 4 Em alguns cenários infelizes, terá a sensação de que o po4a comeu algumas partes do texto, seja o original ou a tradução. \fIgettextization.failed.po\fR indica que ambos os ficheiros corresponderam como esperado até o parágrafo N. Mas uma tentativa (sem sucesso) é feita para corresponder o parágrafo N+1 no ficheiro original não com o parágrafo N+1 na tradução como deveria, mas com o parágrafo N+2. Tal como se o parágrafo N+1 que se vê no documento simplesmente desaparecesse do ficheiro durante o processo. .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 Portanto, a situação anterior ocorre quando dois parágrafos semelhantes, mas diferentes, são traduzidos exatamente da mesma maneira. Aparentemente, isso removerá um parágrafo da tradução. Para corrigir o problema, basta alterar ligeiramente uma das traduções no documento. Também pode preferir eliminar o segundo parágrafo no documento original. .Sp Ao contrário, se o mesmo parágrafo que aparece duas vezes no documento original não for traduzido exatamente da mesma forma em ambos os locais, terá a sensação de que um parágrafo do documento original simplesmente desapareceu. Basta copiar a melhor tradução sobre a outra no documento traduzido para resolver o problema. .IP "\(bu" 4 Como nota final, não se surpreenda se a primeira sincronização do seu ficheiro \s-1PO\s0 demorar muito tempo. Isso acontece porque a maioria do msgid do ficheiro \s-1PO\s0 resultante da gettextização não corresponde exatamente a nenhum elemento do ficheiro \s-1POT\s0 criado dos ficheiros mestre recentes. Isso força o gettext a procurar o mais próximo a usar um algoritmo de proximidade de cadeias caro. .Sp Por exemplo, o primeiro \fBpo4a\-updatepo\fR da tradução em francês da documentação do Perl (ficheiro \s-1PO\s0 de 5.5 \s-1MB\s0) levou cerca de 48 horas (sim, dois dias), enquanto os subsequentes demoram apenas uma dúzia de segundos. .SH "VER TAMBÉM" .IX Header "VER TAMBÉM" \&\fBpo4a\fR\|(1), \fBpo4a\-normalize\fR\|(1), \fBpo4a\-translate\fR\|(1), \fBpo4a\-updatepo\fR\|(1), \&\fBpo4a\fR\|(7). .SH "AUTORES" .IX Header "AUTORES" .Vb 3 \& Denis Barbier \& Nicolas François \& Martin Quinson (mquinson#debian.org) .Ve .SH "DIREITOS DE AUTOR E LICENÇA" .IX Header "DIREITOS DE AUTOR E LICENÇA" Direitos de Autor 2002\-2020 por \s-1SPI,\s0 inc. .PP Este programa é software livre, pode redistribuí\-lo e/ou modificá\-lo sob os termos da \s-1GPL\s0 (consulte o ficheiro CÓPIA).