Ubuntu Manpage: po4a - atualizar ambos os ficheiros PO e documentos traduzidos numa só vez

NOME

       po4a - atualizar ambos os ficheiros PO e documentos traduzidos numa só vez

SINOPSE

       po4a [options] config_file

DESCRIÇÃO

       O objetivo do projeto po4a (PO para tudo) é facilitar traduções (e mais interessante, a
       manutenção das traduções) usando ferramentas gettext em áreas onde eles não eram esperados
       como documentação.

       O programa po4a é útil se você quiser evitar a chamada po4a-gettextize(1),
       po4a-updatepo(1), e po4a-translate(1) no complexo Makefiles quando você tem vários
       ficheiros para traduzir, de formato diferente, ou a necessidade de especificar diferentes
       opções para diferentes documentos.

Tabela de conteúdo

       Este documento está organizado da seguinte forma:

   DESCRIÇÃO
   INTRODUÇÃO
   SINTAXE DE FICHEIROS DE CONFIGURAÇÃO
       Especificando as línguas modelo

       Especificando o caminho para entradas do tradutor

       Deteção automática dos caminhos e linguagens

       Especificando os documentos para traduzir

       Especificar opções para os módulos

       Especificando aliases

       Modo de divisão

   OPÇÕES
   EXEMPLO
   DEFICIÊNCIAS
   VER TAMBÉM
   AUTORES
   DIREITOS DE AUTOR E LICENÇA

INTRODUÇÃO

       O programa po4a é responsável pela atualização tanto dos ficheiros PO (para sincronizá-los
       com os documentos originais) como dos documentos traduzidos (para sincronizá-los para os
       ficheiros PO). O ponto principal é tornar mais fácil o uso do po4a sem ter que se lembrar
       das opções de linha de comando.

       Ele também permite que você misture os documentos tendo formatos diferentes no mesmo
       ficheiro POT para que possa ter apenas um ficheiro por projeto.

       Este comportamento pode ser imitado por outras ferramentas da suite po4a (por exemplo com
       Makefiles), mas é um pouco difícil de fazer, e cansativo refazer o mesmo complicado
       Makefiles para cada projeto usando po4a.

       O fluxo de dados pode ser resumido como a seguir. Quaisquer alterações ao documento
       principal será refletida nos ficheiros PO, e todas as alterações aos ficheiros PO (manual
       ou causada por etapa anterior) será refletido nos documentos de tradução.

       Caso normal sem especificar pot_in:

        <- ficheiros fontes ->|<-------- resultados de compilação --------->

        adendo ----------------------------------------------+
                                                             |
        documento mestre ----+----------------------------+  |
                             V                            +--+--> traduções
        ficheiros PO antigos -+--> ficheiros PO atualizados +
             ^                         |
             |                         V
             +<........................+
           (os ficheiros PO atualizados são copiados
            manualmente para o código-fonte do
            próximo lançamento enquanto atualiza
            manualmente o conteúdo da tradução)

       Caso especial especificando pot_in:

        <- ficheiros fontes ->|<--------- resultados de compilação ------------>

        documento mestre ----+-----------------------------------+
                             :                                   |
        programa de          :    documento                      |
        filtragem    ========X..> mestre                         |
        externo                   filtrado                       |
                                  |                              |
                                  V                              +--> traduções
        ficheiros PO antigos ------+----> ficheiros PO atualizados +
             ^                             |
             |                             V
             +<............................+
           (os ficheiros PO atualizados são copiados
            manualmente para o código-fonte do
            próximo lançamento enquanto atualiza
            manualmente o conteúdo da tradução)

       O fluxo de dados não pode ser revertido nesta ferramenta e alterações nas traduções são
       sobrescritas pelo conteúdo dos ficheiros 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 DE FICHEIROS DE CONFIGURAÇÃO

O argumento (obrigatório) é o caminho para o ficheiro de configuração a usar. A sua
sintaxe pretende ser simples e perto dos ficheiros de configuração usados pelos projetos
intl-tools.

Comentários nestes ficheiros são anotados pelo caratere '#'. Comenta tudo até ao fim da
linha. As linhas podem ser continuadas por escapar do fim da linha. Todas as linhas não em
branco devem começar com um comando [], seguido pelos seus argumentos. (parece difícil
dizer desta maneira, mas é bastante fácil, espero ;)

Especificando as línguas modelo
Note: Recomenda-se utilizar [po_directory] em vez de [po4a_langs] e [po4a_paths]. Ver
secção Detecção automática dos caminhos e linguagens abaixo.

Este é um comando opcional que pode simplificar todo o ficheiro de configuração, e irá
torná-lo mais escalável. Você tem que especificar uma lista das línguas em que deseja
traduzir os documentos. Isto é tão simples como:

[po4a_langs] fr de

Isto irá permitir-lhe expandir $lang para todos os idiomas especificados no resto do
ficheiro de configuração.

Especificando o caminho para entradas do tradutor
Note: Recomenda-se utilizar [po_directory] em vez de [po4a_langs] e [po4a_paths]. Ver
secção Detecção automática dos caminhos e linguagens abaixo.

Primeiro, você tem que especificar onde os ficheiros de entrada do tradutor (ou seja, os
ficheiros utilizado pelos tradutores para fazer o seu trabalho) estão localizados. Isso
pode ser feito por uma tal linha:

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

O comando é portanto [po4a_paths]. O primeiro argumento é o caminho para o ficheiro POT a
usar. Todos os argumentos subsequentes são em forma auto-explicativa:

Se você definiu as línguas de modelo, pode reescrever a linha acima desta forma:

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

Você também pode usar $master para se referir ao nome do documento. Neste caso, po4a vai
usar um modo de divisão: um POT e um PO (para cada idioma) será criado para cada documento
especificado no ficheiro de configuração po4a. Veja a secção Split mode.

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

Deteção automática dos caminhos e linguagens
Outro comando pode ser usado para especificar o nome de um diretório onde os ficheiros PO
e POT estão localizados. Quando é usado, po4a irá detectar o ficheiro POT como o único
*.pot ficheiro do diretório especificado. po4a também vai usar a lista de *.po ficheiros
para definir a lista de idiomas (removendo para fora a extensão). Estas idiomas serão
utilizados para a substituição da $lang variável no resto do ficheiro de configuração.

Este comando não deve ser usado em conjunto com os comandos [po4a_langs] ou [po4a_paths].

Ao usar este comando, você tem que criar um ficheiro POT vazio na primeira invocação de
po4a para deixá-lo saber o nome do ficheiro POT.

[po_directory] po4a/po/

Especificando os documentos para traduzir
Agora você naturalmente tem que especificar que documentos são traduzidos, o seu formato,
e onde colocar as traduções. Isso pode ser feita por tais linhas:

[type: sgml] doc/my_stuff.sgml fr:doc/fr/mon_truc.sgml \
pt_BR:doc/pt_BR/minhas_coisas.sgml
[type: pod] script fr:doc/fr/script.1 pt_BR:doc/pt_BR/script.1 \
add_fr:doc/l10n/script.fr.add
[type: docbook] doc/script.xml fr:doc/fr/script.xml \
pt_BR:doc/pt_BR/script.xml \
pot_in:doc/script.filtered.xml

Isto deve ser também bastante auto-explicativo. Note-se que, no segundo caso,
doc/l10n/script.fr.add é uma adenda para adicionar à versão francesa deste documento. Por
favor, consulte po4a(7) para obter mais informações sobre adendas.

Mais formalmente, o formato é:

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

Se pot_in for especificado, doc_mestre_filtrado será usado para criar o ficheiro POT em
vez de doc_mestre. Esse recurso permite que o usuário crie maneiras flexíveis para evitar
conteúdos que não devem ser incluídos nos ficheiros PO. Ferramentas como o pré-processador
C (cpp) ou o utilitário XSL Transformation (por exemplo, xsltproc) podem ser usadas para
criar o programa de filtragem externo e chamá-lo antes de invocar po4a.

Se não houver um modificador, addendum_path é um caminho para uma adenda. Modificadores
são

? Incluir addendum_path se este ficheiro existir, caso contrário não fazer nada.

@ addendum_path não é uma adenda regular, mas um ficheiro contendo uma lista de adendas,
uma por linha. Cada adenda pode ser precedida de modificadores.

! addendum_path é descartado, não é carregado e não será carregado por qualquer
especificação de adenda.

Se você definiu as línguas de modelo, pode reescrever a linha acima desta forma:

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

Se todos os idiomas tinham adendas com caminhos semelhantes, você também pode escrever
algo como:

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

Especificar opções para os módulos
po4a aceita opções que serão passadas para o módulo. Estas opções são módulos específicos
e são especificados com a troca -o.

Se você precisar de uma opção específica para um dos documentos que deseja traduzir, você
também pode especificá-lo no ficheiro 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] t-05-config/test02_man.1 $lang:tmp/test02_man.$lang.1 \
opt:"-k 75" opt_it:"-L UTF-8" opt_fr:-v

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

Se você quer especificar as mesmas opções para muitos documentos, pode querer usar um
alias (consulte a secção abaixo Specifying aliases).

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

Especificando aliases
Se você deve especificar as mesmas opções para vários ficheiros, pode estar interessado em
definir um módulo alias. Isto pode ser feito desta forma:

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

Isto define um módulo alias denominado test, com base no módulo man, com o -k 21 aplicado
a todas as línguas e com -o debug=splitargsaplicada à tradução espanhola.

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

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

Note que pode especificar opções adicionais num ficheiro por base.

Modo de divisão
O modo de divisão é usado quando $master é usado na linha [po4a_paths].

Quando o modo de divisão é usado, um temporário e grande POT e um grande POs são
utilizados. Isto permite compartilhar as traduções entre todos POs.

Se dois POs tiverem traduções diferentes para a mesma sequência, po4a irá marcar essa
sequência como imprecisa e apresentará duas traduções em todos os POs que contêm essa
sequência. Então, quando um tradutor atualiza a tradução e remove o comando impreciso num
PO, a tradução dessa sequência será atualizada automaticamente em cada POs.

Se há conflitos no nome porque vários ficheiros possuem o mesmo nome de ficheiro, o nome
do ficheiro 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 ficheiro
resultante (padrão: 80). I.e. por padrão, ficheiros têm que ser traduzido em pelo
menos 80% para ser escrito.

-h, --help
Mostrar uma pequena mensagem de ajuda.

-M, --master-charset
Conjunto de carateres dos ficheiros contendo os documentos para traduzir. Note-se que
todos documentos mestre devem usar o mesmo conjunto de carateres por agora. Esta é uma
limitação conhecida, e estamos a trabalhar para resolver isso.

-L, --localized-charset
Conjunto de carateres dos ficheiros contendo os documentos localizados. Note-se que
todos documentos traduzidos usarão o mesmo conjunto de carateres por agora. Esta é uma
limitação conhecida, e estamos a trabalhar para resolver isso.

-A, --addendum-charset
Conjunto de carateres da adenda. Note-se que todas as adendas devem estar no mesmo
conjnto de carateres.

-V, --version
Mostrar a versão do script e sair

-v, --verbose
Aumentar o detalhe do programa.

-q, --quiet
Diminuir o detalhe do programa.

-d, --debug
Saída de alguma informação de depuração.

-o, --option
Opção(s) extra para passar para o formato em modo de extensão. Especificar cada opção
no formato 'name=value'. Consulte a documentação de cada modo de extenção para mais
informações sobre as opções válidas e seus significados.

-f, --force
Gera sempre os ficheiros POT e PO, mesmo se po4a considera que não é necessário.

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

Se o ficheiro POT já existe, ele é regenerado se um documento mestre ou o ficheiro
de configuração é mais recente. O ficheiro POT também é escrito num documento
temporário e po4a verifica que as mudanças são realmente necessárias.

Além disso, uma tradução é regenerada somente se o seu documento mestre, o
ficheiro PO, uma das suas adendas ou o ficheiro de configuração é mais recente.
Para evitar tentar regenerar traduções que não passam no teste de limite (ver
--keep), um ficheiro com a extensão .po4a-stamp pode ser criado (ver --stamp).

Se um documento mestre inclui ficheiros, você deve usar a flag --force porque o tempo
de modificação dos ficheiros incluídos não são tomados emconta.

Os ficheiros PO são sempre regenerados com base em POT com msgmerge -U.

--stamp
Diz po4a para criar ficheiros de informação quando uma tradução não é gerada porque
não atingiu o limiar. Esses ficheiros de informação são nomeados de acordo com o
documento traduzido esperado, com a extensão .po4a-stamp.

Nota: Isso só ativa a criação dos ficheiros .po4a-stamp. Os ficheiros de informação
são sempre utilizados se existirem, e são removidos com --rm-translations ou quando o
ficheiro é finalmente traduzido.

--no-translations
Não gerar os documentos traduzidos, apenas atualizar os ficheiros POT e PO.

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

--keep-translations
Mantém os ficheiros de tradução existentes mesmo se a tradução não atender o limite
especificado por --keep. Essa opção não cria novos ficheiros de tradução com pouco
conteúdo, mas vai salvar traduções existentes que cujo nível decai por causa de
alterações nos ficheiros de mestre.

ATENÇÃO: Esta opção muda o comportamento do po4a de uma maneira bastante drástica:
seus ficheiros traduzidos não serão atualizados até que a tradução melhore. Use esta
opção somente se você preferir enviar uma documentação traduzida desatualizada em vez
de enviar apenas uma documentação não traduzida precisa.

--rm-translations
Remover os ficheiros traduzidos (implica --no-translations).

--no-backups
Esta flag não faz nada desde 0.41, e pode ser removida em versões posteriores.

--rm-backups
Esta flag não faz nada desde 0.41, e pode ser removida em versões posteriores.

--translate-only translated-file
Traduzir apenas o ficheiro especificado. Pode ser útil para acelerar o processamento
se um ficheiro de configuração contém muitos ficheiros. Note que o que esta opção faz
não é possível atualizar ficheiros PO e POT. Esta opção pode ser usada várias vezes.

--variable var=value
Definir uma variável que será expandida no ficheiro de configuração po4a.Cada
ocorrência de $(var) será substituída por value. Esta opção pode ser usada várias
vezes.

--srcdir SRCDIR
Definir o diretório de base para todos os documentos de entrada especificados no
ficheiro de configuração po4a.

--destdir DESTDIR
Definir o diretório base para todos os documentos de saída especificados no ficheiro
de configuração po4a.

OPÇÕES QUE MODIFICAM O CABEÇALHO POT
--porefs type[,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 ficheiro 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).

O argumento pode ser seguido por uma vírgula ou pela palavra-chave wrap ou nowrap.
Referências são escritas por padrão em uma única linha. A opção wrap envolve
referências sobre várias linhas, para imitar as ferramentas gettext (xgettext e
msgmerge). Esta opção irá tornar-se o padrão num lançamento futuro, porque é mais
sensível. A opção nowrap é acessível para os utilizadores que querem manter o
comportamento antigo.

--msgid-bugs-address email@address
Definir o endereço do relatório para msgid bugs. Por padrão, os ficheiros POT criados
não têm campos Report-Msgid-bugs-To.

--copyright-holder string
Definir o titular dos direitos de autor no cabeçalho POT. O valor padrão é " Free
Software Foundation, Inc."

--package-name string
Definir o nome do pacote para o cabeçalho POT. O padrão é "PACOTE".

--package-version string
Definir o nome do pacote para o cabeçalho POT. O padrão é "VERSÃO".

OPÇÕES PARA MODIFICAR FICHEIROS PO
--msgmerge-opt options
Opções extra para msgmerge(1).

Nota: $lang será estendida para o idioma atual.

--no-previous
Esta opção remove --previous a partir das opções passadas para B <msgmerge> Isto
permite suportar versões do gettext mais cedo do que 0.16.

--previous
Esta opção acrescenta --previous ás opções passadas para msgmerge. Isso requer gettext
0.16 ou posterior, e é ativado por padrão.

EXEMPLO
Vamos supor que você mantém um programa chamado foo que tem uma página do manual man/foo.1
que naturalmente, é mantida apenas em Inglês. Agora você como gestor do upstream ou
downstream quer criar e manter a tradução. Primeiro precisa criar o ficheiro POT
necessário para enviar para 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ê teria então que enviar este ficheiro para as listas de idiomas adequadas ou
oferecê-lo para descarregar em algum lugar do seu site.

Agora, vamos supor que você recebeu três traduções antes do seu próximo lançamento: de.po
(incluindo uma adenda de.add), sv.po e pt.po. Desde que não queira mudar o seu Makefile(s)
sempre que uma nova tradução chega, pode usar po4a com um ficheiro de configuração
apropriado no seu Makefile. Vamos chamá-lo po4a.cfg. No nosso exemplo seria algo como 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, vamos supor que suas páginas de manual geradas (e todos ficheiros PO e
adendas) devem ser armazenadas em man/translated/$lang/ (respectivamente em man/po4a/po/ e
man/po4a/add_$lang/) abaixo do diretório atual. No nosso exemplo o diretório man/po4a/po/
incluiria de.po, pt.po e sv.po, e o diretório man/po4a/add_de/ incluiria F <de.add>.

Observe o uso do modificador ? apenas como a tradução alemã (de.po) é acompanhado por uma
adenda.

Para realmente construir as páginas do manual traduzidas você então (uma vez!) adiciona a
seguinte linha no ponto 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 precisa de um destino apropriado para instalar páginas do manual
localizadas em Inglês.

Finalmente, se você não armazenar ficheiros gerados no seu sistema de controlo de versão,
vai precisar de uma linha no seu ponto clean bem como:
-rm -rf man/translated

DEFICIÊNCIAS

       •   Duplicar algum código com os programas po4a-*.

       Fragmento de boas-vindas;)

VER TAMBÉM

       po4a-gettextize(1), po4a-normalize(1), po4a-translate(1), po4a-updatepo(1), po4a(7)

AUTORES

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

DIREITOS DE AUTOR E LICENÇA

       Direitos de Autor 2002-2012 por SPI, inc.

       Este programa é software livre, você pode redistribuí-lo e/ou modificá-lo sob os termos da
       GPL (consulte o ficheiro CÓPIA).