Provided by: po4a_0.52-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($)
           Adicionar outro documento de entrada na extremidade do existente. O argumento é o nome
           do ficheiro para ler.

           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.

   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.

FUNÇÕES INTERNAS usadas para escrever analises derivadas

   Obtenção de entrada, fornecendo saída
       Quatro funções são fornecidas para obter o retorno da entrada e da saída. São muito
       semelhantes ao 'shift/unshift' e 'push/pop'. O primeiro par é  sobre a entrada, enquanto o
       segundo é sobre a saída. Mnemónico: na entrada, você está interessado em primeira linha,
       que o 'shift' dá e, na saída que deseja adicionar o seu resultado no final, como 'push'
       faz.

       shiftline()
           Esta função retorna a próxima linha do doc_in para ser analisada e suareferência
           (embalada como uma matriz).

       unshiftline($$)
           'Unshifts' uma linha do documento de entrada e a sua referência.

       pushline($)
           Empurrar uma nova linha para o doc_out

       popline()
           'Pop' a última linha empurrada do 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

       - fazer uma função pushline_all, o que seria 'pushline' e seu conteúdo para toda a
         linguagem, usando uma sintaxe mapa como:

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