.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" 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 "2020-08-19" "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
Para uma descrição mais completa do catálogo de mensagens no formato \s-1PO\s0 e
seu uso, por favor veja a documentação info do programa gettext. (nó
\&\*(L"`Arquivos \s-1PO\*(R"\s0').
.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 man, 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 \fItipo\fR" 4
.IX Item "--porefs tipo"
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
arquivo sem o número de linha, \fBcounter\fR para substituir os números de
linha aumentando o contador e \fBfull\fR para incluir referências
completas. (padrão: full).
.IP "\fB\-\-wrap\-po\fR \fBno\fR|\fBnewlines\fR|\fInumber\fR (padrão: 76)" 4
.IX Item "--wrap-po no|newlines|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.
.Sp
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 \fBnewlines\fR, o
po4a dividirá apenas o msgid e o msgstr após as novas linhas no conteúdo. Se
definido como \fBno\fR, 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.
.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 strings.
.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 "Funções relativas a catálogos de mensagens inteiros"
.IX Header "Funções relativas a catálogos de mensagens inteiros"
.IP "\fBnew()\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 \fBpo4a\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 "\fBto_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 "\fBstats_get()\fR" 4
.IX Item "stats_get()"
Retorna estatísticas sobre a proporção de acerto do gettext desde a última
vez que \fBstats_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 "\fBstats_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 "\fBcount_entries()\fR" 4
.IX Item "count_entries()"
retorna o número de entradas no catálogo (sem o cabeçalho).
.IP "\fBcount_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 "equals_msgid(po)" 4
.IX Item "equals_msgid(po)"
Retorna ($uptodate, \f(CW$diagnostic\fR) com \f(CW$uptodate\fR 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 \f(CW$uptodate\fR retornar falso, então os arquivos po
podem ser alterados quando forem através do \fBpo4a\-updatepo\fR.
.Sp
Se \f(CW$uptodate\fR for falso, então \f(CW$diagnostic\fR contém um diagnóstico de por que
isto é assim.
.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 "\fBget_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-1UTF\-8\*(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-1UTF\-8\*(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 \fBget_charset()\fR.
.SH "AUTORES"
.IX Header "AUTORES"
.Vb 2
\& Denis Barbier <barbier@linuxfr.org>
\& Martin Quinson (mquinson#debian.org)
.Ve