Provided by: po4a_0.55-1_all bug

NOME

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

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.

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
           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 translated abaixo.

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

       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.

       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

       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
           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, ou o
           atributo de uma marcação sem valor). Ele pode levar os seguintes valores:

           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
           Nota: essa opção é 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
           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
           Nota: Essa opção é obsoleta. Você deveria usar as opções translated e 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 <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>

       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: <bbb><aaa>lang
           especifica que o atributo lang será traduzido apenas se ele estiver dentro de uma
           marcação <aaa> e dentro de uma marcação <bbb>.

       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.

           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 break,
           inline placeholder ou customtag.

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

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

       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 nodefault.

       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.

           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 wrap e defaulttranslateoption.

           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.

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

             * Tags listadas em B<break> são definidas para I<w> ou I<W> dependendo da opção <wrap>.
             * Tags listadas em B<inline> são definidas para I<i>.
             * Tags listadas em B<placeholder> são definidas para I<p>.
             * Tags listadas em B<untranslated> não são definidas com nenhuma dessas opções.

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

           Exemplo: W<capítulo><título>

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

       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 é descartada e w ou W é definida dependendo da
           opção <wrap>.

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

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.

   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 Locale::Po4a::Docbook(3pm),

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

       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.

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

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

       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 "@{$self->{TT}{doc_in}}" detendo os dados do documento de
           entrada e referência indiretamente via "$self->shiftline()" e
           "$self->unshiftline($$)".

       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.

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

       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 CONTEÚDOS MARCADOS
       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 "@{$self->{TT}{doc_in}}" detendo os dados do documento de
           entrada e referência indiretamente via "$self->shiftline()" e
           "$self->unshiftline($$)".

   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 © 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 (veja o arquivo COPYING).