LOCALE::PO4A::PO.3PM(1) | User Contributed Perl Documentation | LOCALE::PO4A::PO.3PM(1) |
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 ;)
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:
- 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
- ignored; the key is kept for backward computability.
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($)
- Retorna o tipo de msgid com a posição dada no documento. Provavelmente, isso só é útil para gettextização e é armazenado separadamente de {$msgid}{'type'} porque o local posterior pode ser substituído por outro tipo quando $msgid é duplicado no documento mestre.
- 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".
AUTORES
Denis Barbier <barbier@linuxfr.org> Martin Quinson (mquinson#debian.org)
2024-06-26 | perl v5.38.2 |