.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Locale::Po4a::Po 3pm"
.TH Locale::Po4a::Po 3pm "2023-01-03" "Ferramentas Po4a" "Ferramentas Po4a"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NOME"
.IX Header "NOME"
Locale::Po4a::Po \- módulo de manipulação dum ficheiro \s-1PO\s0
.SH "SINOPSE"
.IX Header "SINOPSE"
.Vb 2
\&    use Locale::Po4a::Po;
\&    my $pofile=Locale::Po4a::Po\->new();
\&
\&    # Ler ficheiro PO
\&    $pofile\->read(\*(Aqfile.po\*(Aq);
\&
\&    # Adicionar uma entrada
\&    $pofile\->push(\*(Aqmsgid\*(Aq => \*(AqHello\*(Aq, \*(Aqmsgstr\*(Aq => \*(Aqolá\*(Aq,
\&                  \*(Aqflags\*(Aq => "wrap", \*(Aqreference\*(Aq=>\*(Aqfile.c:46\*(Aq);
\&
\&    # Extrair uma tradução
\&    $pofile\->gettext("bom dia"); # returns \*(Aqbonjour\*(Aq
\&
\&    # Escrever de volta para um ficheiro
\&    $pofile\->write(\*(Aqotherfile.po\*(Aq);
.Ve
.SH "DESCRIÇÃO"
.IX Header "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 \fIpo\fR), pode construir novas entradas na execução ou pedir uma tradução de uma cadeia.
.PP
Para uma descrição mais completa do catálogo de mensagens no formato \s-1PO\s0 e o uso dele, por favor veja a documentação info do programa gettext. (nó \*(L"`Ficheiros \s-1PO\*(R"\s0').
.PP
Este módulo é parte do projeto po4a, cujo objetivo é usar ficheiros \s-1PO\s0 (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.
.SH "OPÇÕES ACEITES POR ESTE MÓDULO"
.IX Header "OPÇÕES ACEITES POR ESTE MÓDULO"
.IP "\fB\-\-porefs\fR \fItype\fR" 4
.IX Item "--porefs type"
Especifica o formato de referência. O argumento \fItipo\fR pode ser um de: \fBnever\fR para não produzir qualquer referência, \fBfile\fR para especificar o ficheiro sem o número da linha, \fBcounter\fR para substituir os números de linha a aumentar o contador e \fBfull\fR para incluir referências completas. (predefinição: full).
.IP "\fB\-\-wrap\-po\fR \fBno\fR|\fBnewlines\fR|\fInumber\fR (predefinição: 76)" 4
.IX Item "--wrap-po no|newlines|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.
.Sp
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 \fBnewlines\fR, o po4a dividirá apenas o msgid e o msgstr após as novas linhas no conteúdo. Se for definido como \fBno\fR, 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.
.Sp
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.
.IP "\fB\-\-msgid\-bugs\-address\fR \fIe\-mail@endereço\fR" 4
.IX Item "--msgid-bugs-address e-mail@endereço"
Definir o endereço do relatório para msgid bugs. Por predefinição, os ficheiros \s-1POT\s0 criados não têm campos Report-Msgid-bugs-To.
.IP "\fB\-\-copyright\-holder\fR \fIstring\fR" 4
.IX Item "--copyright-holder string"
Definir o titular dos direitos de autor no cabeçalho \s-1POT. O\s0 valor predefinido é \*(L" Free Software Foundation, Inc.\*(R"
.IP "\fB\-\-package\-name\fR \fIstring\fR" 4
.IX Item "--package-name string"
Definir o nome do pacote para o cabeçalho \s-1POT. A\s0 predefinição é \*(L"\s-1PACKAGE\*(R".\s0
.IP "\fB\-\-package\-version\fR \fIstring\fR" 4
.IX Item "--package-version string"
Definir o nome do pacote para o cabeçalho \s-1POT. A\s0 predefinição é \*(L"\s-1VERSION\*(R".\s0
.SH "Funções relativas a catálogos de mensagens inteiros"
.IX Header "Funções relativas a catálogos de mensagens inteiros"
.IP "\fBnovo()\fR" 4
.IX Item "novo()"
Cria um catálogo de mensagem novo. Se um argumento é fornecido, é o nome dum ficheiro \s-1PO\s0 que deve carregar.
.IP "ler($)" 4
.IX Item "ler($)"
Lê um ficheiro \s-1PO\s0 (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.
.IP "escrever($)" 4
.IX Item "escrever($)"
Escreve o catálogo atual ao ficheiro dado.
.IP "write_if_needed($$)" 4
.IX Item "write_if_needed($$)"
Como escrever, mas se o ficheiro \s-1PO\s0 ou \s-1POT\s0 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 \s-1POT\s0 apenas para atualizar uma linha de referência ou o campo POT-Creation-Date).
.IP "filtro($)" 4
.IX Item "filtro($)"
Esta função extrai um catálogo a partir de um já existente. Somente as entradas têm uma referência no ficheiro dado será posto no catálogo resultante.
.Sp
Esta função analisa o argumento dele, 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.
.Sp
Algumas vezes gosto de Perl ;)
.IP "\fBpara_utf8()\fR" 4
.IX Item "para_utf8()"
Recodifica para \s-1UTF\-8\s0 as mensagens traduzidas do \s-1PO.\s0 Não faz nada se o conjunto de carateres não é especificado no ficheio \s-1PO\s0 (\*(L"charset\*(R" value), ou se já é \s-1UTF\-8\s0 ou \s-1ASCII.\s0
.SH "Funções para utilizar um catálogo de mensagens para traduções"
.IX Header "Funções para utilizar um catálogo de mensagens para traduções"
.IP "gettext($%)" 4
.IX 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.
.Sp
Após a cadeia para traduzir, pode passar um 'hash' de argumentos adicionais. Aqui são as entradas válidas:
.RS 4
.IP "\fBwrap\fR" 4
.IX Item "wrap"
um booleano 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.
.IP "\fBwrapcol\fR" 4
.IX Item "wrapcol"
a coluna em que devemos envolver (predefinição: 76).
.RE
.RS 4
.RE
.IP "\fBstats_get()\fR" 4
.IX Item "stats_get()"
Retorna estatísticas sobre a taxa de acerto de gettext desde a última vez que \fBstats_clear()\fR 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 \s-1PO,\s0 enquanto msgfmt informa sobre o estado do ficheiro. Exemplo de uso:
.Sp
.Vb 1
\&    [algum uso do ficheiro PO para traduzir coisas]
\&
\&    ($percent,$hit,$queries) = $pofile\->stats_get();
\&    print "Até agora, encontramos traduções para $percent\e% ($hit de $queries) de cadeias.\en";
.Ve
.IP "\fBstats_clear()\fR" 4
.IX Item "stats_clear()"
Limpa as estatísticas sobre os êxitos do gettext.
.SH "Funções para a construção de um catálogo de mensagens"
.IX Header "Funções para a construção de um catálogo de mensagens"
.IP "push(%)" 4
.IX Item "push(%)"
Empurrar uma nova entrada no final do catálogo atual. Os argumentos devem formar uma tabela hash. As chaves válidas são:
.RS 4
.IP "\fBmsgid\fR" 4
.IX Item "msgid"
a cadeia no idioma original.
.IP "\fBmsgstr\fR" 4
.IX Item "msgstr"
a tradução.
.IP "\fBreference\fR" 4
.IX Item "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.
.IP "\fBcomment\fR" 4
.IX Item "comment"
um comentário adicionado aqui manualmente (pelo tradutor). O formato é livre.
.IP "\fBautomatic\fR" 4
.IX Item "automatic"
um comentário que foi adicionado automaticamente pelo programa de extração da cadeia. Veja a opção \fB\-\-add\-comments\fR do programa \fBxgettext\fR para obter mais informações.
.IP "\fBflags\fR" 4
.IX Item "flags"
lista separada por espaços de todas as 'flags' definidas para esta entrada.
.Sp
As 'flags' válidas são: \fBc\-text\fR, \fBpython-text\fR, \fBlisp-text\fR, \fBelisp-text\fR, \fBlibrep-text\fR, \fBsmalltalk-text\fR, \fBjava-text\fR, \fBawk-text\fR, \fBobject-pascal-text\fR, \fBycp-text\fR, \fBtcl-text\fR, \fBwrap\fR, \fBno-wrap\fR and \fBfuzzy\fR.
.Sp
Consulte a documentação do gettext para o significado deles.
.IP "\fBtype\fR" 4
.IX Item "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 \s-1PO\s0 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 \s-1PO\s0 recebem um tipo, com base na estrutura deles (como \*(L"chapt\*(R", \*(L"sect1\*(R", \*(L"p\*(R" 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.
.Sp
Esta informação é escrita como comentário automático no ficheiro \s-1PO\s0 uma vez que dá aos tradutores algum contexto sobre as cadeias para traduzir.
.IP "\fBwrap\fR" 4
.IX Item "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.
.Sp
Esta informação é gravada no ficheiro \s-1PO\s0 a usar a 'flag' \fBwrap\fR ou B <no\-wrap>.
.IP "\fBwrapcol\fR" 4
.IX Item "wrapcol"
a coluna em que devemos envolver (predefinição: 76).
.Sp
Esta informação não é escrita no ficheiro \s-1PO.\s0
.RE
.RS 4
.RE
.SH "Funções auxiliares"
.IX Header "Funções auxiliares"
.IP "\fBcount_entries()\fR" 4
.IX Item "count_entries()"
Retorna a quantidade de entradas no catálogo (sem o cabeçalho).
.IP "\fBcount_entries_doc()\fR" 4
.IX Item "count_entries_doc()"
Retorna a quantidade de entradas no documento. Se uma cadeia aparece múltiplas vezes no documento, será contado múltiplas vezes.
.IP "msgid($)" 4
.IX Item "msgid($)"
Retorna o identificador de mensagem do número dado.
.IP "msgid_doc($)" 4
.IX Item "msgid_doc($)"
Retorna o identificador de mensagem na posição do documento dada.
.IP "type_doc($)" 4
.IX 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 \f(CW$msgid\fR is duplicated in the master document.
.IP "\fBget_charset()\fR" 4
.IX Item "get_charset()"
Retorna o conjunto de caracteres especificado no cabeçalho \s-1PO.\s0 Se não foi definido, irá retornar \*(L"\s-1UTF\-8\*(R".\s0
.IP "set_charset($)" 4
.IX Item "set_charset($)"
Isso define o conjunto de caracteres do cabeçalho \s-1PO\s0 ao valor especificado no primeiro argumento dele. Se nunca invocar esta função (e nenhum ficheiro com um conjunto de caracteres especificado é lido), o valor predefinido é \*(L"\s-1UTF\-8\*(R".\s0 Este valor não altera o comportamento deste módulo, que é utilizado apenas para preencher esse campo no cabeçalho e devolvê\-lo em \fBget_charset()\fR.
.SH "AUTORES"
.IX Header "AUTORES"
.Vb 2
\& Denis Barbier <barbier@linuxfr.org>
\& Martin Quinson (mquinson#debian.org)
.Ve