Provided by: po4a_0.47-2_all 
NOME
Locale::Po4a::Po - módulo para manipulação de arquivos PO
SINOPSE
use Locale::Po4a::Po;
my $pofile=Locale::Po4a::Po->new();
# Lê um arquivo PO
$pofile->read('arquivo.po');
# Adiciona uma entrada
$pofile->push('msgid' => 'Hello', 'msgstr' => 'bom dia',
'flags' => "wrap", 'reference'=>'file.c:46');
# Extrai uma tradução
$pofile->gettext("Hello"); # retorna "bom dia"
# Escreve de volta em um arquivo
$pofile->write('outroarquivo.po');
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 po), você pode
compilar novas entradas em tempo real ou requisitar a tradução de uma string.
For a more complete description of message catalogs in the PO format and their use, please
refer to the info documentation of the gettext program (node "`PO Files"').
Este módulo é parte do projeto po4a, cujo objetivo é usar arquivos PO (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.
OPÇÕES ACEITAS POR ESTE MÓDULO
--porefs type[,wrap|nowrap]
Especifica o formato de referência. O argumento tipo pode ser um de: none para não
produzir qualquer referência, noline para não especificar o número de linha (mais
precisamente, todos os números de linhas são substituídas por 1), counter para
substituir um número de linha aumentando o contador e full para incluir referências
completas.
Argumento pode estar seguido por uma vírgula e as palavras-chaves wrap ou nowrap.
Referências são escritas por padrão em uma única linha. A opção wrap quebra as
referências em várias linhas, para copiar as ferramentas do gettext (xgettext e
msgmerge). Essa opção vai se tornar o padrão em um lançamento futuro, mas ela é mais
sensível. A opção nowrap está disponível de forma que usuários que desejarem manter o
comportamento antigo podem fazê-lo.
--msgid-bugs-address e-mail@endereço
Define o endereço para relatórios de erros em msgids. Por padrão, os arquivos POT
criados possuem nenhum campo Report-Msgid-Bugs-To.
--copyright-holder string
Define o detentor do copyright no cabeçalho do POT. O valor padrão é "Free Software
Foundation, Inc."
--package-name string
Define o nome do pacote para o cabeçalho do POT. O padrão é "PACKAGE".
--package-version string
Define a versão do pacote do cabeçalho do POT. O padrão é "VERSION".
Functions concerning entire message catalogs
new()
Cria uma nova mensagem de catálogo. Se for fornecido um argumento, é o nome de um
arquivo PO que nós devemos carregar.
read($)
Lê um arquivo PO (cujo nome é fornecido como argumento). Entradas previamente
existentes nele não são removidas, sendo as novas adicionadas ao final do catálogo.
write($)
Escreve o catálogo atual no arquivo fornecido.
write_if_needed($$)
Similar ao "write", mas se o arquivo PO ou POT 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 POT apenas para atualizar uma linha de
referência ou o campo POT-Creation-Date).
gettextize($$)
Esta função produz um catálogo de mensagens traduzido de dois catálogos, um original e
uma traduzido. Este processo é descrito no po4a(7), seção Gettextização: como ela
funciona?.
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.
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.
Tem vezes que eu adoro Perl ;)
to_utf8()
Re-codifica para UTF-8 as "msgstr"s do PO. Faz nada se a codificação de caracteres não
tiver sido especificada no arquivo PO (valor "CHARSET") ou se ele já for UTF-8 ou
ASCII.
Funções para usar um catálogo de mensagens para traduções
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.
Após a string para ser traduzida, você pode passar um hash de argumentos extras. Aqui
estão as entradas válidas:
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.
wrapcol
a coluna na qual nós deveríamos dimensionar (padrão: 76).
stats_get()
Retorna estatísticas sobre a proporção de acerto do gettext desde a última vez que
stats_clear() 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 PO,
enquanto msgfmt relata o estado do arquivo. Exemplo de uso:
[um uso do arquivo PO para traduzir coisas]
($percent,$hit,$queries) = $pofile->stats_get();
print "Até agora, nós encontramos traduções para $percent\% ($hit de $queries) da strings.\n";
stats_clear()
Limpa as estatísticas sobre os acertos do gettext.
Funções para compilar um catálogo de mensagem
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:
msgid
a string no idioma original.
msgstr
a tradução.
reference
uma indicação de onde esta string foi encontrada. Exemplo: file.c:46 (significa em
"file.c" na linha 46). Ela pode ser uma lista separada por espaço no caso de
múltiplas ocorrências.
comment
um comentário adicionado aqui manualmente (pelos tradutores). Este formato é
livre.
automatic
um comentário que foi adicionado automaticamente pelo programa de extração de
strings. Veja a opção --add-comments no programa xgettext para mais informações.
flags
lista separada por espaço de todas as opções definidas para esta entrada.
Opções válidas são: c-text, python-text, lisp-text, elisp-text, librep-text,
smalltalk-text, java-text, awk-text, object-pascal-text, ycp-text, tcl-text, wrap,
no-wrap e fuzzy.
Veja a documentação do gettext para ver seu significado.
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 PO 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 PO é fornecido
um tipo, baseado em sua estrutura (como "chapt", "sect1", "p" 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.
Esta informação é escrita como um comentário automático no arquivo PO já que isso
fornece aos tradutores algum contexto sobre as strings para traduzir.
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.
Esta informação é escrita no arquivo PO usando as opções wrap ou no-wrap.
wrapcol
a coluna na qual nós deveríamos dimensionar (padrão: 76).
Esta informação não é escrita no arquivo PO.
Funções diversas
count_entries()
retorna o número de entradas no catálogo (sem o cabeçalho).
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.
msgid($)
retorna o msgid do número fornecido.
msgid_doc($)
retorna o msgid com a posição fornecida no documento.
get_charset()
retorna a codificação de caracteres do cabeçalho do PO. Se ele não tiver sido
definido, ele vai retornar "CHARSET".
set_charset($)
Isso define a codificação de caracteres do cabeçalho PO 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
"CHARSET". Este valor não altera o comportamento deste módulo, ele apenas é usado para
preencher aquele campo no cabeçalho e retorná-lo em get_charset().
AUTORES
Denis Barbier <barbier@linuxfr.org>
Martin Quinson (mquinson#debian.org)