". Em nome da simplicidade, nos presumimos que o documento esta bem formatado, ou seja, que as marcacoes "
" sao as unicas marcacoes apresentadas e que essa marcacao esta exatamente no comeco 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--; ) { # Nao e primeira vez que vemos
. # Coloca novamente a linha atual na entrada, # e coloca o paragrafo na saida $self->unshiftline($line,$lref); # Agora que o documento e formatado, traduza-o: # - Remove a tag de abertura $paragraph =~ s/^
//s; # - Envia a saida para a tag de abertura (nao traduzida) # e o resto do paragrafo (traduzido) $self->pushline( "
"
. $self->translate($paragraph,$pararef)
);
next PARAGRAPH;
} else {
# Adiciona o paragrafo ao final
$paragraph .= $line;
$pararef = $lref unless(length($pararef));
}
# Reinicia o loop
($line,$lref)=$self->shiftline();
}
# Nao obteve uma linha definida? Fim do arquivo de entrada.
return;
}
}
Uma vez que voce tenha implementada a funcao de analise, voce pode usar
sua classe de documento, usando a interface publica apresentada na
secao seguinte.
INTERFACE PUBLICA para scripts usando seu analisador
Construtor
process(%)
Essa funcao pode fazer tudo que voce precisa fazer com um documento
po4a em uma chamada. Seus argumentos devem ser empacotados como um
hash. ACOES:
a. Le todos os arquivos 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 todos os adendos especificados
e. Escreve o documento traduzido para file_out_name (se fornecido)
f. Escreve o arquivo PO extraido para po_out_name (se fornecido)
ARGUMENTOS, alem dos aceitos por new() (com o tipo esperado):
file_in_name (@)
Lista de nomes de arquivos nos quais nos deveriamos ler o
documento de entrada.
file_in_charset ($)
Conjunto de caracteres usado no documento de entrada (se esse
nao for especificado, usa UTF-8).
file_out_name ($)
Nome de arquivo no qual nos deveriamos escrever o documento de
saida.
file_out_charset ($)
Conjunto de caracteres usado no documento de saida (se esse nao
for especificado, usa UTF-8).
po_in_name (@)
Lista de nomes de arquivos dos quais nos deveriamos ler os
arquivos PO de entrada, contendo a traducao que sera usada para
traduzir o documento.
po_out_name ($)
Nome de arquivo no qual nos deveriamos escrever o arquivo PO de
saida, contendo as strings extraidas do documento de entrada.
addendum (@)
Lista de nomes de arquivos nos quais nos deveriamos ler os
adendos.
addendum_charset ($)
Conjunto de caracteres para o adendos.
new(%)
Cria um novo documento de po4a. Opcoes aceitas sao (no hash passado
como parametro):
verbose ($)
Define o detalhamento.
debug ($)
Define a depuracao.
wrapcol ($)
A coluna na qual nos devemos fazer a quebra de texto no
documento de saida (padrao: 76).
O valor negativo significa nao quebrar as linhas.
Tambem aceita as proximas opcoes para arquivos PO subjacentes:
porefs, copyright-holder, msgid-bugs-address, package-name,
package-version, wrap-po.
Manipulacao de arquivos de documento
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 arquivo a ser lido no disco;
* O nome a ser usado como nome do arquivo ao construir a
referencia no arquivo PO;
* O conjunto de caracteres a ser usado para ler esse arquivo
(UTF-8 por padrao)
Esse vetor "@{$self->{TT}{doc_in}}" detem os dados desse documento
de entrada como um vetor e strings com significados alternativos.
* A string $textline detendo cada linha de dados de texto de
entrada.
* A string "$filename:$linenum" detendo sua localizacao e chamada
como "referencia" ("linenum" inicia com 1).
Por favor note que ele analisa nada. Voce deveria usa a funcao
parse() quando voce acabar de empacotar os arquivos de entrada no
documento.
write($)
Escreve o documento traduzido no nome de arquivo fornecido.
Os dados desse documento traduzido sao fornecidos por:
* "$self->docheader()" detendo o texto de cabecalho para o plugin,
e
* "@{$self->{TT}{doc_out}}" detendo cada linha do principal texto
traduzido no vetor.
Manipulacao de arquivos PO
readpo($)
Adiciona o conteudo de um arquivo, cujo nome e passado como
argumento, ao PO de entrada existente. O conteudo antigo e
descartado.
writepo($)
Escrever o arquivo PO extraido para o nome de arquivo fornecido.
stats()
Retorna algumas estatisticas sobre a traducao realizada ate o
mesmo. Por favor, note que nao sao as mesmas estatisticas mostradas
pelo "msgfmt --statistic". Aqui, sao as estatisticas sobre uso
recente do arquivo PO, enquanto o msgfmt relata o status do
arquivo. Ele e um wrapper da funcao Locale::Po4a::Po::stats_get
aplicada ao arquivo PO de entrada. Exemplo de uso:
[uso normal do documento po4a...]
($percent,$hit,$queries) = $document->stats();
print "Nos encontramos de $percent\% ($hit de $queries) das strings.\n";
Manipulando adendos
addendum($)
Por favor veja o po4a(7) para mais informacoes sobre o que sao
adendos e como tradutores deveriam escreve-los. Para aplicar um
adendo ao documento traduzido, simplesmente passe seu nome de
arquivo para essa funcao e pronto ;)
Essa funcao retorna um inteiro nao nulo quando ha um erro.
FUNCOES INTERNAS usadas para escrever analisadores derivados
Obtendo a entrada, fornecendo 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 do vetor e solta-o do vetor.
* Perl unshift preenche um item no vetor como o primeiro item do vetor.
* Perl pop retorna o ultimo item do vetor e solta-o do vetor.
* Perl push acrescenta um item ao vetor como o ultimo item do vetor.
O primeiro par e sobre entrada, enquanto ao segundo e sobre saida.
Mnemonico: na entrada, voce esta interessada na primeira linha, que e o
que o shift fornece, e na saida voce quer adicionar seu resultado ao
final, como o push faz.
shiftline()
Esta funcao retorna a primeira linha a ser analisada e a sua
referencia correspondente (empacotada como um vetor) do vetor
"@{$self->{TT}{doc_in}}" e descarta estes 2 primeiros itens do
vetor. Aqui, a referencia e fornecida por uma string
"$filename:$linenum".
unshiftline($$)
Executa unshift a ultima linha "shiftada" do documento de entrada e
sua referencia correspondente de volta para o cabecalho de
"{$self->{TT}{doc_in}}".
pushline($)
Envia uma nova linha para o fim de "{$self->{TT}{doc_out}}".
popline()
Volta, do fim de "{$self->{TT}{doc_out}}", a linha anteriormente
enviada.
Marcando strings como traduziveis
Uma funcao e fornecida para manipular o texto que deveria ser
traduzido.
translate($$$)
Argumentos obrigatorios:
- Uma string para traduzir
- A referencia dessa string (i.e. posicao no arquivo de entrada)
- O tipo dessa string (i.e. a descricao textual de seu papel
estrutural; usado em Locale::Po4a::Po::gettextization(); veja
tambem po4a(7), secao Gettextizacao: como ela funciona?)
Essa funcao tambem pode levar alguns argumentos extras. Eles devem
ser organizados como um hash. Por exemplo:
$self->translate("string","ref","type",
'wrap' => 1);
wrap
booleano indicando se nos podemos considerar que espacos em
brancos nas strings nao sao importantes. Se sim, a funcao
canoniza a string antes de procurar por uma traducao ou de
extrair, e dimensiona a traducao.
wrapcol
a coluna na qual devemos fazer a quebra da linha (padrao: o
valor de wrapcol especificado durante a criacao do TransTractor
ou 76).
O valor negativo sera subtraido do padrao.
comment
um comentario extra para adicionar ao registro.
Acoes:
- Envia a string, referencia e tipo para po_out.
- Retorna a traducao da string (como encontrado em po_in) de forma
que o analisador pode compilar o doc_out.
- Manipula os conjuntos de caracteres para re-codificar as strings
antes de envia-las para po_out e antes de retornar as traducoes.
Funcoes miscelanea
verbose()
Retorna se a opcao de detalhamento foi passada durante a criacao do
TransTractor.
debug()
Retorna se a opcao de depuracao foi passada durante a criacao do
TransTractor.
get_in_charset()
Esta funcao retorna o charset que foi fornecido como o charset
mestre
get_out_charset()
Essa funcao vai retornar o conjunto de caracteres que deveria ser
usado no documento do entrada (normalmente util para substituir o
conjunto de caracteres detectado no documento de entrada, onde ele
foi encontrado).
Ele vai usar o conjunto de caracteres de saida especificado na
linha de comando. Se nao tiver sido especificado, ele vai usar o
conjunto de caracteres do PO de entrada, e se o PO de entrada
possuir o "CHARSET" padrao, ele vai retornar o conjunto de
caracteres do documento de entrada, de forma que nenhuma
codificacao e realizada.
DIRECOES FUTURAS
Um problema do atual TransTractor e que ele nao consegue manipular
documento traduzido contendo todos idiomas, como modelos de debconf, ou
arquivos .desktop.
Para resolver esse problema, as unicas alteracoes necessarias na
interface sao:
- pegar um hash como po_in_name (uma lista por idioma)
- adicionar um argumento para traduzir para indicar o idioma alvo
- fazer uma funcao pushline_all, que deveria fazer pushline de seu
conteudo para todos idiomas, usando uma sintaxe tipo mapa:
$self->pushline_all({ "Description[".$langcode."]=".
$self->translate($line,$ref,$langcode)
});
Veremos se isso e o suficiente ;)
AUTORES
Denis Barbier