
        *****************************************************
        *           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 gettextize($$)

Esta função produz um catálogo de mensagens traduzido de dois catálogos, um
original e uma traduzido. Este processo é descrito no L<po4a(7)|po4a.7>,
seção I<Gettextização: como ela funciona?>.

=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 equals_msgid(po)

Retorna ($uptodate, $diagnostic) com $uptodate indicando se todas as msgid
do arquivo po atual também estão presentes naquele que foi passado como
parâmetro (todos os outros campos são ignorados na comparação de
arquivos). Informalmente se $uptodate retornar falso, então os arquivos po
podem ser alterados quando forem através do B<po4a-updatepo>.

Se $uptodate for falso, então $diagnostic contém um diagnóstico de por que
isto é assim.

=item msgid($)

retorna o msgid do número fornecido.

=item msgid_doc($)

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

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

