Locale::Po4a::Xml - converte documentos XML e derivados de/para ficheiros PO
O objetivo do projeto po4a (PO for anything: PO para qualquer coisa) é
facilitar traduções (e o mais interessante, a
manutenção das traduções) a usar as ferramentas do
gettext em áreas em que não se esperava, como na
documentação.
Locale::Po4a::Xml é um módulo para ajudar a tradução
de documentos XML em outro idioma [humano]. Também pode ser usado como
uma base para a construção de módulos de documentos com
base em XML.
Este módulo pode ser usado diretamente para lidar com documentos XML
genéricos. Isto irá extrair todo o conteúdo das etiquetas
e, não atributos, já que é onde o texto é escrito
na maioria dos documentos com base XML.
Existem algumas opções (descrito na próxima
secção), que podem personalizar este comportamento. Se isto
não se encaixa no seu formato de documento que está encorajado a
escrever o seu próprio módulo derivado deste, para descrever os
detalhes do seu formato. Consulte a secção
WRITING DERIVATE
MODULES abaixo, para descrição do processo.
A opção de depuração global faz com que este
módulo mostre as cadeia excluídas, para ver se ele ignora algo
importante.
Estas são as opções particulares deste módulo:
- nostrip
- Impede-o para tirar os espaços em torno das cadeias
extraídas.
- wrap
- Canoniza a cadeia para traduzir, a considerar que
espaços em branco não são importantes e dimensiona o
documento traduzido. Essa opção pode ser sobrescrita por
opções personalizadas de marcação. Veja a
opção translated abaixo.
- unwrap_attributes
- Atributos são quebrados por
predefinição. Essa opção desativa a
quebra.
- caseinsensitive
- Faz as etiquetas e atributos a procurar trabalhar de forma
em maiúsculas e minúsculas. Se for definido, ele vai tratar
<BooKe<gt>laNG e <BOOK>Lang como <book>lang.
- escapequotes
- Aspas de escapa em cadeias de saída.
Necessário, por exemplo, para criação de recursos de
cadeias para usar por ferramentas de compilação de Android.
Veja também:
https://developer.android.com/guide/topics/resources/string-resource.html
- includeexternal
- Quando definido, entidades externas estão
incluídas no documento gerado (traduzido) e para a
extração de cadeias. Se não for definido, vai ter que
traduzir entidades externas separadamente como documentos
independentes.
- ontagerror
- Esta opção define o comportamento do
módulo quando ele encontrar uma sintaxe de XML inválida (uma
etiqueta de fecho, que não coincide com a última etiqueta de
abertura). Ele pode ter os seguintes valores:
- fail
- Este é o valor predefinido. O módulo
irá sair com um erro.
- warn
- O módulo continuará e emitirá um
aviso.
- silent
- O módulo vai continuar sem emitir um aviso.
Tenha cuidado ao usar esta opção. Recomenda-se geralmente para
corrigir o ficheiro de entrada.
- tagsonly
- Nota: Esta opção está obsoleta.
Extrai apenas as marcações especificadas na
opção tags. Do contrário, ela extrairá
todas as marcações, com exceção daquelas
especificadas.
- doctype
- A cadeias que vai tentar combinar com a primeira linha do
doctype do documento (se definido). Se isso não acontecer, um aviso
indicará que o documento poderá ser de um tipo
incorreto.
- addlang
- A cadeia a indicar o caminho (por exemplo,
<bbb><AAA>) de uma etiqueta onde um atributo
lang="..." deve ser adicionado. O idioma será definido
como o nome base do ficheiro PO sem qualquer extensão po.
- optionalclosingtag
- Booleano indicando se as tags de fechamento são
opcionais (como em HTML). Por padrão, as tags de fechamento
ausentes geram um erro tratado de acordo com ontagerror.
- tags
- Nota: Esta opção está obsoleta. Deve
usar as opções translated e untranslated em
vez.
Lista de etiquetas separada por espaços que deseja traduzir ou
ignorar. Por predefinição, as etiquetas especificadas
serão excluídas, mas se usar a opção
"tagsonly", etiquetas especificadas serão as
únicas incluídas. As etiquetas devem estar em forma
<aaa>, mas podem-se juntar a algum (<bbb><aaa>) para
dizer que o conteúdo da etiqueta <aaa> só será
traduzido quando está numaetiqueta <bbb>.
Também pode especificar algumas opções de
marcação para pôr alguns caracteres na frente da
hierarquia de marcações. Por exemplo, pode pôr um
w (wrap) or W (não aplica wrap) para sobrescrever o
comportamento padrão especificado pela opção global
wrap.
Exemplo: W<chapter><title>
- attributes
- Lista de atributos das etiquetas separada por
espaços que deseja traduzir. Pode especificar os atributos pelo
nome deles (por exemplo, "lang"), mas pode prefixar com uma
hierarquia de etiquetas, para especificar que este atributo só
será traduzido quando está na etiqueta especificada. Por
exemplo:<bbb><aaa>lang especifica que o atributo lang
só será traduzido se for em numa etiqueta <aaa> e
é numa etiqueta <bbb>.
- foldattributes
- Não traduzir atributos em etiquetas em linha. Vez
disso, substitua todos os atributos duma etiqueta por po4a-id=<id>.
Isto é útil quando atributos não serão
traduzidas, como isso simplifica as cadeias para tradutores e evita erros
de digitação.
- customtag
- lista de etiquietas separadas por espaços que
não deviam ser tratadas como etiquetas. Estas etiquetas são
tradadas com em linha e, não precisam de ser fechadas.
- break
- Lisat de etiquetas separada por espaços que devem
quebrar a sequência. Por predefinição, todas as
etiquetas quebrar a sequência.
As etiquetas devem estar na forma <aaa>, mas pode juntar algumas
(<bbb><aaa>), se uma etiqueta (<aaa>) só deveria
ser considerada quando está em outra etiqueta (<bbb>).
Note que uma marcação deve ser listada em apenas uma cadeia de
configuração de break, inline
placeholder ou customtag.
- inline
- Lista de etiquetas separada por espaços que devem
ser tratados como em linha. Por predefinição todas as
etiquetas quebram a sequência.
As etiquetas devem estar na forma <aaa>, mas pode juntar algumas
(<bbb><aaa>), se uma etiqueta (<aaa>) só deveria
ser considerada quando está em outra etiqueta (<bbb>).
- placeholder
- Lista de etiquetas separadas por espaços que devem
ser tratadas como espaços reservados. Os espaços reservados
não quebram a sequência, mas o conteúdo dos
espaços reservados é traduzido separadamente.
A localização do espaço reservado no bloco dele
será marcado com uma cadeia semelhante a:
<placeholder type=\"footnote\" id=\"0\"/>
As etiquetas devem estar na forma <aaa>, mas pode juntar algumas
(<bbb><aaa>), se uma etiqueta (<aaa>) só deveria
ser considerada quando está em outra etiqueta (<bbb>).
- break-pi
- Por padrão, as Instruções de
Processamento (ou seja, tags "<? ... ?>") são
tratadas como tags embutidas. Passe essa opção se desejar
que as I.P. sejam tratadas como tag de quebra. Note que tags PHP
não processadas são tratadas como Instruções
de Processamento pelo analisador.
- nodefault
- lista de etiquetas separadas por espaço que o
módulo não deve tentar definir por
predefinição em qualquer categoria.
Se tiver uma marcação que tenha a configuração
predefinida dela pela subclasse deste módulo, mas desejar definir
uma configuração alternativa, será necessário
listar essa marcação como parte da cadeia de
configuração nodefault.
- cpp
- Diretivas de suporte do pré-processador C. Quando
esta opção está definida, po4a irá considerar
as diretivas de pré-processamento como separadores de
parágrafo. Isso é importante se o ficheiro XML deve ser
processado, porque senão as directivas podem ser inseridas no meio
de linhas se o po4a considerar que pertencem ao parágrafo corrente,
que não será reconhecido pelo pré-processador. Nota:
as directivas de pré-processamento só devem aparecer entre
etiquetas (que não deve quebrar uma etiqueta).
- translated
- Listas de etiquetas separadas por espaços que quer
traduzir.
As etiquetas devem estar na forma <aaa>, mas pode juntar algumas
(<bbb><aaa>), se uma etiqueta (<aaa>) só deveria
ser considerada quando está em outra etiqueta (<bbb>).
Também pode especificar algumas opções de
marcação para por alguns caracteres na frente da hierarquia
de marcações. Isso sobrescreve o comportamento predefinido
especificado pelas opções globais wrap e
defaulttranslateoption.
- w
- Etiquetas devem ser traduzidos e o conteúdo pode ser
re-envolvido.
- W
- Etiquetas devem ser traduzidos e o conteúdo
não devia ser reenvolvido.
- i
- As etiquetas deverão ser traduzidas em linha.
- p
- Etiquetas devem ser traduzidos em linha.
Internamente, o analisador XML só se preocupa com essas quatro
opções:
w W i p.
* As tags listadas em
break são definidas como
w ou
W dependendo da opção
wrap.
* As tags listadas em
inline são definidas como
i.
* As tags listadas em
placeholder são definidas como
p.
* As tags listadas em
untranslated estão sem nenhuma dessas
opções definidas.
Pode verificar o comportamento real do parâmetro interno a invocar
po4a com a opção
--debug.
Exemplo: W<chapter><title>
Note que uma marcação deve estar listada na cadeia de
configuração
translated ou
untranslated.
- untranslated
- Listas de etiquetas separadas por espaços que
não quer traduzir.
As etiquetas devem estar na forma <aaa>, mas pode juntar algumas
(<bbb><aaa>), se uma etiqueta (<aaa>) só deveria
ser considerada quando está em outra etiqueta (<bbb>).
Note que uma tag inline traduzível numa tag não traduzida
é tratada como uma tag de quebra traduzível, a
configuração i é descartada e w ou
W é definida dependendo da opção
wrap.
- defaulttranslateoption
- As categorias predefinidas para etiquetas que não
são nenhuns de: traduzidos, não traduzidos, partidos, em
linha ou espaço reservado.
Este é um conjunto de letras, conforme definido em translated
e essa configuração é válida apenas para tags
traduzíveis.
A mais simples personalização é definir quais as etiquetas
e atributos mais desejados para o analisador a traduzir. Isto deve ser feito
na função 'initialize'. Primeiro, deve invocar o 'initialize'
principal, para obter as opções de linha de comando e, em
seguida, acrescentar as suas definições personalizadas para as
opções de 'hash'. Se quiser tratar de algumas novas
opções de linha de comando, deve defini-las antes invocar o
'initialize' principal:
$self->{options}{'new_option'}='';
$self->SUPER::initialize(%options);
$self->{options}{'_default_translated'}.=' <p> <head><title>';
$self->{options}{'attributes'}.=' <p>lang id';
$self->{options}{'_default_inline'}.=' <br>';
$self->treat_options;
Deveria usar as opções
_default_inline,
_default_break,
_default_placeholder,
_default_translated,
_default_untranslated e
_default_attributes nos módulos derivados. Isso permite que
utilizadores sobrescrevam o comportamento predefinido definido no seu
módulo com opções de linha de comando.
Se não gostar do comportamento predefinido deste módulo xml e
módulos derivados dele, poderá fornecer opções de
linha de comando para alterar o comportamento deles.
Veja
Locale::Po4a::Docbook(3pm),
Outro passo simples é substituir a função
"found_string", que recebe as cadeias extraídas do
analisador, a fim de traduzi-las. Lá pode controlar quais cadeias
deseja traduzir e realizar neles as transformações antes ou
depois da tradução em si.
Ele recebe o texto extraído, a referência de onde ele estava e um
'hash' que contém informações extras para controlar o que
cadeias a traduzir, como traduzi-las e gerar o comentário.
O conteúdo dessas opções depende do tipo de cadeia é
(especificado numa entrada do 'hash'):
- type="tag"
- A cadeia encontrada é o conteúdo de uma
etiqueta traduzível. A entrada "tag_options"
contém os carateres de opção na frente da hierarquia
das etiquetas na opção do módulo
"tags".
- type="attribute"
- Significa que as cadeias encontradas é o valor de um
atributo traduzível. A entrada "attribute" tem o nome do
atributo.
Ela deve retornar o texto que irá substituir o original no documento
traduzido. Aqui está um exemplo básico desta
função:
sub found_string {
my ($self,$text,$ref,$options)=@_;
$text = $self->translate($text,$ref,"type ".$options->{'type'},
'wrap'=>$self->{options}{'wrap'});
return $text;
}
Aqui está outro exemplo simples no novo módulo Dia , que só
filtra algumas cadeias.
Este é mais complexo, mas permite uma personalização
(quase) total. É baseado numa lista de 'hashes', cada um define o
comportamento de um tipo de etiqueta. A lista deve ser ordenada para que as
etiquetas mais gerais estão antes das mais concretas (ordenadas
primeiro no início e, depois, pelas chaves de fecho). Para definir um
tipo de etiqueta vai ter que fazer um hash com as seguintes chaves:
- beginning
- Especifice o princípio da etiqueta, depois de
"<".
- end
- Especifice o fim da etiqueta, depois de
">".
- breaking
- Ele diz que se esta é uma classe de etiquetas
quebradas. Uma etiqueta não-quebrada (inline) é uma que pode
ser tomada como parte do conteúdo de outra etiqueta. Pode levar o
valor falso (0), verdadeiro (1) ou indefinido. Se deixá-lo
indefinido, vai ter que definir a função f_breaking que vai
dizer se uma etiqueta concreta desta classe é uma etiqueta de
quebrar ou não.
- f_breaking
- É uma função que vai dizer se a
próxima etiqueta é uma quebra ou não. Ele deve ser
definido se a opção breaking não
é.
- f_extract
- Se deixar esta chave indefinida, a função de
extração de genéricos terá que extrair a
etiqueta própria. É útil para as etiquetas que podem
ter outras etiquetas ou estruturas especiais dentro deles, de modo que o
analisador principal não fica louco. Esta função
recebe um booleano que diz se a etiqueta deve ser removida do fluxo de
entrada ou não.
- f_translate
- Esta função recebe a etiqueta (no formato
get_string_until()) e retorna a etiqueta traduzida (atributos
traduzidos ou todos as necessárias transformações)
como uma única sequência.
- get_path()
- Esta função retorna o caminho para a etiqueta
corrente a partir da raiz do documento na forma
<html><body><p>.
Um conjunto adicional de etiquetas (sem parênteses) pode ser passado
como argumento. Estes elementos de caminho são adicionados ao fim
do caminho da corrente.
- tag_type()
- Esta função retorna o índice da lista
tag_types que cabe na etiqueta seguinte no fluxo de entrada, ou -1, se
é no fim do ficheiro de entrada.
Aqui, a marcação tem estrutura iniciada por < e finalizada
por > e pode conter várias linhas.
Isso funciona no vetor "@{$self->{TT}{doc_in}}" a deter os
dados do documento de entrada e referência indiretamente via
"$self->shiftline()" e
"$self->unshiftline($$)".
- extract_tag($$)
- Esta função retorna a próxima etiqueta
do fluxo de entrada sem o início e o fim, numa forma de matriz,
para manter as referências do ficheiro de entrada tem dois
parâmetros: o tipo de etiqueta (como retornado por tag_type) e um
booleano, que indica se deve ser removido a partir do fluxo de entrada.
Isso funciona no vetor "@{$self->{TT}{doc_in}}" a deter os
dados do documento de entrada e referência indiretamente via
"$self->shiftline()" e
"$self->unshiftline($$)".
- get_tag_name(@)
- Esta função retorna o nome da etiqueta
passada como um argumento, no formulário da matriz retornada por
extract_tag.
- breaking_tag()
- Esta função retorna um booleano que diz que
se a próxima etiqueta no fluxo de entrada é uma etiqueta
quebrada ou não (etiqueta inline). Ele deixa o fluxo de entrada
intacto.
- treat_tag()
- Essa função converte a próxima
etiqueta a partir do fluxo de entrada. Usando em cada etiqueta tipos
personalizados de funções de tradução.
Isso funciona no vetor "@{$self->{TT}{doc_in}}" a deter os
dados do documento de entrada e referência indiretamente via
"$self->shiftline()" e
"$self->unshiftline($$)".
- tag_in_list($@)
- Esta função retorna um valor de cadeia que
diz que se o primeiro argumento (a hierarquia das etiquetas) corresponde a
qualquer uma das etiquetas do segundo argumento (a lista de etiquetas ou a
hierarquia). Se não corresponder, ele retorna 0. Caso
contrário, retorna as opções de etiqueta
correspondentes (os carateres de frente da etiqueta) ou 1 (se a etiqueta
não tem opções).
- treat_attributes(@)
- Essa função manipula a tradução
dos atributos das marcações. Ela recebe a
marcação sem as marcas de início / fim e,
então, ela encontra os atributos e traduz os traduzíveis
(especificado pela opção do módulo
attributes). Isso retorna uma string simples com a
marcação traduzida.
- treat_content()
- Essa função obtém o texto até a
próxima marcação de quebra (não em linha) do
fluxo de entrada. Traduza-a a usar as funções de
tradução personalizadas de cada tipo de
marcação.
Isso funciona no vetor "@{$self->{TT}{doc_in}}" a deter os
dados do documento de entrada e referência indiretamente via
"$self->shiftline()" e
"$self->unshiftline($$)".
- treat_options()
- Esta função preenche as estruturas internas
que contêm as etiquetas, atributos e dados em linha com as
opções do módulo (especificado na linha de comando ou
na função de inicialização).
- get_string_until($%)
- Esta função retorna uma matriz com as linhas
(e referências) do documento de entrada até encontrar o
primeiro argumento. O segundo argumento é um 'hash' de
opções. Valor 0 significa desativado (a
predefinição) e 1 ativado.
As opções válidas são:
- include
- Isto faz com que a matriz retornada contenha o texto
procurado
- remove
- Isto remove o fluxo retornado a partir da entrada
- unquoted
- Isto assegura que o text procurado está fora de
qualquer citação
- regex
- Isso indica que o primeiro argumento é uma
expressão regular e não uma cadeia simples
- skip_spaces(\@)
- Esta função recebe como argumento a
referência a um parágrafo (no formato retornado por
get_string_until), ignora os espaços de título dele e
retorna-os como uma sequência simples.
- join_lines(@)
- Esta função retorna uma cadeia simples com o
texto do argumento da matriz (a descartar as referências).
Este módulo pode traduzir etiquetas e atributos.
DOCTYPE (ENTITIES)
Há um suporte mínimo para a tradução de entidades.
Elas são traduzida como um todo e as etiquetas não são
tidas em conta. As entidades multi linhas não são suportados e
as entidades são sempre re-envolvidas durante a tradução.
MODIFICAR TIPOS DE ETIQUETAS A PARTIR DE MÓDULOS HERDADOS (move a
estrutura tag_types dentro de hash $self hash?)
Locale::Po4a::TransTractor(3pm),
po4a(7)
Jordi Vilalta <[email protected]>
Nicolas François <[email protected]>
Copyright © 2004 Jordi Vilalta <[email protected]>
Copyright © 2008-2009 Nicolas François <[email protected]>
Este programa é software livre, pode redistribuí-lo e/ou
modificá-lo sob os termos da GPL (consulte o ficheiro
CÓPIA).