LOCALE::PO4A::XML.3PM(1)                   User Contributed Perl Documentation


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

DESCRICAO
       O objetivo do projeto po4a (PO for anything, ou PO para qualquer coisa)
       e facilitar traducoes (e o mais interessante, a manutencao das
       traducoes) usando as ferramentas do gettext em areas em que nao se
       esperava, como documentacao.

       Locale::Po4a::Xml e um modulo para ajudar a traducao de documentos XML
       para outros idiomas. Ele tambem pode ser usado como uma base para
       compilar modulos para documentos baseados em XML.

TRADUZINDO COM PO4A::XML
       Esse modulo pode ser usado diretamente para manipular documentos XML
       genericos. Ele vai extrair o conteudo de todas as marcacoes, porem de
       nenhum atributo, ja que e onde o texto esta escrito na maioria dos
       documentos baseados em XML.

       Ha algumas opcoes (descritas na proxima secao) que podem personalizar
       este comportamento. Se isso nao se adequar ao formato do seu documento,
       encorajamos voce a escrever seu proprio modulo derivado deste, para
       descrever os detalhes do seu formato. Veja a secao abaixo ESCREVENDO
       MODULOS DERIVADOS, para a descricao do processo.

OPCOES ACEITAS POR ESTE MODULO
       A opcao de depuracao global causa esse modulo a mostrar as strings
       excluidas, para ver se ignora alguma coisa importante.

       Estas sao as opcoes especificas deste modulo:

       nostrip
           Previne-o de cortar espacos em volta das strings extraidas.

       wrap
           Canoniza a string para traduzir, considerando que espacos em branco
           nao sao importantes e dimensiona o documento traduzido. Essa opcao
           pode ser sobrescrita por opcoes personalizadas de marcacao. Veja a
           opcao translated abaixo.

       unwrap_attributes
           Atributos sao quebrados por padrao. Essa opcao desabilita a quebra.

       caseinsensitive
           Isso faz com que a pesquisa por marcacoes e atributos funcione de
           uma forma que diferencie letras maiusculas das minusculas. Se essa
           opcao estiver definida, ela vai tratar <BooK>laNG e <BOOK>Lang como
           <book>lang.

       escapequotes
           Escapa aspas em strings de saida. Necessario, por exemplo, para
           criacao de recursos de string para usar por ferramentas de
           compilacao de Android.

           Veja tambem:
           https://developer.android.com/guide/topics/resources/string-resource.html

       includeexternal
           Quando definida, entidades externas sao incluidas no documento
           gerado (traduzido) e para a extracao de strings. Se nao estiver
           definido, voce tera que traduzir entidades externas separadamente
           como documentos independentes.

       ontagerror
           Essa opcao define o comportamento do modulo quando ele encontrar
           uma sintaxe XML invalida (uma marcacao fechando que nao corresponde
           a ultima marcacao abrindo). Ele pode levar os seguintes valores:

           fail
               Esse e o valor padrao. O modulo vai sair com um erro.

           warn
               O modulo vai continuar e vai fazer um aviso.

           silent
               O modulo vai continuar sem qualquer aviso.

           Tenha cuidado ao usar essa opcao. Ela geralmente e recomendada para
           corrigir o arquivo de entrada.

       tagsonly
           Nota: essa opcao e obsoleta.

           Extrai apenas as marcacoes especificadas na opcao tags. Do
           contrario, ela extraira todas as marcacoes, com excecao daquelas
           especificadas.

       doctype
           String que tentara corresponder com a primeira linha do tipo de
           documento (doctype) do documento (se definido). Se nao estiver
           definido, um aviso vai indicar que o documento pode ser um tipo
           incorreto.

       addlang
           String indicando o caminho (ex.: <bbb><aaa>) de uma marcacao na
           qual um atributo lang="..." deve ser adicionado. O idioma sera
           definido como o nome base do arquivo PO sem qualquer extensao.

       optionalclosingtag
           Booleano indicando se as tags de fechamento sao opcionais (como em
           HTML). Por padrao, as tags de fechamento ausentes geram um erro
           tratado de acordo com ontagerror.

       tags
           Nota: Essa opcao e obsoleta. Voce deveria usar as opcoes translated
           e untranslated ao inves dessa.

           Lista separada por espaco de marcacoes que voce deseja traduzir ou
           ignorar. Por padrao, as marcacoes especificadas serao excluidas,
           mas se voce usar a opcao "tagsonly", as marcacoes especificadas
           serao as unicas incluidas. As marcacoes devem estar na forma <aaa>,
           mas voce pode juntar algumas (<bbb><aaa>) para informar que o
           conteudo da tag <aaa> sera traduzido apenas quando ela estiver
           dentro de uma marcacao <bbb>.

           Voce tambem pode especificar algumas opcoes de marcacao para
           colocar alguns caracteres na frente da hierarquia de marcacoes. Por
           exemplo, voce pode colocar um w (wrap) or W (nao aplica wrap) para
           sobrescrever o comportamento padrao especificado pela opcao global
           wrap.

           Exemplo: W<capitulo><titulo>

       attributes
           Lista separada por espaco de atributos da marcacao que voce deseja
           traduzir. Voce pode especificar os atributos por seus nomes (por
           exemplo, "lang"), mas voce pode prefixar com uma hierarquia de
           marcacoes, para especificar que esse atributo vai ser traduzido
           apenas quando ele estiver na marcacao especificada. Por exemplo:
           <bbb><aaa>lang especifica que o atributo lang sera traduzido apenas
           se ele estiver dentro de uma marcacao <aaa> e dentro de uma
           marcacao <bbb>.

       foldattributes
           Nao traduz atributos nas marcacoes integradas. Ao inves disso,
           substitui todos os atributos de uma marcacao por po4a-id=<id>.

           Isso e util quando os atributos nao devam ser traduzidos, pois isso
           simplifica as strings para tradutores e evita erros de escrita.

       customtag
           Lista separada por espaco de marcacoes que nao deveriam ser
           tratadas como marcacoes. Essas marcacoes sao tratadas como
           integradas e nao precisam ser fechadas.

       break
           Lista separada por espaco de marcacoes que deveriam interromper a
           sequencia. Por padrao, todas as marcacoes interrompem a sequencia.

           As marcacoes estar na forma <aaa>, mas voce pode juntar alguns
           (<bbb><aaa>), se uma marcacao (<aaa>) deveria ser considerada
           apenas quando ela estiver dentro de outra marcacao (<bbb>).

           Note que uma tag deve ser listada em apenas uma string de
           configuracao de break, inline placeholder ou customtag.

       inline
           Lista separada por espaco de marcacoes que deveriam ser tratadas
           como integradas. Por padrao, todas as marcacoes interrompem a
           sequencia.

           As marcacoes estar na forma <aaa>, mas voce pode juntar alguns
           (<bbb><aaa>), se uma marcacao (<aaa>) deveria ser considerada
           apenas quando ela estiver dentro de outra marcacao (<bbb>).

       placeholder
           Lista separada por espaco de marcacoes que devem ser tratadas como
           placeholders. Elas nao interrompem a sequencia, mas o conteudo
           desses placeholders e traduzido separadamente.

           A localizacao do placeholder em seu bloco sera marcado com uma
           string similar a:

             <placeholder type=\"footnote\" id=\"0\"/>

           As marcacoes estar na forma <aaa>, mas voce pode juntar alguns
           (<bbb><aaa>), se uma marcacao (<aaa>) deveria ser considerada
           apenas quando ela estiver dentro de outra marcacao (<bbb>).

       break-pi
           Por padrao, as Instrucoes de Processamento (ou seja, tags "<?  ...
           ?>") sao tratadas como tags embutidas. Passe essa opcao se desejar
           que as I.P. sejam tratadas como tag de quebra. Note que tags PHP
           nao processadas sao tratadas como Instrucoes de Processamento pelo
           analisador.

       nodefault
           Lista separada por espaco de marcacoes que o modulo nao deveria
           tentar definir por padrao em qualquer categoria.

           Se voce tiver uma tag que tenha sua configuracao padrao pela
           subclasse deste modulo, mas desejar definir uma configuracao
           alternativa, sera necessario listar essa tag como parte da string
           de configuracao nodefault.

       cpp Diretivas de suporte do preprocessador C. Quando essa opcao esta
           definida, po4a vai considerar as diretivas do preprocessador como
           separadores de paragrafo. Isso e importante se o arquivo XML deve
           ser preprocessado porque, do contrario, as diretivas podem ser
           inseridas no meio de linhas se po4a considerar que elas pertencem
           ao paragrafo atual, e elas nao serao reconhecidas pelo
           preprocessador. Nota: as diretivas do preprocessador devem aparecer
           apenas entre marcacoes (elas nao podem interromper uma marcacao).

       translated
           Lista separada por espaco de marcacoes que voce deseja traduzir.

           As marcacoes estar na forma <aaa>, mas voce pode juntar alguns
           (<bbb><aaa>), se uma marcacao (<aaa>) deveria ser considerada
           apenas quando ela estiver dentro de outra marcacao (<bbb>).

           Voce tambem pode especificar algumas opcoes de marcacao para
           colocar alguns caracteres na frente da hierarquia de marcacoes.
           Isso sobrescreve o comportamento padrao especificado pelas opcoes
           globais wrap e defaulttranslateoption.

           w   Tags deveriam ser traduzidas e o conteudo pode ser
               redimensionado.

           W   Tags deveriam ser traduzidas e o conteudo nao deveria ser
               redimensionado.

           i   Tags deveriam ser traduzidas integradas.

           p   Tags deveriam ser traduzidas como placeholders.

           Internamente, o analisador XML so se preocupa com essas quatro
           opcoes: w W i p.

           * As tags listadas em break sao definidas como w ou W dependendo da
           opcao wrap.

           * As tags listadas em inline sao definidas como i.

           * As tags listadas em placeholder sao definidas como p.

           * As tags listadas em untranslated estao sem nenhuma dessas opcoes
           definidas.

           Voce pode verificar o comportamento real do parametro interno
           invocando po4a com a opcao --debug.

           Exemplo: W<capitulo><titulo>

           Note que uma tag deve estar listada na string de configuracao
           translated ou untranslated.

       untranslated
           Lista separada por espaco de marcacoes que voce nao deseja
           traduzir.

           As marcacoes estar na forma <aaa>, mas voce pode juntar alguns
           (<bbb><aaa>), se uma marcacao (<aaa>) deveria ser considerada
           apenas quando ela estiver dentro de outra marcacao (<bbb>).

           Note que uma tag inline traduzivel em uma tag nao traduzida e
           tratada como uma tag de quebra traduzivel, a configuracao i e
           descartada e w ou W e definida dependendo da opcao wrap.

       defaulttranslateoption
           As categorias padrao para marcacoes que estao em nenhum entre
           "translated", "untranslated", "break", "inline" ou "placeholder".

           Este e um conjunto de letras, conforme definido em translated, e
           essa configuracao e valida apenas para tags traduziveis.

ESCREVENDO MODULOS DERIVADOS
   DEFINA QUAIS MARCACOES E ATRIBUTOS DEVEM SER TRADUZIDOS
       A personalizacao mais simples e definir quais marcacoes e atributos
       voce deseja que o analisador traduzida. Isso deveria ser feito na
       funcao "initialize". Primeiro, voce deveria chamar o "initialize"
       principal, para obter as opcoes de linha de comando e, entao, anexe
       suas definicoes personalizadas aos hash de opcoes. Se voce deseja
       tratar algumas novas opcoes a partir da linha de comando, voce 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;

       Voce deveria usar as opcoes _default_inline, _default_break,
       _default_placeholder, _default_translated, _default_untranslated e
       _default_attributes nos modulos derivados. Isso permite que usuarios
       sobrescrevam o comportamento padrao definido em seu modulo com opcoes
       de linha de comando.

   SUBSTITUICAO DO COMPORTAMENTO PADRAO COM AS OPCOES DE LINHA DE COMANDO
       Se voce nao gostar do comportamento padrao deste modulo xml e seus
       modulos derivados, podera fornecer opcoes de linha de comando para
       alterar seu comportamento.

       Veja Locale::Po4a::Docbook(3pm),

   SOBRESCREVENDO A FUNCAO found_string
       Outro passo simples e sobrescrever a funcao "found_string", que recebe
       as strings extraidas do analisador, para traduzi-las. La, voce pode
       controlar quais strings voce deseja traduzir e realizar transformacoes
       nelas antes ou apos a traducao em si.

       Ela recebe o texto extraido, a referencia de onde ele estava e um hash
       que contem informacoes extras para controlar quais strings devem ser
       traduzidas, como traduzi-las e para gerar o comentario.

       O conteudo dessas opcoes dependem do tipo de string (especificado em
       uma entrada dessa hash):

       type="tag"
           A string encontrada e o conteudo de uma marcacao traduzivel. A
           entrada "tag_options" contem os caracteres da opcao na frente da
           hierarquia de marcacao na opcao "tags" do modulo.

       type="attribute"
           Significa que a string encontrada e o valor de um atributo
           traduzivel. A entrada "atributo" possui o nome do atributo.

       Ela deve retornar o texto que vai substituir o original no documento
       traduzido. Aqui esta um exemplo basico dessa funcao:

         sub found_string {
           my ($self,$text,$ref,$options)=@_;
           $text = $self->translate($text,$ref,"type ".$options->{'type'},
             'wrap'=>$self->{options}{'wrap'});
           return $text;
         }

       Ha um outro exemplo simples no novo modulo do Dia, o qual filtra apenas
       algumas strings.

   MODIFICANDO TIPOS DE MARCACOES (A FAZER)
       Isso e mais complexo, mas permite quase que uma personalizacao total. E
       baseado em uma lista de hashes, cada um definindo um comportamento do
       tipo de marcacao. A lista deveria ser organizado de forma que a maioria
       das marcacoes gerais estao apos aquelas mais concretas (organizadas
       primeiro pelas chaves iniciais e, entao, pelas finais). Para definir um
       tipo de marcacao, voce tera que fazer um hash com as seguintes chaves:

       beginning
           Especifica o comeco da marcacao, apos do "<".

       end Especifica o fim da marcacao, antes do ">".

       breaking
           Informa se essa e uma classe de interrupcao de marcacao. Uma
           marcacao de nao-interrupcao (integrada) e aquela que pode ser
           levada como parte do conteudo de outra marcacao. Ela pode levar os
           valores falso (0), verdadeiro (1) ou indefinido. Se voce deixa-la
           como indefinida, voce tera que definir a funcao f_breaking que vai
           dizer se uma marcacao concreta dessa classe e uma marcacao de
           interrupcao ou nao.

       f_breaking
           Essa e uma funcao que vai dizer se a proxima marcacao e uma de
           interrupcao ou nao. Ela deveria ser definida se a opcao breaking
           nao estiver.

       f_extract
           Se voce deixar essa chave indefinida, a funcao de extracao generica
           tera ela mesma que extrair a marcacao. Isso e util para marcacoes
           que podem ter outras marcacoes ou estruturas especiais nelas, de
           forma que o analisador principal nao fique doido. Essa funcao
           recebe um booleano que informa se a marcacao deveria, ou nao, ser
           removida do fluxo de entrada.

       f_translate
           Essa funcao recebe a marcacao (no formato de get_string_until() ) e
           retorna a marcacao traduzida (atributos traduzidos ou todas as
           transformacoes necessarias) como uma string unica.

FUNCOES INTERNAS usadas para escrever analisadores derivados
   TRABALHANDO COM MARCACOES
       get_path()
           Essa funcao retorna o caminho da marcacao atual da raiz do
           documento, na forma de <html><body><p>.

           Um vetor adicional de marcacoes (sem sinais de maior que, menor
           que) podem ser passados como argumentos. Esses elementos de caminho
           sao adicionados ao final do caminho atual.

       tag_type()
           Essa funcao retorna o indice da lista tag_types que ajusta a
           proxima aba no fluxo de entrada, ou -1 se ela esta ao final do
           arquivo de entrada.

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

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

       extract_tag($$)
           Essa funcao retorna a marcacao seguinte do fluxo de entrada sem o
           inicio e fim, em uma forma de vetor, para manter a referencia do
           arquivo de entrada. Ela tem dois parametros: o tipo da marcacao
           (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 referencia indiretamente via
           "$self->shiftline()" e "$self->unshiftline($$)".

       get_tag_name(@)
           Essa funcao retorna o nome da marcacao passada como um argumento,
           na forma de vetor retornado por extract_tag.

       breaking_tag()
           Essa funcao retorna um booleano que informa se a proxima marcacao
           no fluxo de entrada e uma marcacao de interrupcao ou nao (marcacao
           integrada). Ela deixa o fluxo de entrada intacto.

       treat_tag()
           Essa funcao traduz a proxima marcacao do fluxo de entrada, usando
           as funcoes de traducao personalizada de cada tipo de marcacao.

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

       tag_in_list($@)
           Essa funcao retorna um valor de string que informa se o primeiro
           argumento (uma hierarquia de marcacoes) corresponde a qualquer das
           marcacoes do segundo argumento (uma lista de marcacoes ou
           hierarquias de marcacoes). Se ela nao corresponder, retorna 0. Do
           contrario, retorna as opcoes da marcacao correspondente (os
           caracteres na frente da marcacao) ou 1 (se aquela marcacao nao
           possuir opcoes).

   TRABALHANDO COM ATRIBUTOS
       treat_attributes(@)
           Essa funcao manipula a traducao dos atributos das marcacoes. Ela
           recebe a marcacao sem as marcas de inicio / fim e, entao, ela
           encontra os atributos e traduz os traduziveis (especificado pela
           opcao do modulo attributes). Isso retorna uma string simples com a
           marcacao traduzida.

   TRABALHANDO COM CONTEUDOS MARCADOS
       treat_content()
           Essa funcao obtem o texto ate a proxima tag de quebra (nao em
           linha) do fluxo de entrada. Traduza-a usando as funcoes de traducao
           personalizadas de cada tipo de marcacao.

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

   TRABALHANDO COM AS OPCOES DO MODULO
       treat_options()
           Essa funcao preenche as estruturas internal que contem as
           marcacoes, atributos e dados integrados com as opcoes do modulo
           (especificado na linha de comando ou na funcao "inicialize").

   OBTENDO TEXTO DO DOCUMENTO DE ENTRADA
       get_string_until($%)
           Essa funcao retorna um vetor com as linhas (e referencias) do
           documento de entrada ate encontrar o primeiro argumento. O segundo
           argumento e um hash de opcoes. Valor 0 significa desabilitado (o
           padrao) e 1, habilitado.

           As opcoes validas sao:

           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 nao esta entre aspas

           regex
               Isso indica que o primeiro argumento e uma expressao regular e
               nao uma string simples

       skip_spaces(\@)
           Essa funcao recebe como argumento a referencia para um paragrafo
           (no formato retornado por get_string_until), ignora seu espaco
           inicial e retorna-as como uma string simples.

       join_lines(@)
           Essa funcao retorna uma string simples com o texto de um vetor de
           argumentos (descartando as referencias).

ESTADO DESTE MODULO
       Esse modulo pode traduzir marcacoes e atributos.

LISTA DE TAREFAS
       DOCTYPE (ENTIDADES)

       Ha um suporte minimo para a traducao de entidades. Elas sao traduzidos
       como um todo e marcacoes nao sao levadas em conta. Nao ha suporte a
       entidades multilinhas, sofrendo elas uma quebra de linha durante a
       traducao.

       MODIFICAR TIPOS DE MARCACAO DE MODULOS HERDADOS (move a estrutura de
       tag_types para dentro do $self hash?)

VEJA TAMBEM
       Locale::Po4a::TransTractor(3pm), po4a(7)

AUTORES
        Jordi Vilalta <jvprat@gmail.com>
        Nicolas Francois <nicolas.francois@centraliens.net>

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

COPYRIGHT E LICENCA
        Copyright (C) 2004 Jordi Vilalta  <jvprat@gmail.com>
        Copyright (C) 2008-2009 Nicolas Francois <nicolas.francois@centraliens.net>

       Esse programa e um software livre; voce pode redistribui-lo e/ou
       modifica-lo sob os termos da GPL v2.0 ou posterior (veja o arquivo
       COPYING).

perl v5.42.0                      2025-11-22          LOCALE::PO4A::XML.3PM(1)