Locale::Po4a::TransTractor(3pm)

Ferramentas do Po4a

Locale::Po4a::TransTractor(3pm)

NOME¶

Locale::Po4a::TransTractor - extrator de tradução genérico.

DESCRIÇÃO¶

O objetivo do projeto po4a (PO for anything, ou PO para qualquer coisa) é facilitar traduções (e o mais interessante, a manutenção das traduções) usando as ferramentas do gettext em áreas em que não se esperava, 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>"
                             . $self->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 (no hash passado como parâmetro):

verbose ($): Define o detalhamento.
debug ($): Define a depuração.

Manipulação de arquivos de documento¶

read($$)

Adiciona dados de outro documento de entrada ao final do vetor "@{$self->{TT}{doc_in}}" existente. O argumento é o nome de arquivo para ler. Se um segundo argumento é fornecido, ele é o nome de arquivo para usar em referências.

Esse vetor "@{$self->{TT}{doc_in}}" detém 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 localização e chamada
como "referência" ("linenum" inicia com 1).

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.

Os dados desse documento traduzido são fornecidos por:
* "$self->docheader()" detendo o texto de cabeçalho para o plugin, e
* "@{$self->{TT}{doc_out}}" detendo cada linha do principal texto traduzido no vetor.

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 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, 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(): Esta função retorna a primeira linha a ser analisada e a sua referência 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 string "$filename:$linenum".
unshiftline($$): Executa unshift a última linha "shiftada" do documento de entrada e sua referência correspondente de volta para o cabeçalho 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 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>

2023-01-03

Ferramentas do Po4a

Source file:	Locale::Po4a::TransTractor.3pm.pt_BR.gz (from po4a 0.69-1)
Source last updated:	2023-01-03T14:13:10Z
Converted to HTML:	2023-06-11T00:14:24Z