\*(R". Pelo bem da simplicidade, assumimos que o documento está bem formatado, ou seja, que etiquetas '
são as etiquetas apenas presentes, e que esta marca é no início 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\-\-; ) { \& # Not the first time we see
. \& # Reput the current line in input, \& # and put the built paragraph to output \& $self\->unshiftline($line,$lref); \& \& # Agora que o documento é formado, traduza\-o: \& # \- Remova a etiqueta líder \& $paragraph =~ s/^
//s; \& \& # \- push to output the leading tag (untranslated) and the \& # rest of the paragraph (translated) \& $self\->pushline( "
"
\& . $self\->translate($paragraph,$pararef)
\& );
\&
\& próximo PARAGRÁFO;
\& } else {
\& # Acrescente o parágrafo
\& $paragraph .= $line;
\& $pararef = $lref unless(lenght($pararef));
\& }
\&
\& # Reiniciar o ciclo
\& ($line,$lref)=$self\->shiftline();
\& }
\& # Não tem uma linha definida? Fim do ficheiro de entrada.
\& return;
\& }
\& }
.Ve
.PP
Depois de implementar a função de análise, você pode usar a sua classe de
documento, usando a interface pública apresentada na próxima secção.
.SH "INTERFACE PÚBLICA para scripts usando o seu analisador"
.IX Header "INTERFACE PÚBLICA para scripts usando o seu analisador"
.SS "Construtor"
.IX Subsection "Construtor"
.IP "process(%)" 4
.IX Item "process(%)"
Esta função pode fazer tudo o que você precisa fazer com um documento po4a
numa invocação. Os seus argumentos devem ser empacotados como uma
\&'hash'. AÇÕES:
.RS 4
.IP "a." 3
.IX Item "a."
Lê todos os ficheiros \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 todas as adendas especificadas
.IP "e." 3
.IX Item "e."
Escreve o documento traduzido para o file_out_name (se dado)
.IP "f." 3
.IX Item "f."
Escreve o ficheiro \s-1PO\s0 extraído para po_out_name (se dado)
.RE
.RS 4
.Sp
\&\s-1ARGUMENTOS,\s0 ao lado dos aceites por \fBnew()\fR (com o tipo esperado):
.IP "file_in_name (@)" 4
.IX Item "file_in_name (@)"
Lista de nomes de ficheiros onde devemos ler o documento de entrada.
.IP "file_in_charset ($)" 4
.IX Item "file_in_charset ($)"
O conjunto de carateres utilizado no documento de entrada (se não for
especificado, ele vai tentar detectá\-lo a partir do documento de entrada).
.IP "file_out_name ($)" 4
.IX Item "file_out_name ($)"
Nome do ficheiro onde devemos escrever o documento de saída.
.IP "file_out_charset ($)" 4
.IX Item "file_out_charset ($)"
Conjunto de carateres utilizado no documento de saída (se não for
especificado, será usado o conjunto de carateres do ficheiro \s-1PO\s0).
.IP "po_in_name (@)" 4
.IX Item "po_in_name (@)"
Lista de nomes de ficheiros onde devemos ler os ficheiros de entrada do \s-1PO,\s0
que contêm a tradução que irá ser usada para traduzir o documento.
.IP "po_out_name ($)" 4
.IX Item "po_out_name ($)"
Nome do ficheiro onde devemos escrever a saída do ficheiro \s-1PO,\s0 que contém as
sequências extraídas do documento de entrada.
.IP "addendum (@)" 4
.IX Item "addendum (@)"
Lista de nomes de ficheiros que devemos ler a adenda de.
.IP "addendum_charset ($)" 4
.IX Item "addendum_charset ($)"
Conjunto de carateres para a adenda.
.RE
.RS 4
.RE
.IP "new(%)" 4
.IX Item "new(%)"
Criar um documento po4a novo. Opções aceitas (mas está num 'hash'):
.RS 4
.IP "verbose ($)" 4
.IX Item "verbose ($)"
Define o nivel de detalhe
.IP "debug ($)" 4
.IX Item "debug ($)"
Define a depuração
.RE
.RS 4
.RE
.SS "Manipulação de ficheiros de documentos"
.IX Subsection "Manipulação de ficheiros de documentos"
.IP "read($$)" 4
.IX Item "read($$)"
Add another input document data at the end of the existing array \f(CW\*(C`@{$self\->{TT}{doc_in}}\*(C'\fR. The argument is the filename to read. If a second
argument is provided, it is the filename to use in the references.
.Sp
This array \f(CW\*(C`@{$self\->{TT}{doc_in}}\*(C'\fR holds this input document data as an
array of strings with alternating meanings.
* The string \f(CW$textline\fR holding each line of the input text data.
* The string \f(CW\*(C`$filename:$linenum\*(C'\fR holding its location and called as
\*(L"reference\*(R" (\f(CW\*(C`linenum\*(C'\fR starts with 1).
.Sp
Por favor, note que ele não analisa nada. Você deve usar a função \fBparse()\fR
quando está feito com o empacotamento de ficheiros de entrada no documento.
.IP "escrever($)" 4
.IX Item "escrever($)"
Escreva o documento traduzido para o nome do ficheiro dado.
.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 "Manipulando ficheiros \s-1PO\s0"
.IX Subsection "Manipulando ficheiros PO"
.IP "readpo($)" 4
.IX Item "readpo($)"
Adicionar o conteúdo dum ficheiro (que o nome é passado como argumento) para
o actual \s-1PO\s0 de entrada. O conteúdo antigo não é descartado.
.IP "writepo($)" 4
.IX Item "writepo($)"
Gravar o ficheiro \s-1PO\s0 extraído para o nome do ficheiro dado.
.IP "\fBstats()\fR" 4
.IX Item "stats()"
Retorna algumas estatísticas sobre a tradução feita até agora. Note que não
é a mesma estatística que a impressa por msgfmt\*(--statistic. Aqui, são
estatísticas sobre o uso recente do ficheiro \s-1PO,\s0 enquanto msgfmt relata o
estado do ficheiro. Ele é um envolvido para função
Locale::Po4a::Po::stats_get aplicada ao ficheiro de entrada \s-1PO.\s0 Exemplo de
uso:
.Sp
.Vb 1
\& [utilização normal do documento po4a ...]
\&
\& ($percent,$hit,$queries) = $document\->stats();
\& print "Encontramos traduções para $percent\e% ($hit from $queries) de sequências.\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 ficheiro po não
está atualizado, quando isso acontece.
.SS "Manipulação da adenda"
.IX Subsection "Manipulação da adenda"
.IP "addendum($)" 4
.IX Item "addendum($)"
Por favor, consulte \fBpo4a\fR\|(7) para obter mais informações sobre o
que são adendas e, como os tradutores devem escrevê\-las. Para aplicar uma
adenda ao documento traduzido, basta passar o nome do ficheiro para esta
função e você está feito ;)
.Sp
Esta função retorna um inteiro não nulo em caso de erro.
.SH "FUNÇÕES INTERNAS usadas para escrever analisadores derivados"
.IX Header "FUNÇÕES INTERNAS usadas para escrever analisadores derivados"
.SS "Obtenção de entrada, fornecendo saída"
.IX Subsection "Obtenção de entrada, fornecendo 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 "Sequências de marcação como traduzível"
.IX Subsection "Sequências de marcação como traduzível"
Uma função é fornecida para lidar com o texto que deve ser traduzido.
.IP "translate($$$)" 4
.IX Item "translate($$$)"
Argumentos obrigatórios:
.RS 4
.IP "\-" 2
Uma sequência para traduzir
.IP "\-" 2
A referência desta sequência (ou seja, em posição de ficheiro de entrada)
.IP "\-" 2
O tipo desta sequência (ou seja, a descrição textual do seu papel
estrutural; usado em \fBLocale::Po4a::Po::gettextization()\fR; ver também
\&\fBpo4a\fR\|(7), secção \fBGettextization: como é que funciona?\fR)
.RE
.RS 4
.Sp
Esta função também pode ter alguns argumentos extras. Eles devem ser
organizadas como uma 'hash'. Um exemplo:
.Sp
.Vb 2
\& $self\->translate("string","ref","type",
\& \*(Aqwrap\*(Aq => 1);
.Ve
.IP "\fBwrap\fR" 4
.IX Item "wrap"
booleano que indica se podemos considerar que os espaços em branco na
sequência não são importantes. Se sim, a função canoniza a sequência antes
de procurar a tradução ou extraí\-la, e envolve a tradução.
.IP "\fBwrapcol\fR" 4
.IX Item "wrapcol"
a coluna em que nos devemos envolver (padrão: 76)
.IP "\fBcomment\fR" 4
.IX Item "comment"
um comentário extra para a entrada.
.RE
.RS 4
.Sp
Acões:
.IP "\-" 2
Coloca a sequência de referência, e tipo em po_out.
.IP "\-" 2
Retorna a tradução da sequência (como encontrada em po_in), de modo que o
analisador pode construir o doc_out.
.IP "\-" 2
Lida com os conjuntos de carateres para recodificar as sequências antes de
as enviar para po_out e antes de voltar às traduções.
.RE
.RS 4
.RE
.SS "Funções diversas"
.IX Subsection "Funções diversas"
.IP "\fBverbose()\fR" 4
.IX Item "verbose()"
Retorna se a opção 'verbose' foi aprovada durante a criação do TransTractor.
.IP "\fBdebug()\fR" 4
.IX Item "debug()"
Retorna se a opção de depuração foi aprovada durante a criação
doTransTractor.
.IP "detected_charset($)" 4
.IX Item "detected_charset($)"
Isto diz TransTractor que um conjunto de carateres novo (o primeiro
argumento) foi detetado a partir do documento de entrada. Normalmente pode
ser lido a partir do cabeçalho do documento. Apenas o primeiro conjunto de
carateres permanecerá, vindo a partir dos argumentos de \fBprocess()\fR ou
detetados a partir do documento.
.IP "\fBget_out_charset()\fR" 4
.IX Item "get_out_charset()"
Esta função irá retornar o conjunto de caracteres, que deviam ser usados
na saída (em geral, útil para substituir os conjuntos de
carateresdetetados à entrada do documento onde foi encontrado).
.Sp
Ele vai usar o conjunto de carateres de saída especificado na linha de
comando. Se não fosse especificado, será usado o conjunto de carateres \s-1PO\s0 de
entrada e, se a entrada de \s-1PO\s0 tem o padrão \*(L"charset\*(R", irá retornar conjunto
de carateres do documento de entrada, de modo a que nenhuma codificação é
realizada.
.IP "recode_skipped_text($)" 4
.IX Item "recode_skipped_text($)"
Esta função retorna o texto recodificado passado como argumento, a partir do
conjunto de carateres do documento para os do documento de saída. Isto não é
necessário quando traduzir uma sequência (\fBtranslate()\fR recodifica tudo em
si), mas é para quando saltar uma sequência do documento de entrada e quer
que o documento de saída seja consistente com a codificação global.
.SH "DIREÇÕES FUTURAS"
.IX Header "DIREÇÕES FUTURAS"
Uma falha do TransTractor atual é que ele não pode tratar de documentos
traduzidos contendo todas os idiomas, como modelos debconf, ou ficheiros
desktops.
.PP
Para resolver este problema, as únicas mudanças na interface necessárias
são:
.IP "\-" 2
obter um 'hash' como po_in_name (uma lista por idioma)
.IP "\-" 2
adicionar um argumento para traduzir para indicar a língua apontada
.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
Vai ver se é suficiente ;)
.SH "AUTORES"
.IX Header "AUTORES"
.Vb 3
\& Denis Barbier