\*(R". Em nome da simplicidade, nós presumimos que o documento está bem formatado, ou seja, que as marcações \*(L"
\*(R" são as únicas marcações apresentadas e que essa marcação está exatamente no começo de cada parágrafo. .PP .Vb 2 \& sub parse { \& my $self = shift; \& \& PARAGRAPH: while (1) { \& my ($paragraph,$pararef)=("",""); \& my $first=1; \& my ($line,$lref)=$self\->shiftline(); \& while (defined($line)) { \& if ($line =~ m/
/ && !$first\-\-; ) { \& # Não é a primeira vez que vemos
. \& # Colocar novamnete a linha atual na entrada, \& # e colocar o parágrafo compilado na saída \& $self\->unshiftline($line,$lref); \& \& # Agora que o documento está formado, traduza\-o: \& # \- Remove a marcação no começo \& $paragraph =~ s/^
//s; \& \& # \- envia para a saída a marcação no começo (não \& # traduzida) e o resto do parágrafo (traduzido) \& $self\->pushline( "
"
\& . $self\->translate($paragraph,$pararef)
\& );
\&
\& next PARAGRAPH;
\& } else {
\& # Anexa ao parágrafo
\& $paragraph .= $line;
\& $pararef = $lref unless(length($pararef));
\& }
\&
\& # Reinicia o loop
\& ($line,$lref)=$self\->shiftline();
\& }
\& # Não conseguiu uma linha definida? Termina com o
\& # arquivo de entrada.
\& return;
\& }
\& }
.Ve
.PP
Uma vez que você tenha implementada a função de análise, você pode usar sua
classe de documento, usando a interface pública apresentada na seção
seguinte.
.SH "INTERFACE PÚBLICA para scripts usando seu analisador"
.IX Header "INTERFACE PÚBLICA para scripts usando seu analisador"
.SS "Construtor"
.IX Subsection "Construtor"
.IP "process(%)" 4
.IX Item "process(%)"
Essa função pode fazer tudo que você precisa fazer com um documento po4a em
uma chamada. Seus argumentos devem ser empacotados como um hash. AÇÕES:
.RS 4
.IP "a." 3
.IX Item "a."
Lê todos os arquivos \s-1PO\s0 especificados em po_in_name
.IP "b." 3
.IX Item "b."
Lê todos os documentos originais especificados em file_in_name
.IP "c." 3
.IX Item "c."
Analisa o documento
.IP "d." 3
.IX Item "d."
Lê e aplica todos os adendos especificados
.IP "e." 3
.IX Item "e."
Escreve o documento traduzido para file_out_name (se fornecido)
.IP "f." 3
.IX Item "f."
Escreve o arquivo \s-1PO\s0 extraído para po_out_name (se fornecido)
.RE
.RS 4
.Sp
\&\s-1ARGUMENTOS,\s0 além dos aceitos por \fBnew()\fR (com o tipo esperado):
.IP "file_in_name (@)" 4
.IX Item "file_in_name (@)"
Lista de nomes de arquivos nos quais nós deveríamos ler o documento de
entrada.
.IP "file_in_charset ($)" 4
.IX Item "file_in_charset ($)"
Conjunto de caracteres usado no documento de entrada (se esse não for
especificado, será tentado a detecção do documento de entrada).
.IP "file_out_name ($)" 4
.IX Item "file_out_name ($)"
Nome de arquivo no qual nós deveríamos escrever o documento de saída.
.IP "file_out_charset ($)" 4
.IX Item "file_out_charset ($)"
Conjunto de caracteres usado no documento de saída (se esse não for
especificado, será usado o conjunto de caracteres do arquivo \s-1PO\s0).
.IP "po_in_name (@)" 4
.IX Item "po_in_name (@)"
Lista de nomes de arquivos dos quais nós deveríamos ler os arquivos \s-1PO\s0 de
entrada, contendo a tradução que será usada para traduzir o documento.
.IP "po_out_name ($)" 4
.IX Item "po_out_name ($)"
Nome de arquivo no qual nós deveríamos escrever o arquivo \s-1PO\s0 de saída,
contendo as strings extraídas do documento de entrada.
.IP "addendum (@)" 4
.IX Item "addendum (@)"
Lista de nomes de arquivos nos quais nós deveríamos ler os adendos.
.IP "addendum_charset ($)" 4
.IX Item "addendum_charset ($)"
Conjunto de caracteres para o adendos.
.RE
.RS 4
.RE
.IP "new(%)" 4
.IX Item "new(%)"
Cria um novo documento de po4a. Opções aceitas são (mas devem estar em um
hash):
.RS 4
.IP "verbose ($)" 4
.IX Item "verbose ($)"
Define o detalhamento.
.IP "debug ($)" 4
.IX Item "debug ($)"
Define a depuração.
.RE
.RS 4
.RE
.SS "Manipulação de arquivos de documento"
.IX Subsection "Manipulação de arquivos de documento"
.IP "read($$)" 4
.IX Item "read($$)"
Adiciona dados de outro documento de entrada ao final do vetor \f(CW\*(C`@{$self\->{TT}{doc_in}}\*(C'\fR existente. O argumento é o nome de arquivo para
ler. Se um segundo argumento é fornecido, ele é o nome de arquivo para usar
em referências.
.Sp
Esse vetor \f(CW\*(C`@{$self\->{TT}{doc_in}}\*(C'\fR detém os dados desse documento de
entrada como um vetor e strings com significados alternativos.
* A string \f(CW$textline\fR detendo cada linha de dados de texto de entrada.
* A string \f(CW\*(C`$filename:$linenum\*(C'\fR detendo sua localização e chamada
como \*(L"referência\*(R" (\f(CW\*(C`linenum\*(C'\fR inicia com 1).
.Sp
Por favor note que ele analisa nada. Você deveria usa a função \fBparse()\fR
quando você acabar de empacotar os arquivos de entrada no documento.
.IP "write($)" 4
.IX Item "write($)"
Escreve o documento traduzido no nome de arquivo fornecido.
.Sp
Os dados desse documento traduzido são fornecidos por:
* \f(CW\*(C`$self\->docheader()\*(C'\fR detendo o texto de cabeçalho para o plugin, e
* \f(CW\*(C`@{$self\->{TT}{doc_out}}\*(C'\fR detendo cada linha do principal texto traduzido no vetor.
.SS "Manipulação de arquivos \s-1PO\s0"
.IX Subsection "Manipulação de arquivos PO"
.IP "readpo($)" 4
.IX Item "readpo($)"
Adiciona o conteúdo de um arquivo, cujo nome é passado como argumento, ao \s-1PO\s0
de entrada existente. O conteúdo antigo é descartado.
.IP "writepo($)" 4
.IX Item "writepo($)"
Escrever o arquivo \s-1PO\s0 extraído para o nome de arquivo fornecido.
.IP "\fBstats()\fR" 4
.IX Item "stats()"
Retorna algumas estatísticas sobre a tradução realizada até o mesmo. Por
favor, note que não são as mesmas estatísticas mostradas pelo \*(L"msgfmt
\&\-\-statistic\*(R". Aqui, são as estatísticas sobre uso recente do arquivo \s-1PO,\s0
enquanto o msgfmt relata o status do arquivo. Ele é um wrapper da função
Locale::Po4a::Po::stats_get aplicada ao arquivo \s-1PO\s0 de entrada. Exemplo de
uso:
.Sp
.Vb 1
\& [uso normal de um documento po4a...]
\&
\& ($percent,$hit,$queries) = $document\->stats();
\& print "Nós encontramos de $percent\e% ($hit de $queries) das strings.\en";
.Ve
.IP "\fBis_po_uptodate()\fR" 4
.IX Item "is_po_uptodate()"
Retorna ($uptodate, \f(CW$diagnostic\fR), sendo que \f(CW$uptodate\fR é se o po de entrada e
o po de saída coincidem (se não, significa que o po de entrada deve ser
atualizado) e \f(CW$diagnostic\fR é uma string explicando por que o arquivo po não
está atualizado, quando isso acontece.
.SS "Manipulando adendos"
.IX Subsection "Manipulando adendos"
.IP "addendum($)" 4
.IX Item "addendum($)"
Por favor veja o \fBpo4a\fR\|(7) para mais informações sobre o que são
adendos e como tradutores deveriam escrevê\-los. Para aplicar um adendo ao
documento traduzido, simplesmente passe seu nome de arquivo para essa função
e pronto ;)
.Sp
Essa função retorna um inteiro não nulo quando há um erro.
.SH "FUNÇÕES INTERNAS usadas para escrever analisadores derivados"
.IX Header "FUNÇÕES INTERNAS usadas para escrever analisadores derivados"
.SS "Obtendo a entrada, fornecendo a saída"
.IX Subsection "Obtendo a entrada, fornecendo a saída"
Quatro funções são fornecidas para obter entrada e retornar a saída. Elas
são muito parecidas com shift/unshift e push/pop de Perl.
.PP
.Vb 4
\& * Perl shift retorna o primeiro item do vetor e solta\-o do vetor.
\&* Perl unshift preenche um item no vetor como o primeiro item do vetor.
\&* Perl pop retorna o último item do vetor e solta\-o do vetor.
\&* Perl push acrescenta um item ao vetor como o último item do vetor.
.Ve
.PP
O primeiro par é sobre entrada, enquanto ao segundo é sobre
saída. Mnemônico: na entrada, você está interessada na primeira linha, que é
o que o shift fornece, e na saída você quer adicionar seu resultado ao
final, como o push faz.
.IP "\fBshiftline()\fR" 4
.IX Item "shiftline()"
Esta função retorna a primeira linha a ser analisada e a sua referência
correspondente (empacotada como um vetor) do vetor \f(CW\*(C`@{$self\->{TT}{doc_in}}\*(C'\fR e descarta estes 2 primeiros itens do vetor. Aqui,
a referência é fornecida por uma string \f(CW\*(C`$filename:$linenum\*(C'\fR.
.IP "unshiftline($$)" 4
.IX Item "unshiftline($$)"
Executa unshift a última linha \*(L"shiftada\*(R" do documento de entrada e sua
referência correspondente de volta para o cabeçalho de \f(CW\*(C`{$self\->{TT}{doc_in}}\*(C'\fR.
.IP "pushline($)" 4
.IX Item "pushline($)"
Envia uma nova linha para o fim de \f(CW\*(C`{$self\->{TT}{doc_out}}\*(C'\fR.
.IP "\fBpopline()\fR" 4
.IX Item "popline()"
Volta, do fim de \f(CW\*(C`{$self\->{TT}{doc_out}}\*(C'\fR, a linha anteriormente
enviada.
.SS "Marcando strings como traduzíveis"
.IX Subsection "Marcando strings como traduzíveis"
Uma função é fornecida para manipular o texto que deveria ser traduzido.
.IP "translate($$$)" 4
.IX Item "translate($$$)"
Argumentos obrigatórios:
.RS 4
.IP "\-" 2
Uma string para traduzir
.IP "\-" 2
A referência dessa string (i.e. posição no arquivo de entrada)
.IP "\-" 2
O tipo dessa string (i.e. a descrição textual de seu papel estrutural; usado
em \fBLocale::Po4a::Po::gettextization()\fR; veja também \fBpo4a\fR\|(7), seção
\&\fBGettextização: como ela funciona?\fR)
.RE
.RS 4
.Sp
Essa função também pode levar alguns argumentos extras. Eles devem ser
organizados como um hash. Por exemplo:
.Sp
.Vb 2
\& $self\->translate("string","ref","type",
\& \*(Aqwrap\*(Aq => 1);
.Ve
.IP "\fBwrap\fR" 4
.IX Item "wrap"
booleano indicando se nós podemos considerar que espaços em brancos nas
strings não são importantes. Se sim, a função canoniza a string antes de
procurar por uma tradução ou de extrair, e dimensiona a tradução.
.IP "\fBwrapcol\fR" 4
.IX Item "wrapcol"
a coluna na qual nós deveríamos dimensionar (padrão: 76).
.IP "\fBcomment\fR" 4
.IX Item "comment"
um comentário extra para adicionar ao registro.
.RE
.RS 4
.Sp
Ações:
.IP "\-" 2
Envia a string, referência e tipo para po_out.
.IP "\-" 2
Retorna a tradução da string (como encontrado em po_in) de forma que o
analisador pode compilar o doc_out.
.IP "\-" 2
Manipula os conjuntos de caracteres para re-codificar as strings antes de
enviá\-las para po_out e antes de retornar as traduções.
.RE
.RS 4
.RE
.SS "Funções miscelânea"
.IX Subsection "Funções miscelânea"
.IP "\fBverbose()\fR" 4
.IX Item "verbose()"
Retorna se a opção de detalhamento foi passada durante a criação do
TransTractor.
.IP "\fBdebug()\fR" 4
.IX Item "debug()"
Retorna se a opção de depuração foi passada durante a criação do
TransTractor.
.IP "detected_charset($)" 4
.IX Item "detected_charset($)"
Isso fala para o TransTractor que um novo conjunto de caracteres (o primeiro
argumento) foi detectado no documento de entrada. Ele normalmente pode ser
lido do cabeçalho do documento. Apenas o primeiro conjunto de caracteres
restará, vindo com os argumentos de \fBprocess()\fR ou detectado do documento.
.IP "\fBget_out_charset()\fR" 4
.IX Item "get_out_charset()"
Essa função vai retornar o conjunto de caracteres que deveria ser usado no
documento do entrada (normalmente útil para substituir o conjunto de
caracteres detectado no documento de entrada, onde ele foi encontrado).
.Sp
Ele vai usar o conjunto de caracteres de saída especificado na linha de
comando. Se não tiver sido especificado, ele vai usar o conjunto de
caracteres do \s-1PO\s0 de entrada, e se o \s-1PO\s0 de entrada possuir o \*(L"\s-1CHARSET\*(R"\s0
padrão, ele vai retornar o conjunto de caracteres do documento de entrada,
de forma que nenhuma codificação é realizada.
.IP "recode_skipped_text($)" 4
.IX Item "recode_skipped_text($)"
Essa função retorna o texto re-codificado passado como argumento, do
conjunto de caracteres do documento de entrada para o do documento de
saída. Isso não é necessário quando se está traduzindo uma string (o próprio
\&\fBtranslate()\fR re-codifica tudo), mas é necessário quando você ignora uma
string do documento de entrada e você deseja que o documento de saída seja
consistente com a codificação global.
.SH "DIREÇÕES FUTURAS"
.IX Header "DIREÇÕES FUTURAS"
Um problema do atual TransTractor é que ele não consegue manipular documento
traduzido contendo todos idiomas, como modelos de debconf, ou arquivos
\&.desktop.
.PP
Para resolver esse problema, as únicas alterações necessárias na interface
são:
.IP "\-" 2
pegar um hash como po_in_name (uma lista por idioma)
.IP "\-" 2
adicionar um argumento para traduzir para indicar o idioma alvo
.IP "\-" 2
fazer uma função pushline_all, que deveria fazer pushline de seu conteúdo
para todos idiomas, usando uma sintaxe tipo mapa:
.Sp
.Vb 3
\& $self\->pushline_all({ "Description[".$langcode."]=".
\& $self\->translate($line,$ref,$langcode)
\& });
.Ve
.PP
Veremos se isso é o suficiente ;)
.SH "AUTORES"
.IX Header "AUTORES"
.Vb 3
\& Denis Barbier