Provided by: po4a_0.55-1_all bug

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>