| PO4A(1p) | Ferramentas Po4a | PO4A(1p) |
po4a - atualizar ambos os ficheiros PO e documentos traduzidos numa só vez
po4a [options] config_file
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.
Este documento está organizado da seguinte forma:
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
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.
Normal case without specifying pot_in:
<- source files ->|<--------- build results --------------->
addendum ----------------------------------+
|
master document --+---------------------+ |
V +--+--> translations
old PO files -----+--> updated PO files +
^ |
| V
+<.....................+
(the updated PO files are manually
copied to the source of the next
release while manually updating
the translation contents)
Special case with specifying pot_in:
<- source files ->|<--------- build results ----------------->
master document --+--------------------------+
: |
external : filtered |
filtering ========X..> master |
program document |
| |
V +--> translations
old PO files ----------+--> updated PO files +
^ |
| V
+<..........................+
(the updated PO files are manually
copied to the source of the next
release while manually updating
the translation contents)
The dataflow cannot be reversed in this tool, and changes in translations are overwritten by the content of the PO files. As a matter of fact, this tool cannot be used to convert existing translations to the po4a system. For that task, please refer to po4a-gettextize(1).
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 ;)
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.
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:
<lang>:<caminho para o ficheiro PO para este idioma>
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
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/
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 \
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
[type: docbook] doc/script.xml fr:doc/fr/script.xml \
de:doc/de/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: <format>] <master_doc> (<lang>:<localized_doc>)* \
(pot_in:<filtered_master_doc>)? \
(add_<lang>:<modifier>*<addendum_path>)*
If pot_in is specified, filtered_master_doc is used to create POT file instead of master_doc. This feature allows user to create flexible ways to avoid contents which shouldn't be included in the PO files. Tools such as C preprocessor (cpp) or XSL Transformation utility (e.g., xsltproc) can be used to create the external filtering program and call it before invoking po4a.
Se não houver um modificador, addendum_path é um caminho para uma adenda. Modificadores são
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
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.
If you need a specific option for one of the documents you want to translate, you can also specify it in the configuration file. Options are introduced by the opt keyword. The argument of the opt keyword must be quoted with double quotes if it contains a space (e.g. if you specify multiple options, or an option with an argument). You can also specify options that will only apply to a specific language by using the opt_lang keyword.
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: "..."
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.
This module alias can then be used like a regular module:
[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.
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.
If there are name conflicts because several files have the same filename, the name of the master file can be specified by adding a "master:file="name option:
[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
O comportamento padrão (quando --force não é especificado) é o seguinte:
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.
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.
WARNING: This flag changes the po4a behavior in a rather drastic way: your translated files will not get updated at all until the translation improves. Only use this flag if you prefer shipping an outdated translated documentation rather than only shipping an accurate untranslated documentation.
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.
Nota: $lang será estendida para o idioma atual.
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
Once this is set up you don't need to touch the Makefile when a new translation arrives, i.e. if the French team sends you fr.po and fr.add then you simply drop them respectively in man/po4a/po/ and man/po4a/add_fr/ and the next time the program is built the French translation is automatically build as well in 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
Fragmento de boas-vindas;)
po4a-gettextize(1), po4a-normalize(1), po4a-translate(1), po4a-updatepo(1), po4a(7)
Denis Barbier <barbier@linuxfr.org> Nicolas François <nicolas.francois@centraliens.net> Martin Quinson (mquinson#debian.org)
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).
| 2018-12-09 | Ferramentas Po4a |