.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35) .\" .\" 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-08-19" "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\-gettextize \- converte um arquivo original (e suas traduções) para um arquivo \s-1PO\s0 .SH "SINOPSE" .IX Header "SINOPSE" \&\fBpo4a\-gettextize\fR \fB\-f\fR \fIfmt\fR \fB\-m\fR \fImestre.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, e todo o resto é entrada) .SH "DESCRIÇÃO" .IX Header "DESCRIÇÃO" po4a (\s-1PO\s0 for anything) facilita a manutenção de tradução da documentação usando as ferramentas clássicas do gettext. A principal característica 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 está encarregado da conversão de arquivos de documentação para arquivos \s-1PO.\s0 Você só precisa configurar o seu projeto de tradução com o po4a, nunca depois. .PP Se você começar do zero, \fBpo4a\-gettextize\fR extrairá as strings traduzíveis da documentação e gravará um arquivo \s-1POT.\s0 Se você fornecer um arquivo traduzido existente anteriormente com o sinalizador \fB\-l\fR, \&\fBpo4a\-gettextize\fR tentará usar as traduções que ele contém no arquivo \s-1PO\s0 produzido. Esse processo permanece tedioso e manual, conforme explicado na Seção \*(L"Convertendo uma tradução manual em po4a\*(R" abaixo. .PP Se o documento mestre possui caracteres não\-ASCII, o novo arquivo \s-1PO\s0 gerado vai estar in \s-1UTF\-8.\s0 Do contrário (se o documento mestre estiver completamente em \s-1ASCII\s0), o \s-1PO\s0 gerado vai usar a codificação do documento de entrada traduzido, ou \s-1UTF\-8\s0 se nenhum documento traduzido for fornecido. .SH "OPÇÕES" .IX Header "OPÇÕES" .IP "\fB\-f\fR, \fB\-\-format\fR" 4 .IX Item "-f, --format" Formato da documentação que você quer manipular. 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" Arquivo contendo o documento mestre para traduzir. Você pode usar esta opção múltiplas vezes, se você quiser usar gettextize em múltiplos documentos. .IP "\fB\-M\fR, \fB\-\-master\-charset\fR" 4 .IX Item "-M, --master-charset" Conjunto de caracteres do arquivo contendo o documento para traduzir. .IP "\fB\-l\fR, \fB\-\-localized\fR" 4 .IX Item "-l, --localized" Arquivo contendo o documento localizado (traduzido). Se você forneceu múltiplos arquivos mestre, você pode desejar fornecer múltiplos arquivos localizados usando esta opção mais de uma vez. .IP "\fB\-L\fR, \fB\-\-localized\-charset\fR" 4 .IX Item "-L, --localized-charset" Conjunto de caracteres do arquivo contendo o documento localizado. .IP "\fB\-p\fR, \fB\-\-po\fR" 4 .IX Item "-p, --po" Arquivo para o qual a mensagem deve ser escrita. Se não fornecido, o catálogo de mensagens será escrito para a saída padrão. .IP "\fB\-o\fR, \fB\-\-option\fR" 4 .IX Item "-o, --option" Opções extras para passar o plug-in de formato. Veja a documentação de cada plug-in para mais informações sobre as opções válidas e seus significados. Por exemplo, você poderia passar \*(L"\-o tablecells\*(R" para o analisador AsciiDoc, enquanto o analisador de texto aceitaria \*(L"\-o tabs=split\*(R". .IP "\fB\-h\fR, \fB\-\-help\fR" 4 .IX Item "-h, --help" Mostra uma mensagem de ajuda. .IP "\fB\-\-help\-format\fR" 4 .IX Item "--help-format" Lista os formatos de documentação compreendidos pelo po4a. .IP "\fB\-V\fR, \fB\-\-version\fR" 4 .IX Item "-V, --version" Exibe a versão do script e sai. .IP "\fB\-v\fR, \fB\-\-verbose\fR" 4 .IX Item "-v, --verbose" Aumenta o nível de detalhamento do programa. .IP "\fB\-d\fR, \fB\-\-debug\fR" 4 .IX Item "-d, --debug" Imprime algumas informações de depuração. .IP "\fB\-\-msgid\-bugs\-address\fR \fIe\-mail@endereço\fR" 4 .IX Item "--msgid-bugs-address e-mail@endereço" Define o endereço para relatórios de erros em msgids. Por padrão, os arquivos \s-1POT\s0 criados possuem nenhum campo Report-Msgid-Bugs-To. .IP "\fB\-\-copyright\-holder\fR \fIstring\fR" 4 .IX Item "--copyright-holder string" Define o detentor do copyright no cabeçalho do \s-1POT. O\s0 valor padrão é \*(L"Free Software Foundation, Inc.\*(R" .IP "\fB\-\-package\-name\fR \fIstring\fR" 4 .IX Item "--package-name string" Define o nome do pacote para o cabeçalho do \s-1POT. O\s0 padrão é \*(L"\s-1PACKAGE\*(R".\s0 .IP "\fB\-\-package\-version\fR \fIstring\fR" 4 .IX Item "--package-version string" Define a versão do pacote do cabeçalho do \s-1POT. O\s0 padrão é \*(L"\s-1VERSION\*(R".\s0 .SS "Convertendo uma tradução manual em po4a" .IX Subsection "Convertendo uma tradução manual em po4a" \&\fBpo4a\-gettextize\fR vai tentar extrair o conteúdo de qualquer arquivo \s-1PO\s0 fornecido, e usar este conteúdo como msgstr no arquivo \s-1PO\s0 produzido. Esteja avisado que este processo é muito frágil: a enésima string do arquivo traduzido deve ser a tradução da enésima string do original. Isso naturalmente não vai funcionar a menos que ambos arquivos compartilhem exatamente a mesma estrutura. .PP Internamente, cada analisador po4a relata o tipo sintático de cada sequência extraída. É assim que a dessincronização é detectada durante a gettextization. Por exemplo, se os arquivos tiverem a seguinte estrutura, é muito improvável que a quarta string na tradução (do tipo \*(L"chapter\*(R") seja a tradução da quarta string no original (do tipo \*(L"paragraph\*(R"). É mais provável que um novo parágrafo tenha sido adicionado ao original ou que dois parágrafos originais tenham sido mesclados 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, você deve editar manualmente os arquivos (isso provavelmente requer que você tenha algumas noções do idioma de destino). Você 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 seção. .PP Mesmo quando o documento é processado com sucesso, disparidades não detectadas 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 string antes ou depois. .PP Como você pode ver, a chave aqui é 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 arquivo \s-1PO\s0 somente no arquivo mestre mais recente depois que a gettextização tiver êxito. .PP Se você tiver a sorte de ter uma correspondência perfeita nas estruturas de arquivos, criar um arquivo \s-1PO\s0 correto é uma questão de segundos. Caso contrário, você logo entenderá por que esse processo tem um nome tão feio :) Mas lembre-se de que esse trabalho pesado é o preço a pagar para obter o conforto de po4a posteriormente. Uma vez convertida, a sincronização entre documentos mestre e traduções será sempre totalmente automática. .PP Mesmo quando as coisas dão errado, a gettextização geralmente é mais rápida que traduzir tudo novamente. Eu consegui gettextizar a tradução para francês existente de toda a documentação do Perl em um dia, ainda que estrutura de muitos documentos estivessem dessincronizados. Isso foi mais de dois megabytes que o texto original (2 milhões de caracteres): reiniciar a tradução do zero teria exibido 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 se encerra assim que uma dessincronização é detectada. Em teoria, provavelmente seria possível ressincronizar a gettextização posteriormente nos documentos usando, por exemplo, o mesmo algoritmo que o utilitário \fBdiff\fR\|(1). Mas uma intervenção manual ainda seria obrigatória para corresponder manualmente aos elementos que não puderam ser correspondidos automaticamente, explicando por que a ressincronização automática ainda não foi implementada (ainda?). .PP Quando isso acontece, todo o jogo se resume ao alinhamento das estruturas destes malditos arquivos de novo através de edição manual. \fBpo4a\-gettextize\fR é bastante detalhado sobre o que correu mal quando isso acontece. Ele relata as strings que não correspondem, suas posições no texto, e o tipo de cada um deles. Além disso, o arquivo \s-1PO\s0 gerados até o momento é despejado como \fIgettextization.failed.po\fR para posterior inspeção. .PP Aqui estão alguns outros truques para ajudar você neste processo tedioso: .IP "\(bu" 4 Remova todo o conteúdo extra das traduções, como a seção que dá créditos aos tradutores. Você pode adicioná\-lo novamente no po4a posteriormente, usando um adendo (consulte \fBpo4a\fR\|(7)). .IP "\(bu" 4 Se precisar editar os arquivos para alinhar suas estruturas, você deve preferir editar a tradução, se possível. De fato, se as alterações no original forem muito intrusivas, as versões 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 necessário: o importante é obter um primeiro arquivo \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 arquivo \s-1PO\s0 com o documento. .IP "\(bu" 4 Você provavelmente deve informar o autor original de qualquer alteração estrutural na tradução que pareça justificada. Problemas no documento original devem ser relatadas ao autor. Corrigi-los na sua tradução os corrige apenas para uma parte da comunidade. Além disso, é impossível fazer isso ao usar po4a ;) .IP "\(bu" 4 Algumas vezes, o conteúdo do parágrafo não corresponde, mas não os seus tipos. Corrigir isso é até dependente do formato. No \s-1POD\s0 e man, frequentemente ele vem do fato que um deles contém uma linha começando com espaço em branco, enquanto 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 no \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 detectado no início do processo. Procure o ponto de dessincronização real inspecionando \fIgettextization.failed.po\fR e corrija o problema onde ele realmente está. .IP "\(bu" 4 Em algumas situações infelizes, você terá a sensação de que algumas partes do texto po4a, tanto o original quanto a tradução. \fIgettextization.failed.po\fR indica que os dois arquivos corresponderam conforme o esperado até o parágrafo N. Mas, então, é feita uma tentativa (sem êxito) de corresponder ao parágrafo N+1 no arquivo original e não ao parágrafo N+1 em a tradução como deveria, mas com o parágrafo N+2. Como se o parágrafo N+1 que você vê no documento simplesmente desaparecesse do arquivo durante o processo. .Sp Essa situação infeliz acontece quando o mesmo parágrafo é repetido no documento. Nesse caso, nenhuma nova entrada é criada no arquivo \s-1PO,\s0 mas uma nova referência é adicionada ao já existente. .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. Você também pode preferir eliminar o segundo parágrafo no documento original. .Sp Pelo contrário, se o mesmo parágrafo que aparece duas vezes no documento original não for traduzido exatamente da mesma maneira nos dois locais, você sentirá que um parágrafo do documento original desapareceu. Basta copiar a melhor tradução sobre a outra no documento traduzido para corrigir o problema. .IP "\(bu" 4 Como nota final, não se surpreenda se a primeira sincronização do seu arquivo \s-1PO\s0 demorar muito tempo. Isso ocorre porque a maioria do msgid do arquivo \s-1PO\s0 resultante da gettextização não corresponde exatamente a nenhum elemento do arquivo \s-1POT\s0 criado a partir dos arquivos mestre recentes. Isso força o gettext a procurar o mais próximo usando um algoritmo de proximidade de string caro. .Sp Por exemplo, o primeiro \fBpo4a\-updatepo\fR da tradução em francês da documentação do Perl (arquivo \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 "VEJA TAMBÉM" .IX Header "VEJA 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 "COPYRIGHT E LICENÇA" .IX Header "COPYRIGHT E LICENÇA" Copyright 2002\-2020 por \s-1SPI,\s0 inc. .PP Esse programa é um software livre; você pode redistribuí\-lo e/ou modificá\-lo sob os termos da \s-1GPL\s0 (veja o arquivo \s-1COPYING\s0).