
        *****************************************************
        *           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 arquivos PO

=head1 DESCRIÇÃO

O objetivo do projeto po4a (PO for anything, ou PO para qualquer coisa) é
facilitar traduções (e o mais interessante, a manutenção das traduções)
usando as ferramentas do gettext em áreas em que não se esperava, 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.

=head1 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 B<ESCREVENDO
MÓDULOS DERIVADOS>, para a descrição do processo.

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

=over 4

=item B<nostrip>

Previne-o de cortar espaços em volta das strings extraídas.

=item B<wrap>

Canoniza a string para traduzir, considerando 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
B<translated> abaixo.

=item B<unwrap_attributes>

Atributos são quebrados por padrão. Essa opção desabilita a quebra.

=item B<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 E<lt>BooKE<gt>laNG e E<lt>BOOKE<gt>Lang como
E<lt>bookE<gt>lang.

=item B<escapequotes>

Escapa aspas em strings de saída. Necessário, por exemplo, para criação de
recursos de string 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 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.

=item B<ontagerror>

Essa opção define o comportamento do módulo quando ele encontrar uma sintaxe
XML inválida (uma marcação fechando que não corresponde a última marcação
abrindo). Ele pode levar os seguintes valores:

=over

=item I<fail>

Esse é o valor padrão. O módulo vai sair com um erro.

=item I<warn>

O módulo vai continuar e vai fazer um aviso.

=item I<silent>

O módulo vai continuar sem qualquer aviso.

=back

Tenha cuidado ao usar essa opção. Ela geralmente é recomendada para corrigir
o arquivo de entrada.

=item B<tagsonly>

Nota: essa opção é obsoleta.

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

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

=item B<addlang>

String indicando o caminho (ex.: E<lt>bbbE<gt>E<lt>aaaE<gt>) 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.

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

=item B<tags>

Nota: Essa opção é obsoleta. Você deveria usar as opções B<translated> e
B<untranslated> ao invés dessa.

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 E<lt>aaaE<gt>, mas você pode
juntar algumas (E<lt>bbbE<gt>E<lt>aaaE<gt>) para informar que o conteúdo da
tag E<lt>aaaE<gt> será traduzido apenas quando ela estiver dentro de uma
marcação E<lt>bbbE<gt>.

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

Exemplo: WE<lt>capítuloE<gt>E<lt>títuloE<gt>

=item B<attributes>

Lista separada por espaço de atributos da marcação que você deseja
traduzir. Você pode especificar os atributos por seus nomes (por exemplo,
"lang"), mas você pode prefixar com uma hierarquia de marcações, para
especificar que esse atributo vai ser traduzido apenas quando ele estiver na
marcação especificada. Por exemplo: E<lt>bbbE<gt>E<lt>aaaE<gt>lang
especifica que o atributo lang será traduzido apenas se ele estiver dentro
de uma marcação E<lt>aaaE<gt> e dentro de uma marcação E<lt>bbbE<gt>.

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

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

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

As marcações estar na forma <aaa>, mas você pode juntar alguns (<bbb><aaa>),
se uma marcação (<aaa>) deveria ser considerada apenas quando ela estiver
dentro de outra marcação (<bbb>).

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

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

As marcações estar na forma <aaa>, mas você pode juntar alguns (<bbb><aaa>),
se uma marcação (<aaa>) deveria ser considerada apenas quando ela estiver
dentro de outra marcação (<bbb>).

=item B<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\"/>

As marcações estar na forma <aaa>, mas você pode juntar alguns (<bbb><aaa>),
se uma marcação (<aaa>) deveria ser considerada apenas quando ela estiver
dentro de outra marcação (<bbb>).

=item B<break-pi>

Por padrã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 separada por espaço de marcações que o módulo não deveria tentar
definir por padrão em qualquer categoria.

Se você tiver uma tag que tenha sua configuração padrão pela subclasse deste
módulo, mas desejar definir uma configuração alternativa, será necessário
listar essa tag como parte da string de configuração B<nodefault>.

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

=item B<translated>

Lista separada por espaço de marcações que você deseja traduzir.

As marcações estar na forma <aaa>, mas você pode juntar alguns (<bbb><aaa>),
se uma marcação (<aaa>) deveria ser considerada apenas quando ela estiver
dentro de outra 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. Isso sobrescreve o
comportamento padrão especificado pelas opções globais B<wrap> e
B<defaulttranslateoption>.

=over

=item I<w>

Tags deveriam ser traduzidas e o conteúdo pode ser redimensionado.

=item I<W>

Tags deveriam ser traduzidas e o conteúdo não deveria ser redimensionado.

=item I<i>

Tags deveriam ser traduzidas integradas.

=item I<p>

Tags deveriam ser traduzidas como placeholders.

=back

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

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

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

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

* As tags listadas em B<untranslated> estão sem nenhuma dessas opções
definidas.

Você pode verificar o comportamento real do parâmetro interno invocando
B<po4a> com a opção B<--debug>.

Exemplo: WE<lt>capítuloE<gt>E<lt>títuloE<gt>

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

=item B<untranslated>

Lista separada por espaço de marcações que você não deseja traduzir.

As marcações estar na forma <aaa>, mas você pode juntar alguns (<bbb><aaa>),
se uma marcação (<aaa>) deveria ser considerada apenas quando ela estiver
dentro de outra marcação (<bbb>).

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

=item B<defaulttranslateoption>

As categorias padrão para marcações que estão em nenhum entre "translated",
"untranslated", "break", "inline" ou "placeholder".

Este é um conjunto de letras, conforme definido em B<translated>, e essa
configuração é válida apenas para tags traduzíveis.

=back

=head1 ESCREVENDO MÓDULOS DERIVADOS

=head2 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 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 usuários
sobrescrevam o comportamento padrão definido em seu módulo com opções de
linha de comando.

=head2 SUBSTITUIÇÃO DO COMPORTAMENTO PADRÃO COM AS OPÇÕES DE LINHA DE COMANDO

Se você não gostar do comportamento padrão deste módulo xml e seus módulos
derivados, poderá fornecer opções de linha de comando para alterar seu
comportamento.

Veja L<Locale::Po4a::Docbook(3pm)|Locale::Po4a::Docbook>,

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

=over

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

=item type="attribute"

Significa que a string encontrada é o valor de um atributo traduzível. A
entrada "atributo" possui o nome do atributo.

=back

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.

=head2 MODIFICANDO TIPOS DE MARCAÇÕES (A FAZER)

Isso é mais complexo, mas permite quase que uma personalização total. É
baseado em uma lista de hashes, cada um definindo um comportamento do tipo
de marcação. A lista deveria ser organizado de forma que a maioria das
marcações gerais estão após aquelas mais concretas (organizadas primeiro
pelas chaves iniciais e, então, pelas finais). Para definir um tipo de
marcação, você terá que fazer um hash com as seguintes chaves:

=over 4

=item B<beginning>

Especifica o começo da marcação, após do "E<lt>".

=item B<end>

Especifica o fim da marcação, antes do "E<gt>".

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

=item B<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 B<breaking> não estiver.

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

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

=back

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

=head2 TRABALHANDO COM MARCAÇÕES

=over 4

=item get_path()

Essa função retorna o caminho da marcação atual da raiz do documento, na
forma de E<lt>htmlE<gt>E<lt>bodyE<gt>E<lt>pE<gt>.

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.

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

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

Isso funciona no vetor C<< @{$self->{TT}{doc_in}} >> detendo os dados do
documento de entrada e referência indiretamente via C<< $self->shiftline()
>> e C<< $self->unshiftline($$) >>.

=item 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 booleano, que indica se ela deveria ser removida do fluxo de
entrada.

Isso funciona no vetor C<< @{$self->{TT}{doc_in}} >> detendo os dados do
documento de entrada e referência indiretamente via C<< $self->shiftline()
>> e C<< $self->unshiftline($$) >>.

=item get_tag_name(@)

Essa função retorna o nome da marcação passada como um argumento, na forma
de vetor retornado por extract_tag.

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

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

Isso funciona no vetor C<< @{$self->{TT}{doc_in}} >> detendo os dados do
documento de entrada e referência indiretamente via C<< $self->shiftline()
>> e C<< $self->unshiftline($$) >>.

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

=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 string simples com a marcação traduzida.

=back

=head2 TRABALHANDO COM CONTEÚDOS MARCADOS

=over 4

=item treat_content()

Essa função obtém o texto até a próxima tag de quebra (não em linha) do
fluxo de entrada. Traduza-a usando as funções de tradução personalizadas de
cada tipo de marcação.

Isso funciona no vetor C<< @{$self->{TT}{doc_in}} >> detendo os dados do
documento de entrada e referência indiretamente via C<< $self->shiftline()
>> e C<< $self->unshiftline($$) >>.

=back

=head2 TRABALHANDO COM AS OPÇÕES DO MÓDULO

=over 4

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

=back

=head2 OBTENDO TEXTO DO DOCUMENTO DE ENTRADA

=over

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

=over 4

=item B<include>

Isso faz o vetor resultante conter o texto pesquisado

=item B<remove>

Isso remove o fluxo retornado da entrada

=item B<unquoted>

Isso garante que o texto pesquisado não está entre aspas

=item B<regex>

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

=back

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

=item join_lines(@)

Essa função retorna uma string simples com o texto de um vetor de argumentos
(descartando as referências).

=back

=head1 ESTADO DESTE MÓDULO

Esse módulo pode traduzir marcações e atributos.

=head1 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?)

=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 TRADUÇÃO

 Luiz Fernando Ranghetti <elchevive@opensuse.org>
 Rafael Fontenelle <rafaelff@gnome.org>

=head1 COPYRIGHT E LICENÇA

 Copyright © 2004 Jordi Vilalta  <jvprat@gmail.com>
 Copyright © 2008-2009 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 v2.0 ou posterior (veja o arquivo COPYING).
