
        *****************************************************
        *           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 - extrator de tradução genérico.

=head1 DESCRIÇÃO

O objetivo do projeto po4a (PO for anything, ou PO para qualquer coisa) é
facilitar traduções (e o mais interessante, a manutenção das traduções)
usando as ferramentas do gettext em áreas em que não se esperava, como
documentação.

Essa classe é o ancestral de todo analisador po4a usado para analisar um
documento, para pesquisar strings traduzíveis, para extraí-las para um
arquivo PO e para substitui-las por suas traduções no documento de saída.

Mais formalmente, ele leva os seguintes argumentos como entrada:

=over 2

=item -

um documento para traduzir;

=item -

um arquivo PO contendo as traduções para usar.

=back

Como saída, ele produz:

=over 2

=item -

outro arquivo PO, resultando na extração de strings traduzíveis do documento
de entrada;

=item -

um documento traduzido, com a mesma estrutura daquela na entrada, mas com
todas as strings traduzíveis substituídas com as traduções encontradas no
arquivo PO fornecido na entrada.

=back

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

   Doc. de entrada -\                             /---> Doc. de saída
                     \                           /       (traduzido)
                      +---> função parse() -----+
                     /                           \
   PO de entrada ---/                             \---> PO de saída
                                                         (extraído)

=head1 FUNÇÕES QUE SEU ANALISADOR DEVERIA SOBRESCREVER

=over 4

=item parse()

É aqui onde todo trabalho acontece: o analisador de documentos de entrada, a
geração de saída e a extração das strings traduzíveis. Isso é bem simples
usando as funções fornecidas apresentadas na seção B<FUNÇÕES INTERNAS>
abaixo. Veja também a B<SINOPSE>, que apresenta um exemplo.

Essa função é chamada pela função process() abaixo, mas se você escolher
usar a função new() e adicionar o conteúdo manualmente a seu documento, você
terá que chamar essa função você mesmo.

=item docheader()

Essa função retorna o cabeçalho que nós deveríamos adicionar ao documento
produzido, coloca apropriadamente entre aspas para ser um comentário no
idioma alvo. Veja a seção B<Educando desenvolvedores sobre tradução>, do
L<po4a(7)|po4a.7>, para o que isso é bom.

=back

=head1 SINOPSE

O exemplo a seguir analisa uma linha de parágrafos começando com "<p>". Em
nome da simplicidade, nós presumimos que o documento está bem formatado, ou
seja, que as marcações "<p>" são as únicas marcações apresentadas e que essa
marcação está exatamente no começo 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--; ) {
               # Não é primeira vez que vemos <p>.
               # Coloca novamente a linha atual na entrada,
               # e coloca o parágrafo na saída
               $self->unshiftline($line,$lref);

               # Agora que o documento é formatado, traduza-o:
               #   - Remove a tag de abertura
               $paragraph =~ s/^<p>//s;

               #   - Envia a saída para a tag de abertura (não traduzida)
               #     e o resto do parágrafo (traduzido)
               $self->pushline(  "<p>"
                               . $self->translate($paragraph,$pararef)
                               );

               next PARAGRAPH;
           } else {
               # Adiciona o parágrafo ao final
               $paragraph .= $line;
               $pararef = $lref unless(length($pararef));
           }

           # Reinicia o loop
           ($line,$lref)=$self->shiftline();
       }
       # Não obteve uma linha definida? Fim do arquivo de entrada.
       return;
   }
 }

Uma vez que você tenha implementada a função de análise, você pode usar sua
classe de documento, usando a interface pública apresentada na seção
seguinte.

=head1 INTERFACE PÚBLICA para scripts usando seu analisador

=head2 Construtor

=over 4

=item process(%)

Essa função pode fazer tudo que você precisa fazer com um documento po4a em
uma chamada. Seus argumentos devem ser empacotados como um hash. AÇÕES:

=over 3

=item a.

Lê todos os arquivos 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 todos os adendos especificados

=item e.

Escreve o documento traduzido para file_out_name (se fornecido)

=item f.

Escreve o arquivo PO extraído para po_out_name (se fornecido)

=back

ARGUMENTOS, além dos aceitos por new() (com o tipo esperado):

=over 4

=item file_in_name (@)

Lista de nomes de arquivos nos quais nós deveríamos ler o documento de
entrada.

=item file_in_charset ($)

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

=item file_out_name ($)

Nome de arquivo no qual nós deveríamos escrever o documento de saída.

=item file_out_charset ($)

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

=item po_in_name (@)

Lista de nomes de arquivos dos quais nós deveríamos ler os arquivos PO de
entrada, contendo a tradução que será usada para traduzir o documento.

=item po_out_name ($)

Nome de arquivo no qual nós deveríamos escrever o arquivo PO de saída,
contendo as strings extraídas do documento de entrada.

=item addendum (@)

Lista de nomes de arquivos nos quais nós deveríamos ler os adendos.

=item addendum_charset ($)

Conjunto de caracteres para o adendos.

=back

=item new(%)

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

=over 4

=item verbose ($)

Define o detalhamento.

=item debug ($)

Define a depuração.

=item wrapcol ($)

A coluna na qual nós devemos fazer a quebra de texto no documento de saída
(padrão: 76).

O valor negativo significa não quebrar as linhas.

=back

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

=back

=head2 Manipulação de arquivos de documento

=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 arquivo a ser lido no disco;
 * O nome a ser usado como nome do arquivo ao construir a referência no arquivo PO;
 * O conjunto de caracteres a ser usado para ler esse arquivo (UTF-8 por padrão)

Esse vetor C<< @{$self->{TT}{doc_in}} >> detém os dados desse documento de
entrada como um vetor e strings com significados alternativos.
 * A string C<$textline> detendo cada linha de dados de texto de entrada.
 * A string C<< $filename:$linenum >> detendo sua localização e chamada
   como "referência" (C<linenum> inicia com 1).

Por favor note que ele analisa nada. Você deveria usa a função parse()
quando você acabar de empacotar os arquivos de entrada no documento.

=item write($)

Escreve o documento traduzido no nome de arquivo fornecido.

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

=back

=head2 Manipulação de arquivos PO

=over 4

=item readpo($)

Adiciona o conteúdo de um arquivo, cujo nome é passado como argumento, ao PO
de entrada existente. O conteúdo antigo é descartado.

=item writepo($)

Escrever o arquivo PO extraído para o nome de arquivo fornecido.

=item stats()

Retorna algumas estatísticas sobre a tradução realizada até o mesmo. Por
favor, note que não são as mesmas estatísticas mostradas pelo "msgfmt
--statistic". Aqui, são as estatísticas sobre uso recente do arquivo PO,
enquanto o msgfmt relata o status do arquivo. Ele é um wrapper da função
Locale::Po4a::Po::stats_get aplicada ao arquivo PO de entrada. Exemplo de
uso:

    [uso normal do documento po4a...]

    ($percent,$hit,$queries) = $document->stats();
    print "Nós encontramos de $percent\%  ($hit de $queries) das strings.\n";

=back

=head2 Manipulando adendos

=over 4

=item addendum($)

Por favor veja o L<po4a(7)|po4a.7> para mais informações sobre o que são
adendos e como tradutores deveriam escrevê-los. Para aplicar um adendo ao
documento traduzido, simplesmente passe seu nome de arquivo para essa função
e pronto ;)

Essa função retorna um inteiro não nulo quando há um erro.

=back

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

=head2 Obtendo a entrada, fornecendo 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 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.

=over 4

=item shiftline()

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

=item unshiftline($$)

Executa unshift a última linha "shiftada" do documento de entrada e sua
referência correspondente de volta para o cabeçalho de C<<
{$self->{TT}{doc_in}} >>.

=item pushline($)

Envia uma nova linha para o fim de C<< {$self->{TT}{doc_out}} >>.

=item popline()

Volta, do fim de C<< {$self->{TT}{doc_out}} >>, a linha anteriormente
enviada.

=back

=head2 Marcando strings como traduzíveis

Uma função é fornecida para manipular o texto que deveria ser traduzido.

=over 4

=item translate($$$)

Argumentos obrigatórios:

=over 2

=item -

Uma string para traduzir

=item -

A referência dessa string (i.e. posição no arquivo de entrada)

=item -

O tipo dessa string (i.e. a descrição textual de seu papel estrutural; usado
em Locale::Po4a::Po::gettextization(); veja também L<po4a(7)|po4a.7>, seção
B<Gettextização: como ela funciona?>)

=back

Essa função também pode levar alguns argumentos extras. Eles devem ser
organizados como um hash. Por exemplo:

  $self->translate("string","ref","type",
                   'wrap' => 1);

=over

=item B<wrap>

booleano indicando se nós podemos considerar que espaços em brancos nas
strings não são importantes. Se sim, a função canoniza a string antes de
procurar por uma tradução ou de extrair, e dimensiona a tradução.

=item B<wrapcol>

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

O valor negativo será subtraído do padrão.

=item B<comment>

um comentário extra para adicionar ao registro.

=back

Ações:

=over 2

=item -

Envia a string, referência e tipo para po_out.

=item -

Retorna a tradução da string (como encontrado em po_in) de forma que o
analisador pode compilar o doc_out.

=item -

Manipula os conjuntos de caracteres para re-codificar as strings antes de
enviá-las para po_out e antes de retornar as traduções.

=back

=back

=head2 Funções miscelânea

=over 4

=item verbose()

Retorna se a opção de detalhamento foi passada durante a criação do
TransTractor.

=item debug()

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

=item get_in_charset()

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

=item get_out_charset()

Essa função vai retornar o conjunto de caracteres que deveria ser usado no
documento do entrada (normalmente útil para substituir o conjunto de
caracteres detectado no documento de entrada, onde ele foi encontrado).

Ele vai usar o conjunto de caracteres de saída especificado na linha de
comando. Se não tiver sido especificado, ele vai usar o conjunto de
caracteres do PO de entrada, e se o PO de entrada possuir o "CHARSET"
padrão, ele vai retornar o conjunto de caracteres do documento de entrada,
de forma que nenhuma codificação é realizada.

=back

=head1 DIREÇÕES FUTURAS

Um problema do atual TransTractor é que ele não consegue manipular documento
traduzido contendo todos idiomas, como modelos de debconf, ou arquivos
.desktop.

Para resolver esse problema, as únicas alterações necessárias na interface
são:

=over 2

=item -

pegar um hash como po_in_name (uma lista por idioma)

=item -

adicionar um argumento para traduzir para indicar o idioma alvo

=item -

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

=back

Veremos se isso é o suficiente ;)

=head1 AUTORES

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

=head1 TRADUÇÃO

 Luiz Fernando Ranghetti <elchevive@opensuse.org>
 Rafael Fontenelle <rafaelff@gnome.org>

