". Pelo bem da simplicidade, assumimos que o documento esta bem formatado, ou seja, que etiquetas '
sao as etiquetas apenas presentes e que esta marca e no inicio de cada paragrafo. 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); # Now that the document is formed, translate it: # - Remove the leading tag $paragraph =~ s/^
//s; # - push to output the leading tag (untranslated) and the # rest of the paragraph (translated) $self->pushline( "
"
. $self->translate($paragraph,$pararef)
);
next PARAGRAPH;
} else {
# Append to the paragraph
$paragraph .= $line;
$pararef = $lref unless(length($pararef));
}
# Reinit the loop
($line,$lref)=$self->shiftline();
}
# Did not get a defined line? End of input file.
return;
}
}
Depois de implementar a funcao de analise, pode usar a sua classe de
documento, usando a interface publica apresentada na proxima seccao.
INTERFACE PUBLICA para scripts que usam o seu analisador
Construtor
process(%)
Esta funcao pode fazer tudo o que precisa fazer com um documento
po4a numa invocacao. Os argumentos dela devem ser empacotados como
uma 'hash'. ACOES:
a. Le todos os ficheiros PO especificados em po_in_name
b. Le todos os documentos originais especificados em file_in_name
c. Analisa o documento
d. Le e aplica todas as adendas especificadas
e. Escreve o documento traduzido para o nome_ficheiro_saida (se
dado)
f. Escreve o ficheiro PO extraido para nome_po_saida (se dado)
ARGUMENTOS, alem daqueles aceites pelo new() (com o tipo esperado):
file_in_name (@)
Lista de nomes de ficheiros onde devemos ler o documento de
entrada.
file_in_charset ($)
Conjunto de caracteres usado no documento de entrada (se nao
for especificado, usa UTF-8).
file_out_name ($)
Nome do ficheiro onde devemos escrever o documento de saida.
file_out_charset ($)
Conjunto de caracteres usado no documento de saida (se nao for
especificado, usa UTF-8).
po_in_name (@)
Lista de nomes de ficheiros onde devemos ler os ficheiros de
entrada do PO, que contem a traducao que ira ser usada para
traduzir o documento.
po_out_name ($)
Nome do ficheiro onde devemos escrever a saida do ficheiro PO,
que contem as cadeias extraidas do documento de entrada.
addendum (@)
Lista de nomes de ficheiros de onde devemos ler a adenda.
addendum_charset ($)
Conjunto de caracteres para a adenda.
new(%)
Cria um novo documento de po4a. Opcoes aceites (no hash passado
como parametro):
verbose ($)
Define o nivel de detalhe.
debug ($)
Define a depuracao.
wrapcol ($)
A coluna na qual devemos fazer a quebra de texto no documento
de saida (predefinicao: 76).
O valor negativo significa nao quebrar as linhas.
Tambem aceita as proximas opcoes para ficheiros PO subjacentes:
porefs, copyright-holder, msgid-bugs-address, package-name,
package-version, wrap-po.
Manipulando ficheiros de documentos
read($$$)
Adiciona outros dados do documento de entrada no final da array
existente "@{$self->{TT}{doc_in}}".
Esta funcao recebe dois argumentos obrigatorios e um opcional.
* O nome do ficheiro a ser lido no disco;
* O nome a ser usado como nome do ficheiro ao construir a
referencia no ficheiro PO;
* O conjunto de caracteres a ser usado para ler esse ficheiro
(UTF-8 por predefinicao)
Esta matriz "@{$self->{TT}{doc_in}}" detem os dados desse documento
de entrada como uma matriz de cadeias com significados
alternativos.
* A cadeia $textline que detem cada linha de dados de texto de
entrada.
* A cadeia "$filename:$linenum" que detem a sua localizacao e
chamada
como "referencia" ("linenum" starts with 1)..
Por favor, note que ele nao analisa nada. Deve usar a funcao
parse() quando esta feito com o empacotamento de ficheiros de
entrada no documento.
escrever($)
Escreva o documento traduzido no nome do ficheiro dado.
Os dados desse documento traduzido sao fornecidos por:
* "$self->docheader()" a deter o texto de cabecalho para o plugin
e
* "@{$self->{TT}{doc_out}}" a deter cada linha do principal texto
traduzido na matriz.
Manipulando ficheiros PO
readpo($)
Adiciona o conteudo dum ficheiro (que o nome e passado como
argumento) para o actual PO de entrada. O conteudo antigo nao e
descartado.
writepo($)
Gravar o ficheiro PO extraido no nome do ficheiro dado.
stats()
Retorna algumas estatisticas sobre a traducao feita ate agora. Note
que nao e a mesma estatistica que aquela escrita por
msgfmt--statistic. Aqui, sao estatisticas sobre o uso recente do
ficheiro PO, enquanto msgfmt relata o estado do ficheiro. Ele e um
envolvido para funcao Locale::Po4a::Po::stats_get aplicada ao
ficheiro de entrada PO. Exemplo de uso:
[uso normal do documento po4a...]
($percent,$hit,$queries) = $document->stats();
print "Encontramos traducoes para $percent\% ($hit from $queries) de cadeias.\n";
Manipulando a adenda
addendum($)
Por favor, consulte po4a(7) para obter mais informacoes sobre o que
sao adendas e como os tradutores devem escreve-las. Para aplicar
uma adenda ao documento traduzido, basta passar o nome do ficheiro
para esta funcao e esta feito ;)
Esta funcao retorna um inteiro nao nulo em caso de erro.
FUNCOES INTERNAS usadas para escrever analisadores derivados
Obter a entrada, fornecer a saida
Quatro funcoes sao fornecidas para obter entrada e retornar a saida.
Elas sao muito parecidas com shift/unshift e push/pop de Perl.
* Perl shift retorna o primeiro item da matriz e solta-o da matriz.
* Perl unshift preenche um item da matriz como o primeiro item da matriz.
* Perl pop retorna o ultimo item da matriz e solta-o da matriz.
* Perl push acrescenta um item da matriz como o ultimo item da matriz.
O primeiro par e sobre entrada, enquanto ao segundo e sobre saida.
Mnemonico: na entrada, esta interessada na primeira linha, que e o que
o shift fornece e na saida quer adicionar o seu resultado ao final,
como o push faz.
shiftline()
Esta funcao retorna a primeira linha a ser analisada e a referencia
dele correspondente (empacotada como uma matriz) da matriz
"@{$self->{TT}{doc_in}}" e descarta estes 2 primeiros itens da
matriz. Aqui, a referencia e fornecida por uma cadeia
"$filename:$linenum".
unshiftline($$)
Desloca a ultima linha deslocada do documento de entrada e a
referencia dele correspondente de volta ao cabecalho de
"{$self->{TT}{doc_in}}".
pushline($)
Forca uma nova linha no fim de "{$self->{TT}{doc_out}}".
popline()
Estoira a ultima linha forcada do final de
"{$self->{TT}{doc_out}}".
Marcando cadeias como traduziveis
Uma funcao e fornecida para lidar com o texto que deve ser traduzido.
translate($$$)
Argumentos obrigatorios:
- Uma cadeia para traduzir
- A referencia desta cadeia (ou seja, posicao no ficheiro de
entrada)
- O tipo desta cadeia (ou seja, a descricao textual do papel
estrutural dele; usado em Locale::Po4a::Po::gettextization(); ver
tambem po4a(7), seccao Gettextization: how does it work?)
Esta funcao tambem pode ter alguns argumentos extras. Eles devem
ser organizadas como uma 'hash'. Um exemplo:
$self->translate("string","ref","type",
'wrap' => 1);
wrap
booleano que indica se podemos considerar que os espacos em
branco na cadeia nao sao importantes. Se sim, a funcao canoniza
a cadeia antes de procurar a traducao ou extrai-la, e envolve a
traducao.
wrapcol
a coluna na qual devemos fazer a quebra da linha (predefinicao:
o valor de wrapcol especificado durante a criacao do
TransTractor ou 76).
O valor negativo sera subtraido da predefinicao.
comment
um comentario adicional para a entrada.
Acoes:
- Coloca a cadeia de referencia e tipo em po_out.
- Retorna a traducao da cadeia (como encontrada em po_in), de modo
que o analisador pode construir o doc_out.
- Lida com os conjuntos de caracteres para recodificar as cadeias
antes de as enviar para po_out e antes de voltar as traducoes.
Funcoes diversas
verbose()
Retorna se a opcao 'verbose' foi passada durante a criacao do
TransTractor.
debug()
Retorna se a opcao de depuracao foi passada durante a criacao
doTransTractor.
get_in_charset()
Esta funcao retorna o charset que foi fornecido como o conjunto de
caracteres mestre
get_out_charset()
Esta funcao ira retornar o conjunto de caracteres, que deviam ser
usados na saida (em geral, util para substituir os conjuntos de
caracteres detetados a entrada do documento onde foi encontrado).
Vai usar o conjunto de caracteres de saida especificado na linha de
comando. Se nao fosse especificado, seria usado o conjunto de
caracteres do PO de entrada e, se a entrada de PO tem o "CHARSET"
predefinido, ira retornar um conjunto de caracteres do documento de
entrada, de modo a que nenhuma codificacao e realizada.
DIRECOES FUTURAS
Uma falha do TransTractor atual e que ele nao pode tratar de documentos
traduzidos que contem todos os idiomas, como modelos debconf, ou
ficheiros .desktop.
Para resolver este problema, as unicas mudancas na interface
necessarias sao:
- obter um 'hash' como po_in_name (uma lista por idioma)
- adicionar um argumento para traduzir para indicar a lingua apontada
- fazer uma funcao pushline_all, que deveria fazer pushline do conteudo
dele para todos idiomas, a usar uma sintaxe tipo mapa:
$self->pushline_all({ "Description[".$langcode."]=".
$self->translate($line,$ref,$langcode)
});
Vamos ver se e suficiente ;)
AUTORES
Denis Barbier