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;

               #   - 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($)
    Add another input document data at the end of the existing array "@{$self->{TT}{doc_in}}". The argument is the filename to read.

    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".

    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.

    Please note $linenum starts with 1.

escrever($)
    Escreva o documento traduzido para o nome do ficheiro dado.

    This translated document data are provided by:
     * "$self->docheader()" holding the header text for the plugin, and
     * "@{$self->{TT}{doc_out}}" holding each line of the main translated text in the array.

  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.

INTERNAL FUNCTIONS used to write derivative parsers

  Obtenção de entrada, fornecendo saída
Four functions are provided to get input and return output. They are very similar to shift/unshift and push/pop of Perl.

 * Perl shift returns the first array item and drop it from the array.
 * Perl unshift prepends an item to the array as the first array item.
 * Perl pop returns the last array item and drop it from the array.
 * Perl push appends an item to the array as the last array item.

The first pair is about input, while the second is about output. Mnemonic: in input, you are interested in the first line, what shift gives, and in output you want to add your result at the end, like push does.

shiftline()
    This function returns the first line to be parsed and its corresponding reference (packed as an array) from the array "@{$self->{TT}{doc_in}}" and drop these first 2 array items. Here, the reference is provided by a string "$filename:$linenum".

unshiftline($$)
    Unshifts the last shifted line of the input document and its corresponding reference back to the head of "{$self->{TT}{doc_in}}".

pushline($)
    Push a new line to the end of "{$self->{TT}{doc_out}}".

popline()
    Pop the last pushed line from the end of "{$self->{TT}{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

-   make a pushline_all function, which would make pushline of its content for all languages, using a map-like syntax:

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