
        *****************************************************
        *           GENERATED FILE, DO NOT EDIT             *
        * THIS IS NO SOURCE FILE, BUT RESULT OF COMPILATION *
        *****************************************************

This file was generated by po4a(7). Do not store it (in VCS, for example),
but store the PO file used as source file by po4a-translate.

In fact, consider this as a binary, and the PO file as a regular .c file:
If the PO get lost, keeping this translation up-to-date will be harder.

=encoding UTF-8

=head1 NOME

Locale::Po4a::Xml - converte documentos XML e derivados de/para ficheiros PO

=head1 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
outros idiomas [humanos]. Também pode ser usado como uma base para a
construção de módulos de documentos com base em XML.

=head1 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, e nenhum
atributo, 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 B<WRITING DERIVATE
MODULES> abaixo, para descrição do processo.

=head1 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 salta algo importante.

Estas são as opções particulares deste módulo:

=over 4

=item B<nostrip>

Impede-o para tirar os espaços em torno das cadeias extraídas.

=item B<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
sobreposta por opções personalizadas de marcação. Veja a opção B<translated>
abaixo.

=item B<unwrap_attributes>

Atributos são envolvidos por predefinição. Essa opção desativa o envólucro.

=item B<caseinsensitive>

Faz as etiquetas e atributos a procurar trabalhar de forma em maiúsculas e
minúsculas. Se for definido, ele vai tratar E<lt>BooKe<gt>laNG e
E<lt>BOOKE<gt>Lang como E<lt>bookE<gt>lang.

=item B<escapequotes>

Aspas de escape 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

=item B<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.

=item B<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:

=over

=item I<fail>

Este é o valor predefinido. O módulo irá terminar com um erro.

=item I<warn>

O módulo irá continuar e emitir um aviso.

=item I<silent>

O módulo vai continuar sem emitir nenhuns avisos.

=back

Tenha cuidado ao usar esta opção. Recomenda-se geralmente para corrigir o
ficheiro de entrada.

=item B<tagsonly>

Nota: Esta opção está obsoleta.

Extrai apenas as marcações especificadas na opção B<tags>.   Caso contrário,
ela extrairá todas as marcações, com exceção daquelas especificadas.

=item B<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.

=item B<addlang>

A cadeia a indicar o caminho (por exemplo, E<lt>bbbE<gt>E<lt>AAAE<gt>) 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.

=item B<optionalclosingtag>

Booleano indicando se as etiquetas de fecho são opcionais (como em
HTML). Por predefinição, as etiquetas de fecho ausentes geram um erro
tratado de acordo com B<ontagerror>.

=item B<tags>

Nota: Esta opção está obsoleta.  Deve usar as opções B<translated> e
B<untranslated> em vez desta.

Lista de etiquetas separadas 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 E<lt>aaaE<gt>, mas podem-se juntar a algum
(E<lt>bbbE<gt>E<lt>aaaE<gt>) para dizer que o conteúdo da etiqueta
E<lt>aaaE<gt> só será traduzido quando está numa etiqueta E<lt>bbbE<gt>.

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
I<w> (wrap) ou I<W> (não aplica wrap) para sobrescrever o comportamento
predefinido especificado pela opção global B<wrap>.

Exemplo: WE<lt>chapterE<gt>E<lt>titleE<gt>

=item B<attributes>

Lista de atributos das etiquetas separadas 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:E<lt>bbbE<gt>E<lt>aaaE<gt>lang especifica que o
atributo lang só será traduzido se for numa etiqueta E<lt>aaaE<gt> e é numa
etiqueta E<lt>bbbE<gt>.

=item B<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.

=item B<customtag>

Lista de etiquetas 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.

=item B<break>

Lista de etiquetas separadas por espaços que devem quebrar a sequência. Por
predefinição, todas as etiquetas quebram a sequência.

As etiquetas devem estar na forma <aaa>, mas pode juntar algumas
(<bbb><aaa>), se a etiqueta (<aaa>) só deve ser considerada quando está em
outra etiqueta (<bbb>).

Note que uma marcação deve ser listada em apenas uma cadeia de configuração
de B<break>, B<inline> B<placeholder> ou B<customtag>.

=item B<inline>

Lista de etiquetas separadas por espaços que devem ser tratadas 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 a etiqueta (<aaa>) só deve ser considerada quando está em
outra etiqueta (<bbb>).

=item B<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 a etiqueta (<aaa>) só deve ser considerada quando está em
outra etiqueta (<bbb>).

=item B<break-pi>

Por predefinição, as Instruções de Processamento (ou seja, tags C<E<lt>?
... ?E<gt>>) 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.

=item B<nodefault>

Lista de etiquetas separadas por espaços que o módulo não deve tentar
definir por predefinição em nenhuma 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
B<nodefault>.

=item B<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 tiver de ser processado,
porque senão as diretivas 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 diretivas de pré-processamento só devem
aparecer entre etiquetas (não devem quebrar uma etiqueta).

=item B<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 a etiqueta (<aaa>) só deve 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 sobrepõe o
comportamento predefinido especificado pelas opções globais B<wrap> e
B<defaulttranslateoption>.

=over

=item I<w>

Etiquetas devem ser traduzidas e o conteúdo pode ser re-envolvido.

=item I<W>

Etiquetas devem ser traduzidas e o conteúdo não deve ser re-envolvido.

=item I<i>

As etiquetas devem ser traduzidas em linha.

=item I<p>

Etiquetas devem ser traduzidas como marcadores de posição.

=back

Internamente, o analisador XML só se preocupa com essas quatro opções: I<w>
I<W> I<i> I<p>.

* As etiquetas listadas em B<break> são definidas como I<w> ou I<W>
dependendo da opção B<wrap>.

* As etiquetas listadas em B<inline> são definidas como I<i>.

* As etiquetas listadas em B<placeholder> são definidas como I<p>.

* As etiquetas listadas em B<untranslated> não têm nenhuma dessas opções
definidas.

Pode verificar o comportamento real do parâmetro interno ao invocar B<po4a>
com a opção B<--debug>.

Exemplo: WE<lt>chapterE<gt>E<lt>titleE<gt>

Note que uma marcação deve estar listada na cadeia de configuração
B<translated> ou B<untranslated>.

=item B<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 a etiqueta (<aaa>) só deve ser considerada quando está em
outra etiqueta (<bbb>).

Note que uma etiqueta em linha traduzível numa etiqueta não traduzível é
tratada como uma etiqueta de quebra traduzível, a configuração I<i> é
descartada e I<w> ou I<W> é definido dependendo da opção B<wrap>.

=item B<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 B<translated> e essa
configuração é válida apenas para etiquetas traduzíveis.

=back

=head1 ESCREVENDO MÓDULOS DERIVADOS

=head2 DEFINIR QUE ETIQUETAS E ATRIBUTOS TRADUZIR

A mais simples personalização é definir quais as etiquetas e atributos mais
desejados para o analisador 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 na 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;

Você deve usar as opções B<_default_inline>, B<_default_break>,
B<_default_placeholder>, B<_default_translated>, B<_default_untranslated> e
B<_default_attributes> nos módulos derivados. Isso permite que utilizadores
sobreponham o comportamento predefinido definido no seu módulo com opções de
linha de comando.

=head2 SOBREPOR O 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 L<Locale::Po4a::Docbook(3pm)|Locale::Po4a::Docbook>,

=head2 SOBREPONDO A FUNÇÃO found_string

Outro passo simples é sobrepor 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 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 deste 'hash'):

=over

=item type="tag"

A cadeia encontrada é o conteúdo de uma etiqueta traduzível. A entrada
"tag_options" contém os caracteres de opção na frente da hierarquia das
etiquetas no módulo "tags".

=item type="attribute"

Significa que a cadeia encontrada é o valor de um atributo traduzível. A
entrada "attribute" tem o nome do atributo.

=back

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.

=head2 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
estejam 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:

=over 4

=item B<beginning>

Especifica o princípio da etiqueta, depois de "E<lt>".

=item B<end>

Especifica o fim da etiqueta, depois de "E<gt>".

=item B<breaking>

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.

=item B<f_breaking>

É uma função que vai dizer se a próxima etiqueta é uma quebra ou não. Deve
ser definida se a opção B<breaking> não é.

=item B<f_extract>

Se deixar esta chave indefinida, a função de extração de genéricos terá que
extrair a própria etiqueta. É útil para as etiquetas que podem ter outras
etiquetas ou estruturas especiais dentro delas, de modo que o analisador
principal não fique louco. Esta função recebe um booleano que diz se a
etiqueta deve ser removida do fluxo de entrada ou não.

=item B<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 cadeia.

=back

=head1 FUNÇÕES INTERNAS usadas para escrever analisadores derivados

=head2 TRABALHANDO COM ETIQUETAS

=over 4

=item get_path()

Esta função retorna o caminho para a etiqueta corrente a partir da raiz do
documento no formato E<lt>htmlE<gt>E<lt>bodyE<gt>E<lt>pE<gt>.

Um conjunto adicional de etiquetas (sem parênteses) pode ser passado como
argumento. Estes elementos de caminho são adicionados ao fim do caminho
atual.

=item tag_type()

Esta função retorna o índice da lista tag_types que cabe na etiqueta
seguinte no fluxo de entrada, ou -1, se está no fim do ficheiro de entrada.

Aqui, a marcação tem estrutura iniciada por E<lt> e finalizada por E<gt> e
pode conter várias linhas.

Isso funciona na matriz C<< @{$self->{TT}{doc_in}} >> que detém os dados do
documento de entrada e referência indiretamente via C<< $self->shiftline()
>> e C<< $self->unshiftline($$) >>.

=item 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 na matriz C<< @{$self->{TT}{doc_in}} >> que detém os dados do
documento de entrada e referência indiretamente via C<< $self->shiftline()
>> e C<< $self->unshiftline($$) >>.

=item get_tag_name(@)

Esta função retorna o nome da etiqueta passada como um argumento, no formato
da matriz retornada por extract_tag.

=item 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). Ela deixa o
fluxo de entrada intacto.

=item treat_tag()

Essa função traduz a próxima etiqueta do fluxo de entrada. Usando funções de
tradução personalizadas em cada tipo de etiqueta.

Isso funciona na matriz C<< @{$self->{TT}{doc_in}} >> que detém os dados do
documento de entrada e referência indiretamente via C<< $self->shiftline()
>> e C<< $self->unshiftline($$) >>.

=item tag_in_list($@)

Esta função retorna um valor de cadeia que diz 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 caracteres de frente da etiqueta) ou 1 (se a etiqueta
não tiver opções).

=back

=head2 TRABALHANDO COM ATRIBUTOS

=over 4

=item 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
B<attributes>). Isso retorna uma cadeia simples com a marcação traduzida.

=back

=head2 TRABALHANDO COM CONTEÚDOS ETIQUETADOS

=over 4

=item 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. Traduz-a a usar as funções de tradução personalizadas de
cada tipo de etiqueta.

Isso funciona na matriz C<< @{$self->{TT}{doc_in}} >> que detém os dados do
documento de entrada e referência indiretamente via C<< $self->shiftline()
>> e C<< $self->unshiftline($$) >>.

=back

=head2 TRABALHANDO COM OPÇÕES DE MÓDULOS

=over 4

=item 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).

=back

=head2 OBTER TEXTO A PARTIR DO DOCUMENTO DE ENTRADA

=over

=item 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:

=over 4

=item B<include>

Isto faz com que a matriz retornada contenha o texto procurado

=item B<remove>

Isto remove o fluxo retornado a partir da entrada

=item B<unquoted>

Isto assegura que o text procurado está fora de qualquer citação

=item B<regex>

Isso indica que o primeiro argumento é uma expressão regular e não uma
cadeia simples

=back

=item 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 cadeia simples.

=item join_lines(@)

Esta função retorna uma cadeia simples com o texto do argumento da matriz
(descartando as referências).

=back

=head1 ESTADO DESTE MÓDULO

Este módulo pode traduzir etiquetas e atributos.

=head1 LISTA de A FAZER

DOCTYPE (ENTIDADES)

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 suportadas 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?)

=head1 VEJA TAMBÉM

L<Locale::Po4a::TransTractor(3pm)|Locale::Po4a::TransTractor>,
L<po4a(7)|po4a.7>

=head1 AUTORES

 Jordi Vilalta <jvprat@gmail.com>
 Nicolas François <nicolas.francois@centraliens.net>

=head1 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 é um software livre; pode redistribuí-lo e/ou modificá-lo sob
os termos da GPL v2.0 ou posterior (veja o ficheiro COPYING).
