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

               #   - push to output the leading tag (untranslated) and the
               #     rest of the paragraph (translated)
               $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, 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

read($$)
Add another input document data at the end of the existing array "@{$self->{TT}{doc_in}}". The argument is the filename to read. If a second argument is provided, it is the filename to use in the references.

This array "@{$self->{TT}{doc_in}}" holds this input document data as an array of strings with alternating meanings. * The string $textline holding each line of the input text data. * The string "$filename:$linenum" holding its location and called as "reference" ("linenum" starts with 1).

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.

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.

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()
Retorna ($uptodate, $diagnostic), sendo que $uptodate é se o po de entrada e o po de saída coincidem (se não, significa que o po de entrada deve ser atualizado) e $diagnostic é uma string explicando por que o ficheiro po não está atualizado, quando isso acontece.

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 analisadores derivados

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

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

Vai ver se é suficiente ;)

AUTORES

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