Provided by: po4a_0.67-2_all 
NOME
Locale::Po4a::Xml - converte documentos XML e derivados de/para ficheiros PO
DESCRIÇÃO
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.
TRADUZIR COM PO4A::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.
OPÇÕES ACEITES POR ESTE MÓDULO
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.
ESCREVENDO MÓDULOS DERIVADOS
DEFINIR QUE ETIQUETAS E ATRIBUTOS PARA TRADUÇÃO
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.
SUBSTITUIÇÃO DO COMPORTAMENTO PREDEFINIDO COM AS 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),
SUBSTITUINDO A FUNÇÃO found_string
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.
MODIFICANDO TIPOS DE ETIQUETAS (A FAZER)
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.
FUNÇÕES INTERNAS usadas para escrever analisadores derivados
TRABALHANDO COM ETIQUETAS
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).
TRABALHANDO COM ATRIBUTOS
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.
TRABALHANDO COM CONTEÚDOS MARCADOS
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($$)".
TRABALHANDO COM OPÇÕES DE MÓDULOS
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).
OBTENÇÃO DE TEXTO A PARTIR DO DOCUMENTO DE ENTRADA
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).
ESTADO DESTE MÓDULO
Este módulo pode traduzir etiquetas e atributos.
LISTA PARAFAZER
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?)
VER TAMBÉM
Locale::Po4a::TransTractor(3pm), po4a(7)
AUTORES
Jordi Vilalta <jvprat@gmail.com>
Nicolas François <nicolas.francois@centraliens.net>
DIREITOS DE AUTOR E LICENÇA
Copyright © 2004 Jordi Vilalta <jvprat@gmail.com>
Copyright © 2008-2009 Nicolas François <nicolas.francois@centraliens.net>
Este programa é software livre, pode redistribuí-lo e/ou modificá-lo sob os termos da GPL
(consulte o ficheiro CÓPIA).