LOCALE::PO4A::TRANSTRACTOR.3PM(1) User Contributed Perl Documentation LOCALE::PO4A::TRANSTRACTOR.3PM(1)

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)

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.

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.

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.
Charset used in the input document (if it isn't specified, use UTF-8).
Nome do ficheiro onde devemos escrever o documento de saída.
Charset used in the output document (if it isn't specified, use UTF-8).
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.
The column at which we should wrap text in output document (default: 76).

The negative value means not to wrap lines at all.

Also it accepts next options for underlying Po-files: porefs, copyright-holder, msgid-bugs-address, package-name, package-version, wrap-po.

Manipulação de ficheiros de documentos

Add another input document data at the end of the existing array "@{$self->{TT}{doc_in}}".

This function takes two mandatory arguments and an optional one.
* The filename to read on disk;
* The name to use as filename when building the reference in the PO file;
* The charset to use to read that file (UTF-8 by default)

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.

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

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.

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.
the column at which we should wrap (default: the value of wrapcol specified during creation of the TransTractor or 76).

The negative value will be substracted from the default.

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.

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.
This function return the charset that was provided as master 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.

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 <barbier@linuxfr.org>
Martin Quinson (mquinson#debian.org)
Jordi Vilalta <jvprat@gmail.com>
2024-06-26 perl v5.38.2