". 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--; ) { # Nao e a primeira vez que vemos
. # Reponha a linha atual na entrada, # e por o paragrafo construido a saida $self->unshiftline($line,$lref); # Agora que o documento e formado, traduza-o: # - Remova a etiqueta lider $paragraph =~ s/^
//s; # - Empurre a saida a etiqueta principal (nao traduzido) # e o resto do paragrafo (traduzido) $self-> pushline( "
"
. $self->translate($paragraph,$pararef)
);
proximo PARAGRAFO;
} else {
# Acrescente o paragrafo
$paragraph .= $line;
$pararef = $lref unless(lenght($pararef));
}
# Reiniciar o ciclo
($line,$lref)=$self->shiftline();
}
# Nao tem uma linha definida? Fim do ficheiro de entrada.
return;
}
}
Depois de implementar a funcao de analise, pode usar a sua classe de
documento, a usar a interface publica apresentada na proxima seccao.
INTERFACE PUBLICA para scripts a usar 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 file_out_name (se dado)
f. Escreve o ficheiro PO extraido para po_out_name (se dado)
ARGUMENTOS, ao lado dos aceites por new() (com o tipo esperado):
file_in_name (@)
Lista de nomes de ficheiros onde devemos ler o documento de
entrada.
file_in_charset ($)
Charset used in the input document (if it isn't specified, use
UTF-8).
file_out_name ($)
Nome do ficheiro onde devemos escrever o documento de saida.
file_out_charset ($)
Charset used in the output document (if it isn't specified, use
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 que devemos ler a adenda de.
addendum_charset ($)
Conjunto de carateres para a adenda.
new(%)
Cria um novo documento de po4a. Opcoes aceitas sao (no hash passado
como parametro):
verbose ($)
Define o nivel de detalhe.
debug ($)
Define a depuracao.
wrapcol ($)
The column at which we should wrap text in output document
(default: 76).
The negative value means not to wrap lines at all.
Also it accepts next options for underlying Po-files: porefs,
copyright-holder, msgid-bugs-address, package-name, package-
version, wrap-po.
Manipulacao de ficheiros de documentos
read($$$)
Add another input document data at the end of the existing array
"@{$self->{TT}{doc_in}}".
This function takes two mandatory arguments and an optional one.
* The filename to read on disk;
* The name to use as filename when building the reference in the
PO file;
* The charset to use to read that file (UTF-8 by default)
Esse vetor "@{$self->{TT}{doc_in}}" detem os dados desse documento
de entrada como um vetor e cadeias com significados alternativos.
* A cadeia $textline a deter cada linha de dados de texto de
entrada.
* A cadeia "$filename:$linenum" a deter a localizacao dele 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 no vetor.
Manipulando ficheiros PO
readpo($)
Adicionar 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 ao nome do ficheiro dado.
stats()
Retorna algumas estatisticas sobre a traducao feita ate agora. Note
que nao e a mesma estatistica que a impressa 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:
[utilizacao normal do documento po4a ...]
($percent,$hit,$queries) = $document->stats();
print "Encontramos traducoes para $percent\% ($hit from $queries) de cadeias.\n";
Manipulacao da 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
Obtencao de entrada, a fornecer 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, 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 um vetor) do vetor
"@{$self->{TT}{doc_in}}" e descarta estes 2 primeiros itens do
vetor. Aqui, a referencia e fornecida por uma cadeia
"$filename:$linenum".
unshiftline($$)
Executa unshift a ultima linha "shiftada" do documento de entrada e
a referencia dele correspondente de volta ao cabecalho de
"{$self->{TT}{doc_in}}".
pushline($)
Envia uma nova linha ao fim de "{$self->{TT}{doc_out}}".
popline()
Volta, do fim de "{$self->{TT}{doc_out}}", a linha anteriormente
enviada.
Marcar 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, em posicao de 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: como e que funciona?)
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
the column at which we should wrap (default: the value of
wrapcol specified during creation of the TransTractor or 76).
The negative value will be substracted from the default.
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 carateres 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 aprovada durante a criacao do
TransTractor.
debug()
Retorna se a opcao de depuracao foi aprovada durante a criacao
doTransTractor.
get_in_charset()
This function return the charset that was provided as master
charset
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).
Ele vai usar o conjunto de carateres de saida especificado na linha
de comando. Se nao fosse especificado, sera usado o conjunto de
carateres 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 a conter todas os idiomas, como modelos debconf, ou
ficheiros desktops.
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
delepara todos idiomas, a usar uma sintaxe tipo mapa:
$self->pushline_all({ "Description[".$langcode."]=".
$self->translate($line,$ref,$langcode)
});
Vai ver se e suficiente ;)
AUTORES
Denis Barbier