
        *****************************************************
        *           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 de manipulação dum ficheiro PO

=head1 RESUMO

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

    # Read PO file
    $pofile->read('file.po');

    # Add an entry
    $pofile->push('msgid' => 'Hello', 'msgstr' => 'bonjour',
                  'flags' => "wrap", 'reference'=>'file.c:46');

    # Extract a translation
    $pofile->gettext("Hello"); # returns 'bonjour'

    # Write back to a file
    $pofile->write('otherfile.po');

=head1 DESCRIÇÃO

Locale::po4a:: Po é um módulo que permite que manipule catálogos de
mensagens. Pode carregar e escrever de/para um ficheiro (cuja extensão é
muitas vezes I<po>), pode construir novas entradas na execução ou pedir uma
tradução de uma cadeia.

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

Este módulo é parte do projeto po4a, cujo objetivo é usar ficheiros PO
(projetado na origem para facilitar a tradução de mensagens do programa)
para traduzir tudo, inclusive a documentação (página do manual, manual de
informação), descrição do pacote, modelos debconf e tudo o que pode
beneficiar a partir deste.

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

=over 4

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

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
ficheiro sem o número da linha, B<counter> para substituir os números de
linha a aumentar o contador e B<full> para incluir referências
completas. (predefinição: full).

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

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

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

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

Define o endereço do relatório para bugs de msgid. Por predefinição, os
ficheiros POT criados não têm campos Report-Msgid-bugs-To.

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

Define o titular dos direitos de autor no cabeçalho POT. O valor predefinido
é " Free Software Foundation, Inc."

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

Define o nome do pacote para o cabeçalho POT. A predefinição é "PACKAGE".

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

Define a versão do pacote para o cabeçalho POT. A predefinição é "VERSION".

=back

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

=over 4

=item novo()

Cria um catálogo de mensagem novo. Se um argumento é fornecido, é o nome dum
ficheiro PO que deve carregar.

=item ler($)

Lê um ficheiro PO (que o nome é dado como argumento). Entradas previamente
existentes em si não são removidas, os novos são adicionados ao fim do
catálogo.

=item escrever($)

Escreve o catálogo atual no ficheiro dado.

=item write_if_needed($$)

Como escrever, mas se o ficheiro PO ou POT já existe, o objeto será escrito
num ficheiro temporário, que será comparado com o ficheiro existente para
verificar se a atualização é necessária (isso evita mudar um POT apenas para
atualizar uma linha de referência ou o campo POT-Creation-Date).

=item filtro($)

Esta função extrai um catálogo a partir de um já existente. Somente as
entradas que têm uma referência no ficheiro dado serão postas no catálogo
resultante.

Esta função analisa o seu argumento, converte-o para uma definição função
Perl, avalia esta definição e filtra os campos para os quais esta função
retornará verdadeiro.

Algumas vezes gosto de Perl ;)

=back

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

=over 4

=item gettext($%)

Pede a tradução duma dada sequência como argumento no catálogo atual. Esta
função retorna a sequência (não traduzida) original, se a cadeia não foi
encontrada.

Após a cadeia para traduzir, pode passar um 'hash' de argumentos
adicionais. Aqui são as entradas válidas:

=over

=item B<wrap>

um 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 uma tradução e envolve o resultado.

=item B<wrapcol>

a coluna em que devemos envolver (predefinição: 76).

=back

=item stats_get()

Retorna estatísticas sobre a taxa de acerto de gettext desde a última vez
que stats_clear() foi chamado. Por favor, note que não são as mesmas
estatísticas que são impressas por msgfmt --statistic. Aqui, são as
estatísticas sobre o recente uso do ficheiro PO, enquanto msgfmt informa
sobre o estado do ficheiro. Exemplo de uso:

    [algum uso do ficheiro PO para traduzir coisas]

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

=item stats_clear()

Limpa as estatísticas sobre os êxitos do gettext.

=back

=head1 Funções para a construção de um catálogo de mensagens

=over 4

=item push(%)

Força uma nova entrada no final do catálogo atual. Os argumentos devem
formar uma tabela hash. As chaves válidas são:

=over 4

=item B<msgid>

a cadeia no idioma original.

=item B<msgstr>

a tradução.

=item B<reference>

uma indicação de onde essa cadeia foi encontrada. Exemplo: file.c:46 (ou
seja, em 'file.c' na linha 46). Pode ser uma lista separada por espaços em
caso de múltiplas ocorrências.

=item B<comment>

um comentário adicionado aqui manualmente (pelo tradutor). O formato é
livre.

=item B<automatic>

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

=item B<flags>

lista separada por espaços de todas as bandeiras definidas para esta
entrada.

As bandeiras 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> and
B<fuzzy>.

Consulte a documentação do gettext para o significado delas.

=item B<type>

este é mais um argumento interno: é usado enquanto os documentos são
'gettextizados'. A ideia aqui é analisar tanto o original como a tradução
num objeto PO e fundi-los, a usar um 'msgid' como 'msgid' e os outros
'msgid' como 'msgstr'. Para ter certeza de que as coisas ficam bem, cada
'msgid em objetos PO recebem um tipo, com base na estrutura deles (como
"chapt", "sect1", "p" e assim por diante em DocBook). Se os tipos de cadeias
não são as mesmas, significa que ambos os ficheiros não partilham a mesma
estrutura e, o processo e informa um erro.

Esta informação é escrita como comentário automático no ficheiro PO uma vez
que dá aos tradutores algum contexto sobre as cadeias para traduzir.

=item B<wrap>

booleano que indica se os espaços em branco podem ser mutilados em
cosméticas reformatações. Se for verdade, a cadeia está canonizada antes do
uso.

Esta informação é gravada no ficheiro PO que usa a bandeira B<wrap> ou B
<no-wrap>.

=item B<wrapcol>

ignorada; a chave é mantida para computabilidade retroativa.

=back

=back

=head1 Funções variadas

=over 4

=item count_entries()

Retorna a quantidade de entradas no catálogo (sem o cabeçalho).

=item count_entries_doc()

Retorna a quantidade de entradas no documento. Se uma cadeia aparece
múltiplas vezes no documento, será contada múltiplas vezes.

=item msgid($)

Retorna o identificador de mensagem do número dado.

=item msgid_doc($)

Retorna o identificador de mensagem na posição dado do documento.

=item type_doc($)

Retorna o tipo de msgid com a posição dada no documento. Provavelmente, isso
só é útil para gettextização e é armazenado separadamente de
{$msgid}{'type'} porque o local posterior pode ser substituído por outro
tipo quando $msgid é duplicado no documento mestre.

=item get_charset()

Retorna o conjunto de caracteres especificado no cabeçalho PO. Se não foi
definido, irá retornar "UTF-8".

=back

=head1 AUTORES

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