Locale::Po4a::TransTractor - genérico trans(lator ex)trator.
O objetivo do projeto po4a (PO for anything: PO para qualquer coisa) é
facilitar traduções (e o mais interessante, a
manutenção das traduções) a usar as ferramentas do
gettext em áreas em que não se esperava, como na
documentação.
Esta classe é o ancestral de todos os analisadores po4a usado para
analisar um documento, para pesquisar cadeias traduzíveis, para
extraí-las para um ficheiro PO e substitui-los pela
tradução dela no documento de saída.
Mais formalmente, toma os seguintes argumentos como entrada:
- -
- um documento para traduzir;
- -
- Um ficheiro PO que contém as traduções
para usar.
Como saída, produz:
- -
- outro ficheiro PO, resultante da extração de
cadeias traduzíveis em documento de entrada;
- -
- um documento traduzido, com a mesma estrutura do que o de
entrada, mas com todas as cadeias traduzíveis substituídas
com as traduções encontradas no ficheiro PO fornecido na
entrada.
Aqui está uma representação gráfica deste:
Documento de entrada --\ / ---> documento de saída
\ / (traduzido)
+-> função analisar() ---+
/ \
Entrada PO ------------/ \---> Saída PO
(extraído)
- parse()
- Este é o lugar onde todo o trabalho tem lugar: a
análise dos documentos de entrada, a geração da
saída e a extração das cadeias traduzíveis.
Isto é muito simples a usar as funções
disponíveis apresentadas na secção abaixo INTERNAL
FUNCTIONS. Ver também o SYNOPSIS, o qual apresenta um
exemplo.
Esta função é invocada pela função
processo() abaixo, mas se escolher usar a função
new() e, para adicionar conteúdo manualmente qo documento,
terá que invocar esta função você mesmo.
- docheader()
- Esta função retorna o cabeçalho que
devemos acrescentar ao documento produzido, citado corretamente para ser
um comentário na língua apontada. Consulte a
secção Educating developers about translations, de
po4a(7), que é para o bem de todos.
O exemplo a seguir analisa uma lista de parágrafos que começam com
"<p>". Pelo bem da simplicidade, assumimos que o documento
está bem formatado, ou seja, que etiquetas '<p> são as
etiquetas apenas presentes e que esta marca é no início de cada
parágrafo.
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/<p>/ && !$first--; ) {
# Não é a primeira vez que vemos <p>.
# 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/^<p>//s;
# - Empurre à saída a etiqueta principal (não traduzido)
# e o resto do parágrafo (traduzido)
$self-> pushline( "<p>"
. $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;
}
}
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.
- 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:
- a.
- Lê todos os ficheiros PO especificados em
po_in_name
- b.
- Lê todos os documentos originais especificados em
file_in_name
- c.
- Analisa o documento
- d.
- Lê e aplica todas as adendas especificadas
- e.
- Escreve o documento traduzido para o file_out_name (se
dado)
- f.
- Escreve o ficheiro PO extraído 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 ($)
- 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).
- file_out_name ($)
- Nome do ficheiro onde devemos escrever o documento de
saída.
- 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 PO).
- po_in_name (@)
- Lista de nomes de ficheiros onde devemos ler os ficheiros
de entrada do PO, que contêm a tradução que
irá ser usada para traduzir o documento.
- po_out_name ($)
- Nome do ficheiro onde devemos escrever a saída do
ficheiro PO, que contém as cadeias extraídas 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. Opções
aceitas são (no hash passado como parâmetro):
- verbose ($)
- Define o nivel de detalhe.
- debug ($)
- Define a depuração.
- read($$)
- Adiciona dados de outro documento de entrada ao final do
vetor "@{$self->{TT}{doc_in}}" 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.
Esse vetor "@{$self->{TT}{doc_in}}" detém 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
localização dele e chamada
como "referência" ("linenum" starts with 1)..
Por favor, note que ele não analisa nada. Deve usar a
função parse() quando está 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 são fornecidos por:
* "$self->docheader()" a deter o texto de cabeçalho
para o plugin e
* "@{$self->{TT}{doc_out}}" a deter cada linha do principal
texto traduzido no vetor.
- readpo($)
- Adicionar o conteúdo dum ficheiro (que o nome
é passado como argumento) para o actual PO de entrada. O
conteúdo antigo não é descartado.
- writepo($)
- Gravar o ficheiro PO extraído ao nome do ficheiro
dado.
- 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 PO,
enquanto msgfmt relata o estado do ficheiro. Ele é um envolvido
para função Locale::Po4a::Po::stats_get aplicada ao ficheiro
de entrada PO. Exemplo de uso:
[utilização normal do documento po4a ...]
($percent,$hit,$queries) = $document->stats();
print "Encontramos traduções para $percent\% ($hit from $queries) de cadeias.\n";
- addendum($)
- Por favor, consulte po4a(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 ;)
Esta função retorna um inteiro não nulo em caso de
erro.
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.
* 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.
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.
- shiftline()
- Esta função retorna a primeira linha a ser
analisada e a referência dele correspondente (empacotada como um
vetor) do vetor "@{$self->{TT}{doc_in}}" e descarta estes 2
primeiros itens do vetor. Aqui, a referência é fornecida por
uma cadeia "$filename:$linenum".
- unshiftline($$)
- Executa unshift a última linha "shiftada"
do documento de entrada e a referência dele correspondente de volta
ao cabeçalho 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.
Uma função é fornecida para lidar com o texto que deve ser
traduzido.
- translate($$$)
- Argumentos obrigatórios:
- -
- Uma cadeia para traduzir
- -
- A referência desta cadeia (ou seja, em
posição de ficheiro de entrada)
- -
- O tipo desta cadeia (ou seja, a descrição
textual do papel estrutural dele; usado em
Locale::Po4a::Po::gettextization(); ver também
po4a(7), secção Gettextization: como é que
funciona?)
Esta função também 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
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.
- wrapcol
- a coluna em que devemos envolver
(predefinição: 76).
- comment
- um comentário adicional para a entrada.
Acões:
- -
- Coloca a cadeia de referência e tipo em po_out.
- -
- Retorna a tradução 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 às
traduções.
- verbose()
- Retorna se a opção 'verbose' foi aprovada
durante a criação do TransTractor.
- debug()
- Retorna se a opção de depuração
foi aprovada durante a criação doTransTractor.
- 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 process() ou detetados a partir do
documento.
- 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).
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 PO de entrada e, se a entrada de PO tem o "charset"
predefinido, irá retornar um conjunto de carácteres do
documento de entrada, de modo a que nenhuma codificação
é realizada.
- 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 ( translate()
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.
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.
Para resolver este problema, as únicas mudanças na interface
necessárias são:
- -
- obter um 'hash' como po_in_name (uma lista por idioma)
- -
- adicionar um argumento para traduzir para indicar a
língua apontada
- -
- fazer uma função pushline_all, que deveria
fazer pushline do conteúdo delepara todos idiomas, a usar uma
sintaxe tipo mapa:
$self->pushline_all({ "Description[".$langcode."]=".
$self->translate($line,$ref,$langcode)
});
Vai ver se é suficiente ;)
Denis Barbier <[email protected]>
Martin Quinson (mquinson#debian.org)
Jordi Vilalta <[email protected]>