
        *****************************************************
        *           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::Po - módulo para manipulação de arquivos PO

=head1 SINOPSE

    use Locale::Po4a::Po;
    my $pofile=Locale::Po4a::Po->new();

    # Lê um arquivo PO
    $pofile->read('arquivo.po');

    # Adiciona uma entrada
    $pofile->push('msgid' => 'Hello', 'msgstr' => 'bom dia',
                  'flags' => "wrap", 'reference'=>'file.c:46');

    # Extrai uma tradução
    $pofile->gettext("Hello"); # retorna "bom dia"

    # Escreve de volta em um arquivo
    $pofile->write('outroarquivo.po');

=head1 DESCRIÇÃO

Locale::Po4a::Po é um módulo que permite que você manipule catálogo de mensagens. Você pode carregar e escrever de/para um arquivo (cujas extensões geralmente são I<po>), você pode compilar novas entradas em tempo real ou requisitar a tradução de uma string.

Para uma descrição mais completa do catálogo de mensagens no formato PO e seu uso, por favor veja a documentação info do programa gettext. (nó "`Arquivos PO"').

Este módulo é parte do projeto po4a, cujo objetivo é usar arquivos PO (projetado em sua origem para facilitar a tradução de mensagens de programas) para traduzir tudo, incluindo documentação (páginas man, manual info), descrição de pacotes, modelos de debconf e tudo que pode se beneficiar dele.

=head1 OPÇÕES ACEITAS POR ESTE MÓDULO

=over 4

=item B<--porefs> I<tipo>

Especifica o formato de referência. O argumento I<tipo> pode ser um de: B<never> para não produzir qualquer referência, B<file> para especificar o arquivo sem o número de linha, B<counter> para substituir os números de linha aumentando o contador e B<full> para incluir referências completas. (padrão: full).

=item B<--wrap-po> B<no>|B<newlines>|I<number> (padrão: 76)

Especifica como o arquivo po deve ter sua quebra de linha. Isso permite escolher entre arquivos que tem boa quebra de linha, mas que podem levar a conflitos de git, ou arquivos que são mais fáceis de manipular automaticamente, mas mais difíceis de ler para humanos.

Historicamente, o pacote gettext reformatou os arquivos po na 77ª coluna para questões cosméticas. Esta opção especifica o comportamento de po4a. Se definido como um valor numérico, o po4a quebrará linha do arquivo po após esta coluna e após novas linhas no conteúdo. Se definido como B<newlines>, o po4a dividirá apenas o msgid e o msgstr após as novas linhas no conteúdo. Se definido como B<no>, o po4a não quebrará linha do arquivo po. Os comentários de referência têm sempre as linhas quebradas pelas ferramentas do gettext que nós usamos internamente.

Observe que esta opção não afeta a maneira como o msgid e o msgstr sofrem quebra de linhas, ou seja, como os caracteres de nova linha são adicionados ao conteúdo dessas strings.

=item B<--msgid-bugs-address> I<e-mail@endereço>

Define o endereço para relatórios de erros em msgids. Por padrão, os arquivos POT criados possuem nenhum campo Report-Msgid-Bugs-To.

=item B<--copyright-holder> I<string>

Define o detentor do copyright no cabeçalho do POT. O valor padrão é "Free Software Foundation, Inc."

=item B<--package-name> I<string>

Define o nome do pacote para o cabeçalho do POT. O padrão é "PACKAGE".

=item B<--package-version> I<string>

Define a versão do pacote do cabeçalho do POT. O padrão é "VERSION".

=back

=head1 Funções relativas a catálogos de mensagens inteiros

=over 4

=item new()

Cria uma nova mensagem de catálogo. Se for fornecido um argumento, é o nome de um arquivo PO que nós devemos carregar.

=item read($)

Lê um arquivo PO (cujo nome é fornecido como argumento). Entradas previamente existentes nele não são removidas, sendo as novas adicionadas ao final do catálogo.

=item write($)

Escreve o catálogo atual no arquivo fornecido.

=item write_if_needed($$)

Similar ao "write", mas se o arquivo PO ou POT já existir, o objeto será escrito em um arquivo temporário, o qual será comparado com o arquivo existente para verificar se a atualização é necessária (isso evita alterar um POT apenas para atualizar uma linha de referência ou o campo POT-Creation-Date).

=item filter($)

Esta função extrai um catálogo de um outro existente. Apenas as entradas contendo uma referência no arquivo fornecido serão inseridas no catálogo resultante.

Esta função analisa seu argumento, convertendo-o para uma definição de função de Perl, avalia esta definição e filtra os campos para os quais esta função retorna verdadeiro.

Tem vezes que eu adoro Perl ;)

=item to_utf8()

Re-codifica para UTF-8 as "msgstr"s do PO. Faz nada se a codificação de caracteres não tiver sido especificada no arquivo PO (valor "CHARSET") ou se ele já for UTF-8 ou ASCII.

=back

=head1 Funções para usar um catálogo de mensagens para traduções

=over 4

=item gettext($%)

Requisita a tradução de uma string fornecida como argumento no catálogo atual. A função retorna a string original (não traduzida) se a string não tiver sido encontrada.

Após a string para ser traduzida, você pode passar um hash de argumentos extras. Aqui estão as entradas válidas:

=over 

=item B<wrap>

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

=item B<wrapcol>

a coluna na qual nós deveríamos dimensionar (padrão: 76).

=back

=item stats_get()

Retorna estatísticas sobre a proporção de acerto do gettext desde a última vez que stats_clear() foi chamada. Por favor, note que essa não é a mesma estatística impressa por msgfmt --statistic. Aqui, essa estatística sobre uso recente do arquivo PO, enquanto msgfmt relata o estado do arquivo. Exemplo de uso:

    [um uso do arquivo PO para traduzir coisas]

    ($percent,$hit,$queries) = $pofile->stats_get();
    print "Até agora, nós encontramos traduções para $percent\%  ($hit de $queries) da strings.\n";

=item stats_clear()

Limpa as estatísticas sobre os acertos do gettext.

=back

=head1 Funções para compilar um catálogo de mensagem

=over 4

=item push(%)

Insere uma nova entrada no final do catálogo atual. Os argumentos deveriam formar uma tabela de hash. As chaves válidas são:

=over 4

=item B<msgid>

a string no idioma original.

=item B<msgstr>

a tradução.

=item B<reference>

uma indicação de onde esta string foi encontrada. Exemplo: file.c:46 (significa em "file.c" na linha 46). Ela pode ser uma lista separada por espaço no caso de múltiplas ocorrências.

=item B<comment>

um comentário adicionado aqui manualmente (pelos tradutores). Este formato é livre.

=item B<automatic>

um comentário que foi adicionado automaticamente pelo programa de extração de strings. Veja a opção B<--add-comments> no programa B<xgettext> para mais informações.

=item B<flags>

lista separada por espaço de todas as opções definidas para esta entrada.

Opções válidas são: B<c-text>, B<python-text>, B<lisp-text>, B<elisp-text>, B<librep-text>, B<smalltalk-text>, B<java-text>, B<awk-text>, B<object-pascal-text>, B<ycp-text>, B<tcl-text>, B<wrap>, B<no-wrap> e B<fuzzy>.

Veja a documentação do gettext para ver seu significado.

=item B<type>

esse é basicamente um argumento interno: ele é usado ao gettextizar documentos. A ideia aqui é analisar tanto o original quanto a tradução em um objeto PO e mesclá-los, usando a msgid do primeiro e o msgid do segundo como msgstr. Para certificar-se de que as coisas funcionem, a cada msgid nos objetos PO é fornecido um tipo, baseado em sua estrutura (como "chapt", "sect1", "p" e outros, em DocBook). Se os tipos de strings não forem os mesmos, significa que ambos arquivos não compartilham a mesma estrutura e o processa relata um erro.

Esta informação é escrita como um comentário automático no arquivo PO já que isso fornece aos tradutores algum contexto sobre as strings para traduzir.

=item B<wrap>

booleano indicando se espaços em branco podem ser separados em reformatação cosmética. Se verdadeiro, a string é canonizada antes de ser usada.

Esta informação é escrita no arquivo PO usando as opções B<wrap> ou B<no-wrap>.

=item B<wrapcol>

a coluna na qual nós deveríamos dimensionar (padrão: 76).

Esta informação não é escrita no arquivo PO.

=back

=back

=head1 Funções diversas

=over 4

=item count_entries()

retorna o número de entradas no catálogo (sem o cabeçalho).

=item count_entries_doc()

Retorna o número de entradas no documento. Se uma string aparece múltiplas vezes no documento, ele vai ser contado múltiplas vezes.

=item msgid($)

retorna o msgid do número fornecido.

=item msgid_doc($)

retorna o msgid com a posição fornecida no documento.

=item type_doc($)

Returns the type of the msgid with the given position in the document. This is probably only useful to gettextization, and it's stored separately from {$msgid}{'type'} because the later location may be overwritten by another type when the $msgid is duplicated in the master document.

=item get_charset()

retorna a codificação de caracteres do cabeçalho do PO. Se ele não tiver sido definido, ele vai retornar "UTF-8".

=item set_charset($)

Isso define a codificação de caracteres do cabeçalho PO para o valor especificado no seu primeiro argumento. Se você nunca chamou esta função (e nenhum arquivo com uma codificação de caracteres especificada for lida), o valor padrão é deixado com "UTF-8". Este valor não altera o comportamento deste módulo, ele apenas é usado para preencher aquele campo no cabeçalho e retorná-lo em get_charset().

=back

=head1 AUTORES

 Denis Barbier <barbier@linuxfr.org>
 Martin Quinson (mquinson#debian.org)

