PO4A(1p)

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

SINOPSE
po4a [opções] arquivo_config

DESCRIÇÃO
O objetivo do projeto po4a (PO for anything, ou PO para qualquer coisa) é facilitar traduções (e o mais interessante, a manutenção das traduções) usando as ferramentas do gettext em áreas em que não se esperava, 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.

Caso normal sem especificar pot_in:

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

 adendo ----------------------------------------------+
                                                      |
 documento mestre ----+----------------------------+  |
                      V                            +--+--> traduções
 arquivos PO antigos -+--> arquivos PO atualizados +
      ^                         |
      |                         V
      +<........................+
    (os arquivos 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:

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

 documento mestre ----+-----------------------------------+
                      :                                   |
 programa de          :    documento                      |
 filtragem    ========X..> mestre                         |
 externo                   filtrado                       |
                           |                              |
                           V                              +--> traduções
 arquivos PO antigos ------+----> arquivos PO atualizados +
      ^                             |
      |                             V
      +<............................+
    (os arquivos 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 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:

    <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

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

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>)* \
                  (pot_in:<doc_mestre_filtrado>)? \
                  (add_<lang>:<modificador>*<caminho_adendo>)*

Se pot_in for especificado, doc_mestre_filtrado será usado para criar o arquivo 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 arquivos 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 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] 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ê 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] t-05-config/test02_man.1 $lang:tmp/test02_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.

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

    ATENÇÃO: Esta opção muda o comportamento do po4a de uma maneira bastante drástica: seus arquivos 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
    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-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)

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