.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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 1"
.TH LOCALE::PO4A::PO.3PM 1 2024-06-26 "perl v5.38.2" "User Contributed Perl Documentation"
.\" 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 PO
.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 PO e o uso dele, por favor veja a documentação info do programa gettext. (nó "`Ficheiros PO"').
.PP
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.
.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 POT 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 POT. O valor predefinido é " Free Software Foundation, Inc."
.IP "\fB\-\-package\-name\fR \fIstring\fR" 4
.IX Item "--package-name string"
Definir o nome do pacote para o cabeçalho POT. A predefinição é "PACKAGE".
.IP "\fB\-\-package\-version\fR \fIstring\fR" 4
.IX Item "--package-version string"
Definir o nome do pacote para o cabeçalho POT. A predefinição é "VERSION".
.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 PO que deve carregar.
.IP ler($) 4
.IX 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.
.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 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).
.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 ;)
.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 PO, 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 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.
.Sp
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.
.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 PO a usar a 'flag' \fBwrap\fR ou B <no\-wrap>.
.IP \fBwrapcol\fR 4
.IX Item "wrapcol"
ignored; the key is kept for backward computability.
.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 PO. Se não foi definido, irá retornar "UTF\-8".
.SH AUTORES
.IX Header "AUTORES"
.Vb 2
\& Denis Barbier <barbier@linuxfr.org>
\& Martin Quinson (mquinson#debian.org)
.Ve