Ubuntu Manpages

po4a

atualiza ambos arquivos PO e documentações traduzidas em um tiro

po4a [opções] arquivo_config

A missão do projeto po4a (em inglês, PO for anything) é facilitar as traduções (e o mais interessante, a manutenção de traduções) usando ferramentas de gettext em áreas onde elas não eram esperadas, como documentação.

O programa po4a é útil, se você quer evitar chamar po4a-gettextize(1), po4a-updatepo(1) e po4a-translate(1) em Makefiles complexos quando você possui múltiplos arquivos para traduzir, formato diferente, ou precisa especificar opções diferentes para documentos diferentes.

Esse documento é organizado da seguinte forma:

SINTAXE DO ARQUIVO DE CONFIGURAÇÃO

Especificando os idiomas modelos

Especificando os caminhos para entradas do tradutor

Detecção automática dos caminhos e idiomas

Especificando os documentos para traduzir

Especificando opções para os módulos

Especificando alias

Modo dividido

COPYRIGHT E LICENÇA

O programa po4a está encarregado de atualizar ambos arquivos PO (para sincronizá-los aos documentos originais) e documentos traduzidos (para sincronizá-los aos arquivos PO). O ponto principal é tornar o uso do po4a mais fácil sem ter que lembrar as opções de linha de comando.

Ele também permite que você misture documentos com formatos diferentes no mesmo arquivo POT, de forma que tenha apenas um arquivo por projeto.

Esse comportamento pode ser copiado por outras ferramentas da suíte po4a (por exemplo, com Makefiles), mas isso é difícil de fazer e exaustivo de refazer os mesmos Makefiles complicados para cada projeto usando po4a.

O fluxo de dados pode ser resumido como mostrado a seguir. Quaisquer alterações no documento mestre serão refletidas nos arquivos PO e todas alterações nos arquivos PO (seja manual ou causado por etapas anteriores) vão ser refletidas nos documentos traduzidos.

 documento mestre --> arquivos PO --> traduções

O fluxo de dados não pode ser invertido nesta ferramenta e alterações nas traduções são sobrescritas pelo conteúdo dos arquivos PO. Na verdade, essa ferramenta não pode ser usada para converter traduções existentes ao sistema do po4a. Para essa tarefa, por favor veja o po4a-gettextize(1).

O argumento (obrigatório) é o arquivo de configuração a ser usado. Sua sintaxe mira em ser simples e perto dos arquivos de configuração usados pelos projetos do intl-tools.

Comentários nesses arquivos são anotados pelo caractere "#". Ele comenta tudo até o fim da linha. Linhas podem ser continuadas ao escapar o fima da linha. Todas as linhas não vazias podem iniciar com um comando [], seguido pelos seus argumentos. (parece difícil falando dessa forma, mas é bem fácil, espero! ;)

Nota: É recomendado o uso de [po_directory] ao invés de [po4a_langs] e [po4a_paths]. Veja a seção Detecção automática dos caminhos e idiomas abaixo.

Esse é um comando opcional que pode simplificar o processo de configuração como um todo, e vai tornar ele mais escalável. Você pode especificar uma lista de idiomas para os quais você deseja traduzir os documentos. Isso é tão simples quanto:

 [po4a_langs] fr de

Isso vai permitir que você expanda $lang para todos os idiomas especificados no resto do arquivo de configuração.

Nota: É recomendado o uso de [po_directory] ao invés de [po4a_langs] e [po4a_paths]. Veja a seção Detecção automática dos caminhos e idiomas abaixo.

Primeiro, você tem que especificar onde os arquivos de entrada do tradutor (i.e. os arquivos usados pelos tradutores para fazer seu trabalho) estão localizados. Isso pode ser feito por uma linha assim:

 [po4a_paths] doc/l10n/project.doc.pot \
              fr:doc/l10n/fr.po de:doc/l10n/de.po

O comando é assim [po4a_paths]. O primeiro argumento é o caminho para o arquivo POT para usar. Todos os argumentos subsequentes são da forma auto-explicativa:

    <lang>:<caminho para o arquivo PO para este idioma>

Se você definiu os idiomas modelos, você pode reescrever a linha acima dessa forma:

 [po4a_paths] doc/l10n/project.doc.pot $lang:doc/l10n/$lang.po

Você também pode usar $master para referir ao nome de arquivo do documento. Neste caso, po4a vai usar um modo dividido: um POT e um PO (para cada idioma) vão ser criados para cada documento especificado no arquivo de configuração do po4a. Veja a seção do Modo dividido.

 [po4a_paths] doc/$master/$master.pot $lang:doc/$master/$lang.po

Outro comando pode ser usado para especificar o nome de um diretório onde os arquivos PO e POT estão localizados. Quando ele é usado, po4a vai detectar o arquivo POT com o único arquivo *.pot do diretório especificado. po4a também vai ser usado na lista de arquivos *.po para definir a lista de idiomas (ao remover a extensão). Esses idiomas vão ser usados para a substituição da variável $lang no resto do arquivo de configuração.

Esse comando deveria não ser usado junto com os comandos [po4a_langs] ou [po4a_paths].

Quando usando esse comando, você tem que criar um arquivo POT vazio na primeira invocação de po4a para que ele saiba o nome do arquivo POT.

 [po_directory] po4a/po/

Agora, você normalmente tem que especificar quais documentos estão traduzidos, seus formatos e onde colocar as traduções. Isso pode ser feito por uma linha assim:

 [type: sgml] doc/my_stuff.sgml fr:doc/fr/mon_truc.sgml \
              de:doc/de/mein_kram.sgml
 [type: pod] script fr:doc/fr/script.1 de:doc/de/script.1 \
             add_fr:doc/l10n/script.fr.add

Isso também deveria ser auto-explicativa. Note que no segundo caso, doc/l10n/script.fr.add é um adendo para adicionar a versão em francês deste documento. Por favor, veja o po4a(7) para mais informações sobre os adendos.

Mais formalmente, o formato é:

 [type: <formato>] <doc_mestre> (<lang>:<doc_localizado>)* \
                  (add_<lang>:<modificador>*<caminho_adendo>)*

Se há nenhum modificador, addendum_path é um caminho para um adendo. Modificadores são

?
Inclua addendum_path se esse arquivo não existir, do contrário nada para fazer.
@
addendum_path não é um adendo regular, mas um arquivo contendo uma lista de adendos, uma por linha. Cada adendo pode ser precedido por modificadores.
!
addendum_path está descartado, ele não é carregado e não vai ser carregado por qualquer uma especificação de adendo.

Se você definiu os idiomas modelos, você pode reescrever a linha acima dessa forma:

 [type: pod] script $lang:doc/$lang/script.1 \
             add_fr:doc/l10n/script.fr.add

Se todos os idiomas possuíssem adendos com caminhos similares, você poderia também escrever alguma coisa como:

 [type: pod] script $lang:doc/$lang/script.1 \
             add_$lang:doc/l10n/script.$lang.add

po4a aceita opções que serão passadas para o módulo. Essas opções são especificas do módulo e são especificadas com a opção -o.

Se você precisar de uma opção específica para um dos documentos que deseja traduzir, você também pode especificá-lo no arquivo de configuração. Opções são introduzidas pela palavra-chave opt. O argumento da palavra-chave opt deve estar entre aspas duplas se contiver um espaço (ex.: se você especificar múltiplas opções ou uma opção com um argumento). Você também pode especificar opções que vão apenas aplicar a um idioma específico usando a palavra-chave opt_lang.

Aqui está um exemplo:
[type:man] data-05/test2_man.1 $lang:tmp/test2_man.$lang.1 \
opt:"-k 75" opt_it:"-L UTF-8" opt_fr:-v

Argumentos podem conter espaços se você usa aspas simples ou aspas escapadas ("):
[po4a_alias:man] man opt:"-o \"mdoc=NAME,SEE ALSO\" -k 20"

Se você quiser especificar as mesmas opções para muitos documentos, você pode querer usar um apelido/alias (veja a seção Especificando alias abaixo).

Você também pode definir opções para todos os documentos especificados no arquivo de configuração:
[opções] opt:"..." opt_fr:"..."

Se você deve especificar as mesmas opções para múltiplos arquivos, você pode se interessar na definição de um alias (apelido) de um módulo. Isso pode ser feito dessa forma:

 [po4a_alias:test] man opt:"-k 21" opt_es:"-o debug=splitargs"

Isso define um alias para um módulo chamado test, baseado no módulo man, com o -k 21 aplicado aos idiomas e com -o debug=splitargs aplicado para tradução em espanhol.

Esse alias de módulo pode, então, ser usado como um módulo normal:

 [type:test] data-05/test2_man.1 $lang:tmp/test2_man.$lang.1 \
            opt_it:"-L UTF-8" opt_fr:-v

Note que você pode especificar opções adicionais por arquivo.

O modo dividido ("split mode") é usado quando $master é usado na linha de [po4a_paths].

Quando o modo dividido for usado, um grande POT temporário e grandes POs temporários são usados. Isso permite compartilhar as traduções entre todos os POs.

Se dois POs possuem traduções diferentes para a mesma string, po4a vai marcar essa string como aproximada ("fuzzy") e vai enviar ambas traduções em todos os POs que contêm essa string. Então, quando um tradutor atualiza a tradução e remove a sinalização de aproximada em um PO, a tradução dessa string será atualizada em todos POs automaticamente.

Se há conflitos no nome porque vários arquivos possuem o mesmo nome de arquivo, o nome do arquivo mestre pode ser especificado adicionando uma opção "master:file="name:

 [po4a_langs] de fr ja
 [po4a_paths] l10n/po/$master.pot $lang:l10n/po/$master.$lang.po
 [type: xml] foo/gui.xml $lang:foo/gui.$lang.xml master:file=foo-gui
 [type: xml] bar/gui.xml $lang:bar/gui.$lang.xml master:file=bar-gui

Limite mínimo de porcentagem de tradução para manter (i.e. escrever) o arquivo resultante (padrão: 80). I.e. por padrão, arquivos têm que ser traduzido em pelo menos 80% para ser escrito.
Mostra uma mensagem de ajuda.
Conjunto de caracteres contendo os documentos para traduzir. Note que todos os documentos mestres deve usar o mesmo conjunto de caracteres por hora. Isso é uma limitação conhecida e nós estamos trabalhando para resolver isso.
Conjunto de caracteres dos arquivos contendo os documentos localizados. Note que todos os documentos traduzidos vão usar o mesmo conjunto de caracteres por hora. Essa é uma limitação conhecida e nós estamos trabalhando para resolver isso.
Conjunto de caracteres dos adendos. Note que todos os adendos deveriam ser do mesmo conjunto de caracteres.
Exibe a versão do script e sai.
Aumenta o nível de detalhamento do programa.
Reduz o nível de detalhamento do programa.
Imprime algumas informações de depuração.
Opções extras para passar o plug-in de formato. Especifique cada opção no formato "nome=valor". Veja a documentação de cada plug-in para mais informações sobre as opções válidas e seus significados.
Sempre gera os aquivos POT e PO, mesmo se po4a considera isso desnecessário.

O comportamento padrão (quando --force não é especificado) é o seguinte:

Se o arquivo POT já existe, ele é regerado se uma documentação mestre ou arquivo de configuração for mais recente. O POT também é escrito em um documento temporário e po4a certifica-se de que as alterações são realmente necessárias.

Também, uma tradução é gerada novamente apenas se seu documento mestre, o arquivo PO, um desses adendos ou arquivo de configuração é mais recente. Para evitar tentativa de gerar traduções que não passam no teste de limite (veja --keep), um arquivo com a extensão .po4a-stamp pode ser criada (veja --stamp).

Se um documento mestre inclui arquivos, você deveria usar a opção --force porque o horário de modificação desses arquivos incluídos não são levados em consideração.

Os arquivos PO são gerados novamente baseados no POT com msgmerge -U.

Informa ao po4a para criar arquivos stamp quando uma tradução não é gerada porque ela não atingiu o limite. Esses arquivos stamp são nomeados de acordo com o documento de tradução esperado, com a extensão .po4a-stamp.

Nota: Isso somente ativa a criação dos arquivos .po4a-stamp. Os arquivos stamp são sempre usados se existirem e eles são removidos com --rm-translations ou quando o arquivo é finalmente traduzido.

Não gera os documentos traduzidos, apenas atualiza os arquivos POT e PO.
Remove os arquivos de tradução (implica em --no-translations).
Essa opção não faz nada desde 0.41 e pode ser removida em versões posteriores.
Essa opção não faz nada desde 0.41 e pode ser removida em versões posteriores.
Traduz apenas o arquivo especificado. Pode ser útil para agilizar o processamento se um arquivo de configuração contém muitos arquivos. Note que essa opção não atualiza arquivos POT e PO. Essa opção pode ser usada múltiplas vezes.
Define uma variável que vai ser expandida no arquivo de configuração do po4a. Toda ocorrência de $(var) vai ser substituída por valor. Essa opção pode ser usada múltiplas vezes.
Define o diretório base para todos os documentos de entradas especificados no arquivo de configuração do po4a.
Define o diretório base para todos os documentos de saída especificados no arquivo de configuração do po4a.

OPÇÕES QUE MODIFICAM O CABEÇALHO DO POT

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.

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.
Define o detentor do copyright no cabeçalho do POT. O valor padrão é "Free Software Foundation, Inc."
Define o nome do pacote para o cabeçalho do POT. O padrão é "PACKAGE".
Define a versão do pacote do cabeçalho do POT. O padrão é "VERSION".

OPÇÕES PARA MODIFICAR ARQUIVOS PO

Extra options for msgmerge(1).

Nota: $lang vai estar estendida do idioma atual.

Essa opção remove --previous das opções passadas ao msgmerge. Isso permite Isso permite o suporte a versões do gettext antes de 0.16.
Essa opção adiciona --previous às opções passadas ao msgmerge. Isso requer gettext 0.16 ou posterior, e é ativada por padrão.

EXEMPLO

Vamos presumir que você mantém um programa chamado foo, o qual possui uma página de manual man/foo.1, a qual naturalmente é mantida em inglês somente. Agora você, como o mantenedor upstream ou downstream, quer criar e manter a tradução. Primeiro você precisa criar o arquivo POT necessário para enviar os tradutores usando po4a-gettextize(1).

Então, para o nosso caso, chamaríamos

 cd man && po4a-gettextize -f man -m foo.1 -p foo.pot

Você iria, então, enviar esse arquivo para as listas de idiomas apropriadas ou oferecê-lo para download em algum lugar na sua página web.

Agora, vamos presumir que você recebeu três traduções antes de seu próximo lançamento: de.po (includindo um adendo de.add), sv.po e pt.po. Considerando que você não quer alterar seu Makefile(s) quando uma nova tradução aparece, você pode usar o po4a com um arquivo de configuração apropriada em seu Makefile. Vamos chamá-lo de po4a.cfg. Em nosso exemplo, ele se pareceria com o seguinte:

 [po_directory] man/po4a/po/
 [type: man] man/foo.1 $lang:man/translated/$lang/foo.1 \
            add_$lang:?man/po4a/add_$lang/$lang.add opt:"-k 80"

Neste exemplo, nós presumimos que suas páginas de manual geradas (e todos os arquivos PO e de adendos) deveriam estar armazenadas em man/translated/$lang/ (respectivamente em man/po4a/po/ e man/po4a/add_$lang/) abaixo do diretório atual. Em nosso exemplo, o diretório de man/po4a/po/ iria incluir de.po, pt.po e sv.po, e o diretório de man/po4a/add_de/ iria incluir de.add.

Note que o uso do modificador ? em apenas tradução em alemão (de.po) é acompanhada por um adendo.

Para atualmente compilar as páginas de manual traduzidas você iria, então, adicionar (uma só vez!) a seguinte linha no alvo build do Makefile apropriado:

        po4a po4a.cfg

Assim que isso estiver sido configurado, você não precisa tocar no Makefile quando uma nova tradução aparecer , i.e. se o time francês enviar a você fr.po e fr.add, você iria simplesmente colocá-las respectivamente em man/po4a/po/ e man/po4a/add_fr/ e o a próxima vez que o programa for compilado, a tradução em francês também será compilada automaticamente em man/translated/fr/.

Note que você ainda precisaria de um alvo apropriado para instalar páginas de manuais localizados com os em inglês.

Finalmente, se você não armazena arquivos gerados em seu sistema de controle de versão, você vai precisar de uma linha em seu alvo clean também:
-rm -rf man/translated

  • Duplica alguns códigos com os programas po4a-*.

Patches são bem-vindos! ;)

po4a-build(1), po4a-gettextize(1), po4a-normalize(1), po4a-translate(1), po4a-updatepo(1), po4a-build.conf(5), po4a(7)

 Denis Barbier <barbier@linuxfr.org>
 Nicolas François <nicolas.francois@centraliens.net>
 Martin Quinson (mquinson#debian.org)

Copyright 2002-2012 por SPI, inc.

Esse programa é um software livre; você pode redistribuí-lo e/ou modificá-lo sob os termos da GPL (veja o arquivo COPYING).