
        *****************************************************
        *           GENERATED FILE, DO NOT EDIT             *
        * THIS IS NO SOURCE FILE, BUT RESULT OF COMPILATION *
        *****************************************************

This file was generated by po4a(7). Do not store it (in VCS, for example),
but store the PO file used as source file by po4a-translate.

In fact, consider this as a binary, and the PO file as a regular .c file:
If the PO get lost, keeping this translation up-to-date will be harder.

=encoding UTF-8

=head1 NOME

Locale::Po4a::TransTractor - trans(lator ex)trator tradutor extrator
genérico.

=head1 DESCRIÇÃO

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

Mais formalmente, recebe os seguintes argumentos como entrada:

=over 2

=item -

um documento para traduzir;

=item -

Um ficheiro PO que contém as traduções para usar.

=back

Como saída, produz:

=over 2

=item -

outro ficheiro PO, resultante da extração de cadeias traduzíveis no
documento de entrada;

=item -

um documento traduzido, com a mesma estrutura que o da entrada, mas com
todas as cadeias traduzíveis substituídas com as traduções encontradas no
ficheiro PO fornecido na entrada.

=back

Aqui está uma representação gráfica disto:

   Documento de entrada --\                     / ---> documento de saída
                           \                   /          (traduzido)
                           +-> função analisar() ---+
                           /                         \
   Entrada PO ------------/                           \---> Saída PO
                                                            (extraído)

=head1 FUNÇÕES QUE O SEU ANALISADOR DEVE SOBREPOR

=over 4

=item 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 cadeias traduzíveis. Isto é
muito simples de usar as funções disponíveis apresentadas na secção abaixo
B<FUNÇÕES INTERNAS>. Veja também o B<RESUMO>, o qual apresenta um exemplo.

Esta função é invocada pela função process() abaixo, mas se escolher usar a
função new() e, para adicionar conteúdo manualmente ao documento, terá que
invocar esta função você mesmo.

=item 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 B<Educating developers about translations>, de
L<po4a(7)|po4a.7>, que é para o bem de todos.

=back

=head1 RESUMO

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

               # Now that the document is formed, translate it:
               #   - Remove the leading tag
               $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)
                               );

               next PARAGRAPH;
           } else {
               # Append to the paragraph
               $paragraph .= $line;
               $pararef = $lref unless(length($pararef));
           }

           # Reinit the loop
           ($line,$lref)=$self->shiftline();
       }
       # Did not get a defined line? End of input file.
       return;
   }
 }

Depois de implementar a função de análise, pode usar a sua classe de
documento, usando a interface pública apresentada na próxima secção.

=head1 INTERFACE PÚBLICA para scripts que usam o seu analisador

=head2 Construtor

=over 4

=item process(%)

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:

=over 3

=item a.

Lê todos os ficheiros PO especificados em po_in_name

=item b.

Lê todos os documentos originais especificados em file_in_name

=item c.

Analisa o documento

=item d.

Lê e aplica todas as adendas especificadas

=item e.

Escreve o documento traduzido para o nome_ficheiro_saída (se dado)

=item f.

Escreve o ficheiro PO extraído para nome_po_saída (se dado)

=back

ARGUMENTOS, além daqueles aceites pelo new() (com o tipo esperado):

=over 4

=item file_in_name (@)

Lista de nomes de ficheiros onde devemos ler o documento de entrada.

=item file_in_charset ($)

Conjunto de caracteres usado no documento de entrada (se não for
especificado, usa UTF-8).

=item file_out_name ($)

Nome do ficheiro onde devemos escrever o documento de saída.

=item file_out_charset ($)

Conjunto de caracteres usado no documento de saída (se não for especificado,
usa UTF-8).

=item 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.

=item po_out_name ($)

Nome do ficheiro onde devemos escrever a saída do ficheiro PO, que contém as
cadeias extraídas do documento de entrada.

=item addendum (@)

Lista de nomes de ficheiros de onde devemos ler a adenda.

=item addendum_charset ($)

Conjunto de caracteres para a adenda.

=back

=item new(%)

Cria um novo documento de po4a. Opções aceites (no hash passado como
parâmetro):

=over 4

=item verbose ($)

Define o nível de detalhe.

=item debug ($)

Define a depuração.

=item wrapcol ($)

A coluna na qual devemos fazer a quebra de texto no documento de saída
(predefinição: 76).

O valor negativo significa não quebrar as linhas.

=back

Também aceita as próximas opções para ficheiros PO subjacentes: B<porefs>,
B<copyright-holder>, B<msgid-bugs-address>, B<package-name>,
B<package-version>, B<wrap-po>.

=back

=head2 Manipulando ficheiros de documentos

=over 4

=item read($$$)

Adiciona outros dados do documento de entrada no final da array existente
C<< @{$self->{TT}{doc_in}} >>.

Esta função recebe dois argumentos obrigatórios e um opcional.
 * O nome do ficheiro a ser lido no disco;
 * O nome a ser usado como nome do ficheiro ao construir a referência no ficheiro PO;
 * O conjunto de caracteres a ser usado para ler esse ficheiro (UTF-8 por predefinição)

Esta matriz C<< @{$self->{TT}{doc_in}} >> detém os dados desse documento de
entrada como uma matriz de cadeias com significados alternativos.
 * A cadeia C<$textline> que detém cada linha de dados de texto de entrada.
 * A cadeia C<< $filename:$linenum >> que detém a sua localização e chamada
   como "referência" (C<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.

=item escrever($)

Escreva o documento traduzido no nome do ficheiro dado.

Os dados desse documento traduzido são fornecidos por:
 * C<< $self->docheader() >> a deter o texto de cabeçalho para o plugin e
 * C<< @{$self->{TT}{doc_out}} >> a deter cada linha do principal texto traduzido na matriz.

=back

=head2 Manipulando ficheiros PO

=over 4

=item readpo($)

Adiciona o conteúdo dum ficheiro (que o nome é passado como argumento) para
o actual PO de entrada. O conteúdo antigo não é descartado.

=item writepo($)

Gravar o ficheiro PO extraído no nome do ficheiro dado.

=item stats()

Retorna algumas estatísticas sobre a tradução feita até agora. Note que não
é a mesma estatística que aquela escrita 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:

    [uso normal do documento po4a...]

    ($percent,$hit,$queries) = $document->stats();
    print "Encontramos traduções para $percent\%  ($hit from $queries) de cadeias.\n";

=back

=head2 Manipulando a adenda

=over 4

=item addendum($)

Por favor, consulte L<po4a(7)|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.

=back

=head1 FUNÇÕES INTERNAS usadas para escrever analisadores derivados

=head2 Obter a entrada, fornecer a 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 da matriz e solta-o da matriz.
* Perl unshift preenche um item da matriz como o primeiro item da matriz.
* Perl pop retorna o último item da matriz e solta-o da matriz.
* Perl push acrescenta um item da matriz como o último item da matriz.

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.

=over 4

=item shiftline()

Esta função retorna a primeira linha a ser analisada e a referência dele
correspondente (empacotada como uma matriz) da matriz C<<
@{$self->{TT}{doc_in}} >> e descarta estes 2 primeiros itens da
matriz. Aqui, a referência é fornecida por uma cadeia C<< $filename:$linenum
>>.

=item unshiftline($$)

Desloca a última linha deslocada do documento de entrada e a referência dele
correspondente de volta ao cabeçalho de C<< {$self->{TT}{doc_in}} >>.

=item pushline($)

Força uma nova linha no fim de C<< {$self->{TT}{doc_out}} >>.

=item popline()

Estoira a última linha forçada do final de C<< {$self->{TT}{doc_out}} >>.

=back

=head2 Marcando cadeias como traduzíveis

Uma função é fornecida para lidar com o texto que deve ser traduzido.

=over 4

=item translate($$$)

Argumentos obrigatórios:

=over 2

=item -

Uma cadeia para traduzir

=item -

A referência desta cadeia (ou seja, posição no ficheiro de entrada)

=item -

O tipo desta cadeia (ou seja, a descrição textual do papel estrutural dele;
usado em Locale::Po4a::Po::gettextization(); ver também L<po4a(7)|po4a.7>,
secção B<Gettextization: how does it work?>)

=back

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

=over

=item B<wrap>

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.

=item B<wrapcol>

a coluna na qual devemos fazer a quebra da linha (predefinição: o valor de
B<wrapcol> especificado durante a criação do TransTractor ou 76).

O valor negativo será subtraído da predefinição.

=item B<comment>

um comentário adicional para a entrada.

=back

Ações:

=over 2

=item -

Coloca a cadeia de referência e tipo em po_out.

=item -

Retorna a tradução da cadeia (como encontrada em po_in), de modo que o
analisador pode construir o doc_out.

=item -

Lida com os conjuntos de caracteres para recodificar as cadeias antes de as
enviar para po_out e antes de voltar às traduções.

=back

=back

=head2 Funções diversas

=over 4

=item verbose()

Retorna se a opção 'verbose' foi passada durante a criação do TransTractor.

=item debug()

Retorna se a opção de depuração foi passada durante a criação
doTransTractor.

=item get_in_charset()

Esta função retorna o charset que foi fornecido como o conjunto de
caracteres mestre

=item get_out_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).

Vai usar o conjunto de caracteres de saída especificado na linha de
comando. Se não fosse especificado, seria usado o conjunto de caracteres do
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.

=back

=head1 DIREÇÕES FUTURAS

Uma falha do TransTractor atual é que ele não pode tratar de documentos
traduzidos que contém todos os idiomas, como modelos debconf, ou ficheiros
.desktop.

Para resolver este problema, as únicas mudanças na interface necessárias
são:

=over 2

=item -

obter um 'hash' como po_in_name (uma lista por idioma)

=item -

adicionar um argumento para traduzir para indicar a língua apontada

=item -

fazer uma função pushline_all, que deveria fazer pushline do conteúdo dele
para todos idiomas, a usar uma sintaxe tipo mapa:

    $self->pushline_all({ "Description[".$langcode."]=".
                          $self->translate($line,$ref,$langcode)
                        });

=back

Vamos ver se é suficiente ;)

=head1 AUTORES

 Denis Barbier <barbier@linuxfr.org>
 Martin Quinson (mquinson#debian.org)
 Jordi Vilalta <jvprat@gmail.com>
