Provided by: po4a_0.52-1_all 
NOME
Locale::Po4a::TransTractor - genérico trans(lator ex)trator.
DESCRIÇÃO
O objetivo do projeto po4a (PO para tudo) é facilitar traduções (e mais interessante, a
manutenção das traduções) usando ferramentas gettext em áreas onde eles não eram esperados
como documentação.
Esta classe é o ancestral de todos os analisadores po4a usado para analisar um documento,
para pesquisar sequências traduzíveis, para extraí-las para um ficheiro PO e substitui-los
por sua tradução 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 sequências traduzíveis em documento de
entrada;
- um documento traduzido, com a mesma estrutura do que o de entrada, mas com todas as
sequências 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)
FUNÇÕES QUE O SEU ANALISADOR DEVERIA SUBSTITUIR
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 sequências traduzíveis. Isto é muito simples usando
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 pelo processo() função abaixo, mas se você escolher para usar a
nova() função e, para adicionar conteúdo manualmente para o 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.
SINOPSE
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--; ) {
# Not the first time we see <p>.
# Reput the current line in input,
# and put the built paragraph to output
$self->unshiftline($line,$lref);
# Agora que o documento é formado, traduza-o:
# - Remova a etiqueta líder
$paragraph =~ s/^<p>//s;
# - Empurre para a saída a etiqueta principal (não traduzido)
# e o resto do parágrafo (traduzido)
$self-> pushline( "<p>"
. $document->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, você pode usar a sua classe de documento,
usando a interface pública apresentada na próxima secção.
INTERFACE PÚBLICA para scripts usando o seu analisador
Construtor
process(%)
Esta função pode fazer tudo o que você precisa fazer com um documento po4a numa
invocação. Os seus argumentos 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
sequências 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(%)
Criar um documento po4a novo. Opções aceitas (mas está num 'hash'):
verbose ($)
Define o nivel de detalhe
debug ($)
Define a depuração
Manipulação de ficheiros de documentos
ler($)
Adicionar outro documento de entrada na extremidade do existente. O argumento é o nome
do ficheiro para ler.
Por favor, note que ele não analisa nada. Você deve usar a função parse() quando está
feito com o empacotamento de ficheiros de entrada no documento.
escrever($)
Escreva o documento traduzido para o nome do ficheiro dado.
Manipulando ficheiros PO
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 para o 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 sequências.\n";
is_po_uptodate()
Returns ($uptodate, $diagnostic) where $uptodate is whether the input po and the
output po match (if not, it means that the input po should be updated) and $diagnostic
is a string explaining why the po file is not uptodate, when this happens.
Manipulação da adenda
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 você está feito ;)
Esta função retorna um inteiro não nulo em caso de erro.
FUNÇÕES INTERNAS usadas para escrever analises derivadas
Obtenção de entrada, fornecendo saída
Quatro funções são fornecidas para obter o retorno da entrada e da saída. São muito
semelhantes ao 'shift/unshift' e 'push/pop'. O primeiro par é sobre a entrada, enquanto o
segundo é sobre a saída. Mnemónico: na entrada, você está interessado em primeira linha,
que o 'shift' dá e, na saída que deseja adicionar o seu resultado no final, como 'push'
faz.
shiftline()
Esta função retorna a próxima linha do doc_in para ser analisada e suareferência
(embalada como uma matriz).
unshiftline($$)
'Unshifts' uma linha do documento de entrada e a sua referência.
pushline($)
Empurrar uma nova linha para o doc_out
popline()
'Pop' a última linha empurrada do doc_out.
Sequências de marcação como traduzível
Uma função é fornecida para lidar com o texto que deve ser traduzido.
translate($$$)
Argumentos obrigatórios:
- Uma sequência para traduzir
- A referência desta sequência (ou seja, em posição de ficheiro de entrada)
- O tipo desta sequência (ou seja, a descrição textual do seu papel estrutural; 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 sequência
não são importantes. Se sim, a função canoniza a sequência antes de procurar a
tradução ou extraí-la, e envolve a tradução.
wrapcol
a coluna em que nos devemos envolver (padrão: 76)
comment
um comentário extra para a entrada.
Acões:
- Coloca a sequência de referência, e tipo em po_out.
- Retorna a tradução da sequência (como encontrada em po_in), de modo que o analisador
pode construir o doc_out.
- Lida com os conjuntos de carateres para recodificar as sequências antes de as enviar
para po_out e antes de voltar às traduções.
Funções diversas
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á, vindo a
partir dos argumentos de process() ou detetados a partir do documento.
get_out_charset()
Esta função irá retornar o conjunto de caracteres, que deviam ser usados na saída
(em geral, útil para substituir os conjuntos de carateresdetetados à 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 padrão "charset", irá retornar conjunto de carateres 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 carateres do documento para os do documento de saída. Isto não é necessário quando
traduzir uma sequência (translate() recodifica tudo em si), mas é para quando saltar
uma sequência do documento de entrada e quer que o documento de saída seja consistente
com a codificação global.
DIREÇÕES FUTURAS
Uma falha do TransTractor atual é que ele não pode tratar de documentos traduzidos
contendo 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, o que seria 'pushline' e seu conteúdo para toda a
linguagem, usando uma sintaxe mapa como:
$self->pushline_all({ "Description[".$langcode."]=".
$self->translate($line,$ref,$langcode)
});
Vai ver se é suficiente ;)
AUTORES
Denis Barbier <barbier@linuxfr.org>
Martin Quinson (mquinson#debian.org)
Jordi Vilalta <jvprat@gmail.com>