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.

Para uma descrição mais completa do catálogo de mensagens no formato PO e seu uso, por favor veja a documentação info do programa gettext. (nó "`Arquivos PO"').

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 man, manual info), descrição de pacotes, modelos de debconf e tudo que pode se beneficiar dele.

OPÇÕES ACEITAS POR ESTE MÓDULO

--porefs tipo

Especifica o formato de referência. O argumento tipo pode ser um de: never para não produzir qualquer referência, file para especificar o arquivo sem o número de linha, counter para substituir os números de linha aumentando o contador e full para incluir referências completas. (padrão: full).

--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.

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 newlines, o po4a dividirá apenas o msgid e o msgstr após as novas linhas no conteúdo. Se definido como no, 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.

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.

--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".

Funções relativas a catálogos de mensagens inteiros

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).

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:

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:

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.

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 $msgid is duplicated in the master document.

get_charset()

retorna a codificação de caracteres do cabeçalho do PO. Se ele não tiver sido definido, ele vai retornar "UTF-8".

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 "UTF-8". 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)