Provided by: po4a_0.52-1_all 
NOME
Locale::Po4a::Xml - converte documentos XML e derivados de/para ficheiros PO
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.
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 sequências 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 sequências extraídas.
wrap
Canonicalizes the string to translate, considering that whitespaces are not important, and wraps the
translated document. This option can be overridden by custom tag options. See the "tags" option
below.
unwrap_attributes
Attributes are wrapped by default. This option disables wrapping.
caseinsensitive
Faz as etiquetas e atributos procurando 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
Escape quotes in output strings. Necessary, for example, for creating string resources for use by
Android build tools.
See also: 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 sequências. Se não for definido, você vaiter que traduzir entidades externas
separadamente como documentos independentes.
ontagerror
This option defines the behavior of the module when it encounters invalid XML syntax (a closing tag
which does not match the last opening tag, or a tag's attribute without value). It can take the
following values:
fail
Este é o valor padrão. 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 arquivo de entrada.
tagsonly
Extrai apenas as etiquetas especificados na opção "tags". Caso contrário, ele irá extrair todas as
marcas, exceto os especificados.
Nota: Esta opção está obsoleta.
doctype
A sequência 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 mau.
addlang
A sequência indicando 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.
tags
Lista de etiquetas separada por espaços que deseja traduzir ou ignorar. Por padrão, as etiquetas
especificadas serão excluídas, mas se você 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 de que o conteúdo da etiqueta <aaa> só será traduzido quando está numaetiqueta <bbb>.
Você também pode especificar algumas opções de etiquetas, colocando alguns carateres em frente da
hierarquia de etiquetas. Por exemplo, você pode colocar 'w' (wrap) ou 'W' (don't wrap) para
substituir o comportamento padrão especificado pela opção global "wrap".
Exemplo: W<chapter><title>
Nota: Esta opção está obsoleta. Você deve usar as opções translated e untranslated em vez.
attributes
Space-separated list of tag's attributes you want to translate. You can specify the attributes by
their name (for example, "lang"), but you can prefix it with a tag hierarchy, to specify that this
attribute will only be translated when it's in the specified tag. For example: <bbb><aaa>lang
specifies that the lang attribute will only be translated if it's in an <aaa> tag, and it's in a
<bbb> tag.
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 sequências 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 padrão, todas as etiquetas
quebrar a sequência.
The tags must be in the form <aaa>, but you can join some (<bbb><aaa>), if a tag (<aaa>) should only
be considered when it's within another tag (<bbb>).
inline
Lista de etiquetas separada por espaços que devem ser tratados como em linha. Por padrão, todas as
etiquetas quebram a sequência.
The tags must be in the form <aaa>, but you can join some (<bbb><aaa>), if a tag (<aaa>) should only
be considered when it's within another tag (<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 seu bloco será marcado com uma sequência semelhante a:
<placeholder type=\"footnote\" id=\"0\"/>
The tags must be in the form <aaa>, but you can join some (<bbb><aaa>), if a tag (<aaa>) should only
be considered when it's within another tag (<bbb>).
nodefault
lista de etiquetas separadas por espaço que o módulo não deve tentar definir por padrão em qualquer
categoria.
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.
The tags must be in the form <aaa>, but you can join some (<bbb><aaa>), if a tag (<aaa>) should only
be considered when it's within another tag (<bbb>).
Você também pode especificar algumas opções de etiquetas, colocando alguns carateres em frente da
hierarquia de etiquetas. Por exemplo, você pode colocar 'w' (wrap) ou 'W' (don't wrap) para
substituir o comportamento padrão especificado pela opção global "wrap".
Exemplo: W<chapter><title>
untranslated
Listas de etiquetas separadas por espaços que não quer traduzir.
The tags must be in the form <aaa>, but you can join some (<bbb><aaa>), if a tag (<aaa>) should only
be considered when it's within another tag (<bbb>).
defaulttranslateoption
As categorias padrão para etiquetas que não estão em nenhum dos traduzidosnão traduzidos, partidos,
em linha, ou espaço reservado.
Trata-se de um conjunto da cartas:
w Etiquetas devem ser traduzidos e o conteúdo pode ser re-envolvido.
W Etiquetas devem ser traduzidos e o conteúdo não pode ser re-envolvido
i As tags deverão ser traduzidas em linha
p Etiquetas devem ser traduzidos em linha.
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
de traduzir. Isto deve ser feito na função 'initialize'. Primeiro, você 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 algumas novas opções de linha de comando, você
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;
Você deve usar o _default_inline, _default_break, _default_placeholder, _default_translated e,
_default_untranslated e opções _default_attributes em módulos derivados. Isso permite aos utilizadores
substituir o comportamento padrão definido no seu módulo com as opções da linha de comando.
SUBSTITUINDO A FUNÇÃO found_string
Outro passo simples é substituir a função "found_string", que recebe as sequências extraídas do
analisador, a fim de traduzi-las.Lá pode controlar quais linhas você 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 sequências a traduzir, como traduzi-las e gerar o comentário.
O conteúdo dessas opções depende do tipo de sequência é (especificado numa entrada do 'hash'):
type="tag"
A sequência 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 a sequência encontrada é 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 sequências.
MODIFICANDO TIPOS DE ETIQUETAS (A FAZER)
This is a more complex one, but it enables a (almost) total customization. It's based on a list of
hashes, each one defining a tag type's behavior. The list should be sorted so that the most general tags
are after the most concrete ones (sorted first by the beginning and then by the end keys). To define a
tag type you'll have to make a hash with the following keys:
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 uma outra etiqueta. Pode levar o valor falso (0),
verdadeiro (1) ou indefinido. Se você deixar este indefinido, você 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 você deixar esta chave indefinida, a função de extração de genéricos terá que extrair a etiqueta
em si. É útil para as etiquetas que podem ter outras etiquetas ou estruturas especiais em si, 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 analises derivadas
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.
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.
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.
tag_in_list($@)
Esta função retorna um valor de sequência 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
sua hierarquia). Se não corresponder, ele retorna 0. 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 de atributos das etiquetas. Recebe a etiqueta sem as marcas de
início/fim e, em seguida encontram os atributos, e traduz as traduzíveis (especificado pela opção do
módulo "atributos"). Este retorna uma sequência simples com a etiqueta traduzida.
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 (o
padrã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
skip_spaces(\@)
Esta função recebe como argumento a referência a um parágrafo (no formato retornado por
get_string_until), ignora seus espaços de título e retorna-os como uma sequência simples.
join_lines(@)
Esta função retorna uma sequência simples com o texto do argumento da matriz (descartando as
referências).
STATUS 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
Direitos de Autor (c) 2004 por Jordi Vilalta <jvprat@gmail.com>
Direitos de Autor (c) 2008-2009 porNicolas François <nicolas.francois@centraliens.net>
Este programa é software livre, você pode redistribuí-lo e/ou modificá-lo sob os termos da GPL (consulte
o ficheiro CÓPIA).
Ferramentas Po4a 2017-08-26 Locale::Po4a::Xml(3pm)