.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29)
.\"
.\" 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 turned on, 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 "2016-01-05" "Ferramentas do Po4a" "Ferramentas do 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 para manipulação de arquivos \s-1PO\s0
.SH "SINOPSE"
.IX Header "SINOPSE"
.Vb 2
\&    use Locale::Po4a::Po;
\&    my $pofile=Locale::Po4a::Po\->new();
\&
\&    # Lê um arquivo PO
\&    $pofile\->read(\*(Aqarquivo.po\*(Aq);
\&
\&    # Adiciona uma entrada
\&    $pofile\->push(\*(Aqmsgid\*(Aq => \*(AqHello\*(Aq, \*(Aqmsgstr\*(Aq => \*(Aqbom dia\*(Aq,
\&                  \*(Aqflags\*(Aq => "wrap", \*(Aqreference\*(Aq=>\*(Aqfile.c:46\*(Aq);
\&
\&    # Extrai uma tradução
\&    $pofile\->gettext("Hello"); # retorna "bom dia"
\&
\&    # Escreve de volta em um arquivo
\&    $pofile\->write(\*(Aqoutroarquivo.po\*(Aq);
.Ve
.SH "DESCRIÇÃO"
.IX Header "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 \fIpo\fR), você pode compilar novas entradas em tempo real ou
requisitar a tradução de uma string.
.PP
For a more complete description of message catalogs in the \s-1PO\s0 format and
their use, please refer to the info documentation of the gettext program
(node \*(L"`\s-1PO\s0 Files\*(R"').
.PP
Este módulo é parte do projeto po4a, cujo objetivo é usar arquivos \s-1PO
\&\s0(projetado em sua origem para facilitar a tradução de mensagens de
programas) para traduzir tudo, incluindo documentação (páginas de manual,
manual info), descrição de pacotes, modelos de debconf e tudo que pode se
beneficiar dele.
.SH "OPÇÕES ACEITAS POR ESTE MÓDULO"
.IX Header "OPÇÕES ACEITAS POR ESTE MÓDULO"
.IP "\fB\-\-porefs\fR \fItype\fR[,\fBwrap\fR|\fBnowrap\fR]" 4
.IX Item "--porefs type[,wrap|nowrap]"
Especifica o formato de referência. O argumento \fItipo\fR pode ser um de:
\&\fBnone\fR para não produzir qualquer referência, \fBnoline\fR para não
especificar o número de linha (mais precisamente, todos os números de linhas
são substituídas por 1), \fBcounter\fR para substituir um número de linha
aumentando o contador e \fBfull\fR para incluir referências completas.
.Sp
Argumento pode estar seguido por uma vírgula e as palavras-chaves \fBwrap\fR ou
\&\fBnowrap\fR. Referências são escritas por padrão em uma única linha. A opção
\&\fBwrap\fR quebra as referências em várias linhas, para copiar as ferramentas
do \fBgettext\fR (\fBxgettext\fR e \fBmsgmerge\fR). Essa opção vai se tornar o padrão
em um lançamento futuro, mas ela é mais sensível. A opção \fBnowrap\fR está
disponível de forma que usuários que desejarem manter o comportamento antigo
podem fazê\-lo.
.IP "\fB\-\-msgid\-bugs\-address\fR \fIe\-mail@endereço\fR" 4
.IX Item "--msgid-bugs-address e-mail@endereço"
Define o endereço para relatórios de erros em msgids. Por padrão, os
arquivos \s-1POT\s0 criados possuem nenhum campo Report-Msgid-Bugs-To.
.IP "\fB\-\-copyright\-holder\fR \fIstring\fR" 4
.IX Item "--copyright-holder string"
Define o detentor do copyright no cabeçalho do \s-1POT. O\s0 valor padrão é \*(L"Free
Software Foundation, Inc.\*(R"
.IP "\fB\-\-package\-name\fR \fIstring\fR" 4
.IX Item "--package-name string"
Define o nome do pacote para o cabeçalho do \s-1POT. O\s0 padrão é \*(L"\s-1PACKAGE\*(R".\s0
.IP "\fB\-\-package\-version\fR \fIstring\fR" 4
.IX Item "--package-version string"
Define a versão do pacote do cabeçalho do \s-1POT. O\s0 padrão é \*(L"\s-1VERSION\*(R".\s0
.SH "Functions concerning entire message catalogs"
.IX Header "Functions concerning entire message catalogs"
.IP "\fInew()\fR" 4
.IX Item "new()"
Cria uma nova mensagem de catálogo. Se for fornecido um argumento, é o nome
de um arquivo \s-1PO\s0 que nós devemos carregar.
.IP "read($)" 4
.IX Item "read($)"
Lê um arquivo \s-1PO \s0(cujo nome é fornecido como argumento). Entradas
previamente existentes nele não são removidas, sendo as novas adicionadas ao
final do catálogo.
.IP "write($)" 4
.IX Item "write($)"
Escreve o catálogo atual no arquivo fornecido.
.IP "write_if_needed($$)" 4
.IX Item "write_if_needed($$)"
Similar ao \*(L"write\*(R", mas se o arquivo \s-1PO\s0 ou \s-1POT\s0 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 \s-1POT\s0 apenas para atualizar uma linha de referência ou o campo
POT-Creation-Date).
.IP "gettextize($$)" 4
.IX 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 \fIpo4a\fR\|(7),
seção \fIGettextização: como ela funciona?\fR.
.IP "filter($)" 4
.IX 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.
.Sp
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.
.Sp
Tem vezes que eu adoro Perl ;)
.IP "\fIto_utf8()\fR" 4
.IX Item "to_utf8()"
Re-codifica para \s-1UTF\-8\s0 as \*(L"msgstr\*(R"s do \s-1PO.\s0 Faz nada se a codificação de
caracteres não tiver sido especificada no arquivo \s-1PO \s0(valor \*(L"\s-1CHARSET\*(R"\s0) ou se
ele já for \s-1UTF\-8\s0 ou \s-1ASCII.\s0
.SH "Funções para usar um catálogo de mensagens para traduções"
.IX Header "Funções para usar um catálogo de mensagens para traduções"
.IP "gettext($%)" 4
.IX 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.
.Sp
Após a string para ser traduzida, você pode passar um hash de argumentos
extras. Aqui estão as entradas válidas:
.RS 4
.IP "\fBwrap\fR" 4
.IX Item "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.
.IP "\fBwrapcol\fR" 4
.IX Item "wrapcol"
a coluna na qual nós deveríamos dimensionar (padrão: 76).
.RE
.RS 4
.RE
.IP "\fIstats_get()\fR" 4
.IX Item "stats_get()"
Retorna estatísticas sobre a proporção de acerto do gettext desde a última
vez que \fIstats_clear()\fR 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 \s-1PO,\s0 enquanto msgfmt relata o estado do
arquivo. Exemplo de uso:
.Sp
.Vb 1
\&    [um uso do arquivo PO para traduzir coisas]
\&
\&    ($percent,$hit,$queries) = $pofile\->stats_get();
\&    print "Até agora, nós encontramos traduções para $percent\e%  ($hit de $queries) da strings.\en";
.Ve
.IP "\fIstats_clear()\fR" 4
.IX Item "stats_clear()"
Limpa as estatísticas sobre os acertos do gettext.
.SH "Funções para compilar um catálogo de mensagem"
.IX Header "Funções para compilar um catálogo de mensagem"
.IP "push(%)" 4
.IX 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:
.RS 4
.IP "\fBmsgid\fR" 4
.IX Item "msgid"
a string 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 esta string foi encontrada. Exemplo: file.c:46
(significa em \*(L"file.c\*(R" na linha 46). Ela pode ser uma lista separada por
espaço no caso de múltiplas ocorrências.
.IP "\fBcomment\fR" 4
.IX Item "comment"
um comentário adicionado aqui manualmente (pelos tradutores). Este formato é
livre.
.IP "\fBautomatic\fR" 4
.IX Item "automatic"
um comentário que foi adicionado automaticamente pelo programa de extração
de strings. Veja a opção \fB\-\-add\-comments\fR no programa \fBxgettext\fR para mais
informações.
.IP "\fBflags\fR" 4
.IX Item "flags"
lista separada por espaço de todas as opções definidas para esta entrada.
.Sp
Opções 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 e
\&\fBfuzzy\fR.
.Sp
Veja a documentação do gettext para ver seu significado.
.IP "\fBtype\fR" 4
.IX Item "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 \s-1PO\s0 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 \s-1PO\s0 é fornecido um tipo, baseado em sua estrutura (como \*(L"chapt\*(R",
\&\*(L"sect1\*(R", \*(L"p\*(R" 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.
.Sp
Esta informação é escrita como um comentário automático no arquivo \s-1PO\s0 já que
isso fornece aos tradutores algum contexto sobre as strings para traduzir.
.IP "\fBwrap\fR" 4
.IX Item "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.
.Sp
Esta informação é escrita no arquivo \s-1PO\s0 usando as opções \fBwrap\fR ou
\&\fBno-wrap\fR.
.IP "\fBwrapcol\fR" 4
.IX Item "wrapcol"
a coluna na qual nós deveríamos dimensionar (padrão: 76).
.Sp
Esta informação não é escrita no arquivo \s-1PO.\s0
.RE
.RS 4
.RE
.SH "Funções diversas"
.IX Header "Funções diversas"
.IP "\fIcount_entries()\fR" 4
.IX Item "count_entries()"
retorna o número de entradas no catálogo (sem o cabeçalho).
.IP "\fIcount_entries_doc()\fR" 4
.IX 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.
.IP "msgid($)" 4
.IX Item "msgid($)"
retorna o msgid do número fornecido.
.IP "msgid_doc($)" 4
.IX Item "msgid_doc($)"
retorna o msgid com a posição fornecida no documento.
.IP "\fIget_charset()\fR" 4
.IX Item "get_charset()"
retorna a codificação de caracteres do cabeçalho do \s-1PO.\s0 Se ele não tiver
sido definido, ele vai retornar \*(L"\s-1CHARSET\*(R".\s0
.IP "set_charset($)" 4
.IX Item "set_charset($)"
Isso define a codificação de caracteres do cabeçalho \s-1PO\s0 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 \*(L"\s-1CHARSET\*(R".\s0 Este valor não altera o comportamento
deste módulo, ele apenas é usado para preencher aquele campo no cabeçalho e
retorná\-lo em \fIget_charset()\fR.
.SH "AUTORES"
.IX Header "AUTORES"
.Vb 2
\& Denis Barbier <barbier@linuxfr.org>
\& Martin Quinson (mquinson#debian.org)
.Ve