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.

--no-update
Não altere os arquivos POT e PO, apenas a tradução pode ser atualizada.

--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 tipo[,wrap|nowrap]
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).

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
Opções extras para 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).

Ferramentas do Po4a                                2017-08-26                                           PO4A(1p)