Ubuntu Manpage: po4a - atualiza ambos arquivos PO e documentações traduzidas em um tiro

NOME

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

SINOPSE

       po4a [opções] arquivo_config

DESCRIÇÃO

       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.

Sumário

       Esse documento é organizado da seguinte forma:

   DESCRIÇÃO
   INTRODUÇÃO
   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

   OPÇÕES
   EXEMPLO
   PROBLEMAS
   VEJA TAMBÉM
   AUTORES
   COPYRIGHT E LICENÇA

INTRODUÇÃO

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

SINTAXE DO ARQUIVO DE CONFIGURAÇÃO

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! ;)

Especificando os idiomas modelos
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.

Especificando os caminhos para entradas do tradutor
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:

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

Detecção automática dos caminhos e idiomas
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/

Especificando os documentos para traduzir
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

Especificando opções para os módulos
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:"..."

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

Modo dividido
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

OPÇÕES

-k, --keep
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.

-h, --help
Mostra uma mensagem de ajuda.

-M, --master-charset
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.

-L, --localized-charset
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.

-A, --addendum-charset
Conjunto de caracteres dos adendos. Note que todos os adendos deveriam ser do mesmo
conjunto de caracteres.

-V, --version
Exibe a versão do script e sai.

-v, --verbose
Aumenta o nível de detalhamento do programa.

-q, --quiet
Reduz o nível de detalhamento do programa.

-d, --debug
Imprime algumas informações de depuração.

-o, --option
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.

-f, --force
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.

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

--no-translations
Não gera os documentos traduzidos, apenas atualiza os arquivos POT e PO.

--rm-translations
Remove os arquivos de tradução (implica em --no-translations).

--no-backups
Essa opção não faz nada desde 0.41 e pode ser removida em versões posteriores.

--rm-backups
Essa opção não faz nada desde 0.41 e pode ser removida em versões posteriores.

--translate-only arquivo-traduzido
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.

--variable var=valor
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.

--srcdir SRCDIR
Define o diretório base para todos os documentos de entradas especificados no arquivo
de configuração do po4a.

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

OPÇÕES PARA MODIFICAR ARQUIVOS PO
--msgmerge-opt opções
Extra options for msgmerge(1).

Nota: $lang vai estar estendida do idioma atual.

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

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

PROBLEMAS

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

       Patches são bem-vindos! ;)

VEJA TAMBÉM

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

AUTORES

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

COPYRIGHT E LICENÇA

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