Provided by: po4a_0.47-2_all 
NOME
Locale::Po4a::TransTractor - extrator de tradução genérico.
DESCRIÇÃO
A missão do projeto po4a (em inglês, PO for anything) é facilitar as traduções (e o mais
interessante, a manutenção de traduções) usando ferramentas de gettext em áreas onde elas
não eram esperadas, como documentação.
Essa classe é o ancestral de todo analisador po4a usado para analisar um documento, para
pesquisar strings traduzíveis, para extraí-las para um arquivo PO e para substitui-las por
suas traduções no documento de saída.
Mais formalmente, ele leva os seguintes argumentos como entrada:
- um documento para traduzir;
- um arquivo PO contendo as traduções para usar.
Como saída, ele produz:
- outro arquivo PO, resultando na extração de strings traduzíveis do documento de entrada;
- um documento traduzido, com a mesma estrutura daquela na entrada, mas com todas as
strings traduzíveis substituídas com as traduções encontradas no arquivo PO fornecido na
entrada.
Aqui está uma representação gráfica disso:
Doc. de entrada -\ /---> Doc. de saída
\ / (traduzido)
+---> função parse() -----+
/ \
PO de entrada ---/ \---> PO de saída
(extraído)
FUNÇÕES QUE SEU ANALISADOR DEVERIA SOBRESCREVER
parse()
É aqui onde todo trabalho acontece: o analisador de documentos de entrada, a geração
de saída e a extração das strings traduzíveis. Isso é bem simples usando as funções
fornecidas apresentadas na seção FUNÇÕES INTERNAS abaixo. Veja também a SINOPSE, que
apresenta um exemplo.
Essa função é chamada pela função process() abaixo, mas se você escolher usar a função
new() e adicionar o conteúdo manualmente a seu documento, você terá que chamar essa
função você mesmo.
docheader()
Essa função retorna o cabeçalho que nós deveríamos adicionar ao documento produzido,
coloca apropriadamente entre aspas para ser um comentário no idioma alvo. Veja a seção
Educando desenvolvedores sobre tradução, do po4a(7), para o que isso é bom.
SINOPSE
O exemplo a seguir analisa uma linha de parágrafos começando com "<p>". Em nome da
simplicidade, nós presumimos que o documento está bem formatado, ou seja, que as marcações
"<p>" são as únicas marcações apresentadas e que essa marcação está exatamente no começo
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>.
# Colocar novamnete a linha atual na entrada,
# e colocar o parágrafo compilado na saída
$self->unshiftline($line,$lref);
# Agora que o documento está formado, traduza-o:
# - Remove a marcação no começo
$paragraph =~ s/^<p>//s;
# - envia para a saída a marcação no começo (não
# traduzida) e o resto do parágrafo (traduzido)
$self->pushline( "<p>"
. $document->translate($paragraph,$pararef)
);
next PARAGRAPH;
} else {
# Anexa ao parágrafo
$paragraph .= $line;
$pararef = $lref unless(length($pararef));
}
# Reinicia o loop
($line,$lref)=$self->shiftline();
}
# Não conseguiu uma linha definida? Termina com o
# arquivo de entrada.
return;
}
}
Uma vez que você tenha implementada a função de análise, você pode usar sua classe de
documento, usando a interface pública apresentada na seção seguinte.
INTERFACE PÚBLICA para scripts usando seu analisador
Construtor
process(%)
Essa função pode fazer tudo que você precisa fazer com um documento po4a em uma
chamada. Seus argumentos devem ser empacotados como um hash. AÇÕES:
a. Lê todos os arquivos 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 todos os adendos especificados
e. Escreve o documento traduzido para file_out_name (se fornecido)
f. Escreve o arquivo PO extraído para po_out_name (se fornecido)
ARGUMENTOS, além dos aceitos por new() (com o tipo esperado):
file_in_name (@)
Lista de nomes de arquivos nos quais nós deveríamos ler o documento de entrada.
file_in_charset ($)
Conjunto de caracteres usado no documento de entrada (se esse não for
especificado, será tentado a detecção do documento de entrada).
file_out_name ($)
Nome de arquivo no qual nós deveríamos escrever o documento de saída.
file_out_charset ($)
Conjunto de caracteres usado no documento de saída (se esse não for especificado,
será usado o conjunto de caracteres do arquivo PO).
po_in_name (@)
Lista de nomes de arquivos dos quais nós deveríamos ler os arquivos PO de entrada,
contendo a tradução que será usada para traduzir o documento.
po_out_name ($)
Nome de arquivo no qual nós deveríamos escrever o arquivo PO de saída, contendo as
strings extraídas do documento de entrada.
addendum (@)
Lista de nomes de arquivos nos quais nós deveríamos ler os adendos.
addendum_charset ($)
Conjunto de caracteres para o adendos.
new(%)
Cria um novo documento de po4a. Opções aceitas são (mas devem estar em um hash):
verbose ($)
Define o detalhamento.
debug ($)
Define a depuração.
Manipulação de arquivos de documento
read($)
Adiciona outro documento de entrada ao final do existente. O argumento é o nome de
arquivo para ler.
Por favor note que ele analisa nada. Você deveria usa a função parse() quando você
acabar de empacotar os arquivos de entrada no documento.
write($)
Escreve o documento traduzido no nome de arquivo fornecido.
Manipulação de arquivos PO
readpo($)
Adiciona o conteúdo de um arquivo, cujo nome é passado como argumento, ao PO de
entrada existente. O conteúdo antigo é descartado.
writepo($)
Escrever o arquivo PO extraído para o nome de arquivo fornecido.
stats()
Retorna algumas estatísticas sobre a tradução realizada até o mesmo. Por favor, note
que não são as mesmas estatísticas mostradas pelo "msgfmt --statistic". Aqui, são as
estatísticas sobre uso recente do arquivo PO, enquanto o msgfmt relata o status do
arquivo. Ele é um wrapper da função Locale::Po4a::Po::stats_get aplicada ao arquivo PO
de entrada. Exemplo de uso:
[uso normal de um documento po4a...]
($percent,$hit,$queries) = $document->stats();
print "Nós encontramos de $percent\% ($hit de $queries) das strings.\n";
Manipulando adendos
addendum($)
Por favor veja o po4a(7) para mais informações sobre o que são adendos e como
tradutores deveriam escrevê-los. Para aplicar um adendo ao documento traduzido,
simplesmente passe seu nome de arquivo para essa função e pronto ;)
Essa função retorna um inteiro não nulo quando há um erro.
FUNÇÕES INTERNAS usadas para escrever analisadores derivados
Obtendo a entrada, fornecendo a saída
Quatro funções são fornecidas para obter entrada e retornar saída. Elas são muito
similares a shift/unshift e push/pop. O primeiro par é sobre entrada, enquanto ao segundo
é sobre saída. Mnemônico: na entrada, você está interessada na primeira linha, que é o que
o shift fornece, e na saída você quer adicionar seu resultado ao final, como o push faz.
shiftline()
Essa função retorna a próxima linha do doc_in a ser analisada e sua referência
(empacotada como um vetor).
unshiftline($$)
Volta uma linha do documento de entrada e sua referência.
pushline($)
Envia uma nova linha para o doc_out.
popline()
Volta, do doc_out, a linha anteriormente enviada.
Marcando strings como traduzíveis
Uma função é fornecida para manipular o texto que deveria ser traduzido.
translate($$$)
Argumentos obrigatórios:
- Uma string para traduzir
- A referência dessa string (i.e. posição no arquivo de entrada)
- O tipo dessa string (i.e. a descrição textual de seu papel estrutural; usado em
Locale::Po4a::Po::gettextization(); veja também po4a(7), seção Gettextização: como
ela funciona?)
Essa função também 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 nós podemos considerar que espaços em brancos nas strings
não são importantes. Se sim, a função canoniza a string antes de procurar por uma
tradução ou de extrair, e dimensiona a tradução.
wrapcol
a coluna na qual nós deveríamos dimensionar (padrão: 76).
comment
um comentário extra para adicionar ao registro.
Ações:
- Envia a string, referência e tipo para po_out.
- Retorna a tradução 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 enviá-las
para po_out e antes de retornar as traduções.
Funções miscelânea
verbose()
Retorna se a opção de detalhamento foi passada durante a criação do TransTractor.
debug()
Retorna se a opção de depuração foi passada durante a criação do TransTractor.
detected_charset($)
Isso fala para o TransTractor que um novo conjunto de caracteres (o primeiro
argumento) foi detectado no documento de entrada. Ele normalmente pode ser lido do
cabeçalho do documento. Apenas o primeiro conjunto de caracteres restará, vindo com os
argumentos de process() ou detectado do documento.
get_out_charset()
Essa função vai retornar o conjunto de caracteres que deveria ser usado no documento
do entrada (normalmente útil para substituir o conjunto de caracteres detectado no
documento de entrada, onde ele foi encontrado).
Ele vai usar o conjunto de caracteres de saída especificado na linha de comando. Se
não tiver sido especificado, ele vai usar o conjunto de caracteres do PO de entrada, e
se o PO de entrada possuir o "CHARSET" padrão, ele vai retornar o conjunto de
caracteres do documento de entrada, de forma que nenhuma codificação é realizada.
recode_skipped_text($)
Essa função retorna o texto re-codificado passado como argumento, do conjunto de
caracteres do documento de entrada para o do documento de saída. Isso não é necessário
quando se está traduzindo uma string (o próprio translate() re-codifica tudo), mas é
necessário quando você ignora uma string do documento de entrada e você deseja que o
documento de saída seja consistente com a codificação global.
DIREÇÕES FUTURAS
Um problema do atual TransTractor é que ele não consegue manipular documento traduzido
contendo todos idiomas, como modelos de debconf, ou arquivos .desktop.
Para resolver esse problema, as únicas alterações necessárias na interface são:
- pegar um hash como po_in_name (uma lista por idioma)
- adicionar um argumento para traduzir para indicar o idioma alvo
- fazer uma função pushline_all, que deveria fazer pushline de seu conteúdo para todos
idiomas, usando uma sintaxe tipo mapa:
$self->pushline_all({ "Description[".$langcode."]=".
$self->translate($line,$ref,$langcode)
});
Veremos se isso é o suficiente ;)
AUTORES
Denis Barbier <barbier@linuxfr.org>
Martin Quinson (mquinson#debian.org)
Jordi Vilalta <jvprat@gmail.com>