Provided by: po4a_0.47-2_all 
NOME
Locale::Po4a::Xml - converte documentos XML e derivados de/para arquivos PO
DESCRIÇÃO
A missão do projeto po4a (em inglês, PO for anything) é facilitar as traduções (e o mais
interessante, a manutenção de traduções) usando ferramentas de gettext em áreas onde elas
não eram esperadas, como documentação.
Locale::Po4a::Xml é um módulo para ajudar a tradução de documentos XML para outros
idiomas. Ele também pode ser usado como uma base para compilar módulos para documentos
baseados em XML.
TRADUZINDO COM PO4A::XML
Esse módulo pode ser usado diretamente para manipular documentos XML genéricos. Ele vai
extrair o conteúdo de todas as marcações, porém de nenhum atributo, já que é onde o texto
está escrito na maioria dos documentos baseados em XML.
Há algumas opções (descritas na próxima seção) que podem personalizar este comportamento.
Se isso não se adequar ao formato do seu documento, encorajamos você a escrever seu
próprio módulo derivado deste, para descrever os detalhes do seu formato. Veja a seção
abaixo ESCREVENDO MÓDULOS DERIVADOS, para a descrição do processo.
OPÇÕES ACEITAS POR ESTE MÓDULO
A opção de depuração global causa esse módulo a mostrar as strings excluídas, para ver se
ignora alguma coisa importante.
Estas são as opções específicas deste módulo:
nostrip
Previne-o de cortar espaços em volta das strings 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.
caseinsensitive
Isso faz com que a pesquisa por marcações e atributos funcione de uma forma que
diferencie letras maiúsculas das minúsculas. Se essa opção estiver definida, ela vai
tratar <BooK>laNG e <BOOK>Lang como <book>lang.
includeexternal
Quando definida, entidades externas são incluídas no documento gerado (traduzido) e
para a extração de strings. Se não estiver definido, você terá 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
Esse é o valor padrão. O módulo vai sair com um erro.
warn
O módulo vai continuar e vai fazer um aviso.
silent
O módulo vai continuar sem qualquer aviso.
Tenha cuidado ao usar essa opção. Ela geralmente é recomendada para corrigir o arquivo
de entrada.
tagsonly
Extrai apenas as marcações especificadas na opção "tags". Do contrário, ela extrairá
todas as marcações, com exceção daquelas especificadas.
Nota: essa opção é obsoleta.
doctype
String que tentará corresponder com a primeira linha do tipo de documento (doctype) do
documento (se definido). Se não estiver definido, um aviso vai indicar que o documento
pode ser um tipo incorreto.
addlang
String indicando o caminho (ex.: <bbb><aaa>) de uma marcação na qual um atributo
lang="..." deve ser adicionado. O idioma será definido como o nome base do arquivo PO
sem qualquer extensão.
tags
Lista separada por espaço de marcações que você deseja traduzir ou ignorar. Por
padrão, as marcações especificadas serão excluídas, mas se você usar a opção
"tagsonly", as marcações especificadas serão as únicas incluídas. As marcações devem
estar na forma <aaa>, mas você pode juntar algumas (<bbb><aaa>) para informar que o
conteúdo da tag <aaa> será traduzido apenas quando ela estiver dentro de uma marcação
<bbb>.
Você também pode especificar algumas opções de marcação para colocar alguns caracteres
na frente da hierarquia de marcações. Por exemplo, você pode colocar um "w" (wrap) ou
"W" (não aplica wrap) para sobrescrever o comportamento padrão especificado pela opção
global "wrap".
Exemplo: W<capítulo><título>
Nota: Essa opção é obsoleta. Você deveria usar as opções translated e untranslated ao
invés dessa.
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 traduz atributos nas marcações integradas. Ao invés disso, substitui todos os
atributos de uma marcação por po4a-id=<id>.
Isso é útil quando os atributos não devam ser traduzidos, pois isso simplifica as
strings para tradutores e evita erros de escrita.
customtag
Lista separada por espaço de marcações que não deveriam ser tratadas como marcações.
Essas marcações são tratadas como integradas e não precisam ser fechadas.
break
Lista separada por espaço de marcações que deveriam interromper a sequência. Por
padrão, todas as marcações interrompem 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 separada por espaço de marcações que deveriam ser tratadas como integradas. Por
padrão, todas as marcações interrompem 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 separada por espaço de marcações que devem ser tratadas como placeholders. Elas
não interrompem a sequência, mas o conteúdo desses placeholders é traduzido
separadamente.
A localização do placeholder em seu bloco será marcado com uma string similar 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 separada por espaço de marcações que o módulo não deveria tentar definir por
padrão em qualquer categoria.
cpp Diretivas de suporte do preprocessador C. Quando essa opção está definida, po4a vai
considerar as diretivas do preprocessador como separadores de parágrafo. Isso é
importante se o arquivo XML deve ser preprocessado porque, do contrário, as diretivas
podem ser inseridas no meio de linhas se po4a considerar que elas pertencem ao
parágrafo atual, e elas não serão reconhecidas pelo preprocessador. Nota: as diretivas
do preprocessador devem aparecer apenas entre marcações (elas não podem interromper
uma marcação).
translated
Lista separada por espaço de marcações que você deseja 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 marcação para colocar alguns caracteres
na frente da hierarquia de marcações. Por exemplo, você pode colocar um "w" (wrap) ou
"W" (não aplica wrap) para sobrescrever o comportamento padrão especificado pela opção
global "wrap".
Exemplo: W<capítulo><título>
untranslated
Lista separada por espaço de marcações que você não deseja 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 marcações que estão em nenhum entre "translated",
"untranslated", "break", "inline" ou "placeholder".
Essa é um conjunto de letras:
w Tags deveriam ser traduzidas e o conteúdo pode ser redimensionado.
W Tags deveriam ser traduzidas e o conteúdo não deveria ser redimensionado.
i Tags deveriam ser traduzidas integradas.
p Tags deveriam ser traduzidas como placeholders.
ESCREVENDO MÓDULOS DERIVADOS
DEFINA QUAIS MARCAÇÕES E ATRIBUTOS DEVEM SER TRADUZIDOS
A personalização mais simples é definir quais marcações e atributos você deseja que o
analisador traduzida. Isso deveria ser feito na função "initialize". Primeiro, você
deveria chamar o "initialize" principal, para obter as opções de linha de comando e,
então, anexe suas definições personalizadas aos hash de opções. Se você deseja tratar
algumas novas opções a partir da linha de comando, você deveria defini-las antes de chamar
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ê 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 usuários sobrescrevam o comportamento padrão definido em seu módulo com
opções de linha de comando.
SOBRESCREVENDO A FUNÇÃO found_string
Outro passo simples é sobrescrever a função "found_string", que recebe as strings
extraídas do analisador, para traduzi-las. Lá, você pode controlar quais strings você
deseja traduzir e realizar transformações nelas antes ou após a tradução em si.
Ela recebe o texto extraído, a referência de onde ele estava e um hash que contém
informações extras para controlar quais strings devem ser traduzidas, como traduzi-las e
para gerar o comentário.
O conteúdo dessas opções dependem do tipo de string (especificado em uma entrada dessa
hash):
type="tag"
A string encontrada é o conteúdo de uma marcação traduzível. A entrada "tag_options"
contém os caracteres da opção na frente da hierarquia de marcação na opção "tags" do
módulo.
type="attribute"
Significa que a string encontrada é o valor de um atributo traduzível. A entrada
"atributo" possui o nome do atributo.
Ela deve retornar o texto que vai substituir o original no documento traduzido. Aqui está
um exemplo básico dessa função:
sub found_string {
my ($self,$text,$ref,$options)=@_;
$text = $self->translate($text,$ref,"type ".$options->{'type'},
'wrap'=>$self->{options}{'wrap'});
return $text;
}
Há um outro exemplo simples no novo módulo do Dia, o qual filtra apenas algumas strings.
MODIFICANDO TIPOS DE MARCAÇÕES (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
Especifica o começo da marcação, após do "<".
end Especifica o fim da marcação, antes do ">".
breaking
Informa se essa é uma classe de interrupção de marcação. Uma marcação de
não-interrupção (integrada) é aquela que pode ser levada como parte do conteúdo de
outra marcação. Ela pode levar os valores falso (0), verdadeiro (1) ou indefinido. Se
você deixa-la como indefinida, você terá que definir a função f_breaking que vai dizer
se uma marcação concreta dessa classe é uma marcação de interrupção ou não.
f_breaking
Essa é uma função que vai dizer se a próxima marcação é uma de interrupção ou não. Ela
deveria ser definida se a opção breaking não estiver.
f_extract
Se você deixar essa chave indefinida, a função de extração genérica terá ela mesma que
extrair a marcação. Isso é útil para marcações que podem ter outras marcações ou
estruturas especiais nelas, de forma que o analisador principal não fique doido. Essa
função recebe um booleano que informa se a marcação deveria, ou não, ser removida do
fluxo de entrada.
f_translate
Essa função recebe a marcação (no formato de get_string_until() ) e retorna a marcação
traduzida (atributos traduzidos ou todas as transformações necessárias) como uma
string única.
FUNÇÕES INTERNAS usadas para escrever analisadores derivados
TRABALHANDO COM MARCAÇÕES
get_path()
Essa função retorna o caminho da marcação atual da raiz do documento, na forma de
<html><body><p>.
Um vetor adicional de marcações (sem sinais de maior que, menor que) podem ser
passados como argumentos. Esses elementos de caminho são adicionados ao final do
caminho atual.
tag_type()
Essa função retorna o índice da lista tag_types que ajusta à próxima aba no fluxo de
entrada, ou -1 se ela está ao final do arquivo de entrada.
extract_tag($$)
Essa função retorna a marcação seguinte do fluxo de entrada sem o início e fim, em uma
forma de vetor, para manter a referência do arquivo de entrada. Ela tem dois
parâmetros: o tipo da marcação (como retornada por tag_type) e um boleano, que indica
se ela deveria ser removida do fluxo de entrada.
get_tag_name(@)
Essa função retorna o nome da marcação passada como um argumento, na forma de vetor
retornado por extract_tag.
breaking_tag()
Essa função retorna um booleano que informa se a próxima marcação no fluxo de entrada
é uma marcação de interrupção ou não (marcação integrada). Ela deixa o fluxo de
entrada intacto.
treat_tag()
Essa função traduz a próxima marcação do fluxo de entrada, usando as funções de
tradução personalizada de cada tipo de marcação.
tag_in_list($@)
Essa função retorna um valor de string que informa se o primeiro argumento (uma
hierarquia de marcações) corresponde a qualquer das marcações do segundo argumento
(uma lista de marcações ou hierarquias de marcações). Se ela não corresponder, retorna
0. Do contrário, retorna as opções da marcação correspondente (os caracteres na frente
da marcação) ou 1 (se aquela marcação não possuir 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 AS OPÇÕES DO MÓDULO
treat_options()
Essa função preenche as estruturas internal que contém as marcações, atributos e dados
integrados com as opções do módulo (especificado na linha de comando ou na função
"inicialize").
OBTENDO TEXTO DO DOCUMENTO DE ENTRADA
get_string_until($%)
Essa função retorna um vetor 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 desabilitado (o padrão) e 1, habilitado.
As opções válidas são:
include
Isso faz o vetor resultante conter o texto pesquisado
remove
Isso remove o fluxo retornado da entrada
unquoted
Isso garante que o texto pesquisado não está entre aspas
skip_spaces(\@)
Essa função recebe como argumento a referência para um parágrafo (no formato retornado
por get_string_until), ignora seu espaço inicial e retorna-as como uma string simples.
join_lines(@)
Essa função retorna uma string simples com o texto de um vetor de argumentos
(descartando as referências).
ESTADO DESTE MÓDULO
Esse módulo pode traduzir marcações e atributos.
LISTA DE TAREFAS
DOCTYPE (ENTIDADES)
Há um suporte mínimo para a tradução de entidades. Elas são traduzidos como um todo e
marcações não são levadas em conta. Não há suporte a entidades multilinhas, sofrendo elas
uma quebra de linha durante a tradução.
MODIFICAR TIPOS DE MARCAÇÃO DE MÓDULOS HERDADOS (move a estrutura de tag_types para dentro
do $self hash?)
VEJA TAMBÉM
Locale::Po4a::TransTractor(3pm), po4a(7)
AUTORES
Jordi Vilalta <jvprat@gmail.com>
Nicolas François <nicolas.francois@centraliens.net>
COPYRIGHT E LICENÇA
Copyright (c) 2004 por Jordi Vilalta <jvprat@gmail.com>
Copyright (c) 2008-2009 por Nicolas François <nicolas.francois@centraliens.net>
Esse programa é um software livre; você pode redistribuí-lo e/ou modificá-lo sob os termos
da GPL (veja o arquivo COPYING).