\*(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\-\-; ) { \& # Não é a primeira vez que vemos
. \& # Reponha a linha atual na entrada, \& # e pôr o parágrafo construído à saída \& $self\->unshiftline($line,$lref); \& \& # Agora que o documento é formado, traduza\-o: \& # \- Remova a etiqueta líder \& $paragraph =~ s/^
//s; \& \& # \- Empurre à saída a etiqueta principal (não traduzido) \& # e o resto do parágrafo (traduzido) \& $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, pode usar a sua classe de documento, a usar a interface pública apresentada na próxima secção.
.SH "INTERFACE PÚBLICA para scripts a usar o seu analisador"
.IX Header "INTERFACE PÚBLICA para scripts a usar o seu analisador"
.SS "Construtor"
.IX Subsection "Construtor"
.IP "process(%)" 4
.IX Item "process(%)"
Esta função pode fazer tudo o que precisa fazer com um documento po4a numa invocação. Os argumentos dela 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 cadeias 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(%)"
Cria um novo documento de po4a. Opções aceitas são (no hash passado como parâmetro):
.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($$)"
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 ficheiro a ler. Se um segundo argumento for fornecido, é o nome do ficheiro a ser usado nas 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 cadeias com significados alternativos.
* A cadeia \f(CW$textline\fR a deter cada linha de dados de texto de entrada.
* A cadeia \f(CW\*(C`$filename:$linenum\*(C'\fR a deter a localização dele e chamada
como \*(L"referência\*(R" (\f(CW\*(C`linenum\*(C'\fR starts with 1)..
.Sp
Por favor, note que ele não analisa nada. 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 no nome do ficheiro dado.
.Sp
Os dados desse documento traduzido são fornecidos por:
* \f(CW\*(C`$self\->docheader()\*(C'\fR a deter o texto de cabeçalho para o plugin e
* \f(CW\*(C`@{$self\->{TT}{doc_out}}\*(C'\fR a deter 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 ao 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 cadeias.\en";
.Ve
.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 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, a fornecer saída"
.IX Subsection "Obtenção de entrada, a fornecer 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, está interessada na primeira linha, que é o que o shift fornece e na saída quer adicionar o 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 referência dele 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 cadeia \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 a referência dele correspondente de volta ao cabeçalho de \f(CW\*(C`{$self\->{TT}{doc_in}}\*(C'\fR.
.IP "pushline($)" 4
.IX Item "pushline($)"
Envia uma nova linha ao 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 "Marcar cadeias como traduzíveis"
.IX Subsection "Marcar cadeias como traduzíveis"
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 cadeia para traduzir
.IP "\-" 2
A referência desta cadeia (ou seja, em posição de ficheiro de entrada)
.IP "\-" 2
O tipo desta cadeia (ou seja, a descrição textual do papel estrutural dele; 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 cadeia não são importantes. Se sim, a função canoniza a cadeia 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 devemos envolver (predefinição: 76).
.IP "\fBcomment\fR" 4
.IX Item "comment"
um comentário adicional para a entrada.
.RE
.RS 4
.Sp
Acões:
.IP "\-" 2
Coloca a cadeia de referência e tipo em po_out.
.IP "\-" 2
Retorna a tradução da cadeia (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 cadeias 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á, a vir 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 carácteres, que deviam ser usados na saída (em geral, útil para substituir os conjuntos de carácteres detetados à 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 \*(L"charset\*(R" predefinido, irá retornar um conjunto de carácteres 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 carácteres do documento para os do documento de saída. Isto não é necessário quando traduzir uma cadeia (\fBtranslate()\fR recodifica tudo em si), mas é para quando saltar uma cadeia 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 a conter 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 do conteúdo delepara todos idiomas, a usar 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