Scroll to navigation

Locale::Po4a::TransTractor(3pm) Ferramentas Po4a Locale::Po4a::TransTractor(3pm)

NOME

Locale::Po4a::TransTractor - genérico trans(lator ex)trator.

DESCRIÇÃO

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)

FUNÇÕES QUE O SEU ANALISADOR DEVERIA SUBSTITUIR

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.

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--; ) {
               # 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.

INTERFACE PÚBLICA para scripts a usar o seu analisador

Construtor

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:
Lê todos os ficheiros PO especificados em po_in_name
Lê todos os documentos originais especificados em file_in_name
Analisa o documento
Lê e aplica todas as adendas especificadas
Escreve o documento traduzido para o file_out_name (se dado)
Escreve o ficheiro PO extraído para po_out_name (se dado)

ARGUMENTOS, ao lado dos aceites por new() (com o tipo esperado):

Lista de nomes de ficheiros onde devemos ler o documento de entrada.
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).
Nome do ficheiro onde devemos escrever o documento de saída.
Conjunto de carateres utilizado no documento de saída (se não for especificado, será usado o conjunto de carateres do ficheiro PO).
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.
Nome do ficheiro onde devemos escrever a saída do ficheiro PO, que contém as cadeias extraídas do documento de entrada.
Lista de nomes de ficheiros que devemos ler a adenda de.
Conjunto de carateres para a adenda.
Cria um novo documento de po4a. Opções aceitas são (no hash passado como parâmetro):
Define o nivel de detalhe.
Define a depuração.
Boolean indicating whether we should deduplicate msgids. Passed to Po.pm as is. See Po.pm documentation for more info.

Manipulação de ficheiros de documentos

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.

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.

Manipulando ficheiros PO

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.
Gravar o ficheiro PO extraído ao nome do ficheiro dado.
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";
    

Manipulação da adenda

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.

FUNÇÕES INTERNAS usadas para escrever analisadores derivados

Obtenção de entrada, a fornecer 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, 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.

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".
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}}".
Envia uma nova linha ao fim de "{$self->{TT}{doc_out}}".
Volta, do fim de "{$self->{TT}{doc_out}}", a linha anteriormente enviada.

Marcar cadeias como traduzíveis

Uma função é fornecida para lidar com o texto que deve ser traduzido.

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);
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.
a coluna em que devemos envolver (predefinição: 76).
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.

Funções diversas

Retorna se a opção 'verbose' foi aprovada durante a criação do TransTractor.
Retorna se a opção de depuração foi aprovada durante a criação doTransTractor.
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.
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.

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.

DIREÇÕES FUTURAS

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 ;)

AUTORES

 Denis Barbier <barbier@linuxfr.org>
 Martin Quinson (mquinson#debian.org)
 Jordi Vilalta <jvprat@gmail.com>
2022-07-15 Ferramentas Po4a