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

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:

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.

equals_msgid(po)

Retorna ($uptodate, $diagnostic) com $uptodate 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 $uptodate retornar falso, então os arquivos po podem ser alterados quando forem através do po4a-updatepo.

Se $uptodate for falso, então $diagnostic contém um diagnóstico de por que isto é assim.

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