Provided by: po4a_0.55-1_all bug

NOME

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

DESCRIÇÃO

       O objetivo do projeto po4a (PO para tudo) é facilitar traduções (e mais interessante, a
       manutenção das traduções) usando ferramentas gettext em áreas onde eles não eram esperados
       como documentação.

       Locale::Po4a::Xml é um módulo para ajudar a tradução de documentos XML em outro idioma
       [humano]. Também pode ser usado como uma base para a construção de módulos de documentos
       com base em XML.

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, não atributos, 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 WRITING DERIVATE MODULES abaixo, para descrição do processo.

OPÇÕES ACEITES POR ESTE MÓDULO

       A opção de depuração global faz com que este módulo mostre as sequências excluídas, para
       ver se ele ignora algo importante.

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

       nostrip
           Impede-o para tirar os espaços em torno das sequências 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 translated option below.

       unwrap_attributes
           Attributes are wrapped by default. This option disables wrapping.

       caseinsensitive
           Faz as etiquetas e atributos procurando trabalhar de forma em maiúsculas e minúsculas.
           Se for definido, ele vai tratar <BooKe<gt>laNG e <BOOK>Lang como <book>lang.

       escapequotes
           Escape quotes in output strings.  Necessary, for example, for creating string
           resources for use by Android build tools.

           See also: https://developer.android.com/guide/topics/resources/string-resource.html

       includeexternal
           Quando definido, entidades externas estão incluídas no documento gerado (traduzido) e,
           para a extração de sequências. Se não for definido, você vaiter que traduzir entidades
           externas separadamente como documentos independentes.

       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,
           ou um atributo de marca sem valor). Ele pode ter os seguintes valores:

           fail
               Este é o valor padrão. O módulo irá sair com um erro.

           warn
               O módulo continuará e emitirá um aviso

           silent
               O módulo vai continuar sem emitir um aviso.

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

       tagsonly
           Nota: Esta opção está obsoleta.

           Extrai apenas as etiquetas especificados na opção "tags". Caso contrário, ele irá
           extrair todas as marcas, exceto os especificados.

       doctype
           A sequência 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 mau.

       addlang
           A sequência indicando o caminho (por exemplo, <bbb><AAA>) 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.

       tags
           Nota: Esta opção está obsoleta. Você deve usar as opções translated e untranslated em
           vez.

           Lista de etiquetas separada por espaços que deseja traduzir ou ignorar. Por padrão, as
           etiquetas especificadas serão excluídas, mas se você usar a opção "tagsonly",
           etiquetas especificadas serão as únicas incluídas. As etiquetas devem estar em forma
           <aaa>, mas podem-se juntar a algum (<bbb><aaa>) para dizer de que o conteúdo da
           etiqueta <aaa> só será traduzido quando está numaetiqueta <bbb>.

           Você também pode especificar algumas opções de etiquetas, colocando alguns carateres
           em frente da hierarquia de etiquetas. Por exemplo, você pode colocar 'w' (wrap) ou 'W'
           (don't wrap) para substituir o comportamento padrão especificado pela opção global
           "wrap".

           Exemplo: W<chapter><title>

       attributes
           Lista de atributos das etiquetas separada por espaços que deseja traduzir. Você pode
           especificar os atributos pelo nome deles (por exemplo, "lang"), mas você pode prefixar
           com uma hierarquia de etiquetas, para especificar que este atributo só será traduzido
           quando está na etiqueta especificada. Por exemplo:<bbb><aaa>lang especifica que o
           atributo lang só será traduzido se for em numa etiquetas <aaa>, e é numa etiqueta
           <bbb>.

       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 sequências
           para tradutores e evita erros de digitação.

       customtag
           lista de etiquietas 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.

       break
           Lisat de etiquetas separada por espaços que devem quebrar a sequência. Por padrão,
           todas as etiquetas quebrar a sequência.

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

           Please note a tag should be listed in only one of the break, inline placeholder, or
           customtag setting string.

       inline
           Lista de etiquetas separada por espaços que devem ser tratados como em linha. Por
           padrão, todas as etiquetas quebram a sequência.

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

       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 seu bloco será marcado com uma sequência
           semelhante a:

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

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

       nodefault
           lista de etiquetas separadas por espaço que o módulo não deve tentar definir por
           padrão em qualquer categoria.

           If you have a tag which has its default setting by the subclass of this module but you
           want to set alternative setting, you need to list that tag as a part of the nodefault
           setting string.

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

       translated
           Listas de etiquetas separadas por espaços que quer traduzir.

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

           You can also specify some tag options by putting some characters in front of the tag
           hierarchy.  This overrides the default behavior specified by the global wrap and
           defaulttranslateoption option.

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

           W   Etiquetas devem ser traduzidos e o conteúdo não pode ser re-envolvido

           i   As tags deverão ser traduzidas em linha

           p   Etiquetas devem ser traduzidos em linha.

           Internally, the XML parser only cares about these four options: w W i p.

             * Tags listed in B<break> are set to I<w> or I<W> depending on the <wrap> option.
             * Tags listed in B<inline> are set to I<i>.
             * Tags listed in B<placeholder> are set to I<p>.
             * Tags listed in B<untranslated> are without any of these options set.

           You can verify actual internal parameter behavior by invoking po4a with --debug
           option.

           Exemplo: W<chapter><title>

           Please note a tag should be listed in either translated or untranslated setting
           string.

       untranslated
           Listas de etiquetas separadas por espaços que não quer traduzir.

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

           Please note a translatable inline tag in an untranslated tag is treated as a
           translatable breaking tag, i setting is dropped and w or W is set depending on the
           <wrap> option.

       defaulttranslateoption
           As categorias padrão para etiquetas que não estão em nenhum dos traduzidosnão
           traduzidos, partidos, em  linha, ou espaço reservado.

           This is a set of letters as defined in translated and this setting is only valid for
           translatable tags.

WRITING DERIVATIVE MODULES

   DEFINIR QUE ETIQUETAS E ATRIBUTOS PARA TRADUÇÃO
       A mais simples personalização é definir quais as etiquetas e atributos mais desejados para
       o analisador de traduzir. Isto deve ser feito na função 'initialize'. Primeiro, você 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
       algumas novas opções de linha de comando, você 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;

       You should use the _default_inline, _default_break, _default_placeholder,
       _default_translated, _default_untranslated, and _default_attributes options in derivative
       modules. This allow users to override the default behavior defined in your module with
       command line options.

   OVERRIDE THE DEFAULT BEHAVIOR WITH COMMAND LINE OPTIONS
       If you don't like the default behavior of this xml module and its derivative modules, you
       can provide command line options to change their behavior.

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

   SUBSTITUINDO A FUNÇÃO found_string
       Outro passo simples é substituir a função "found_string", que recebe as sequências
       extraídas do analisador, a fim de traduzi-las.Lá pode controlar quais linhas você 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 o que sequências a traduzir, como traduzi-las e gerar o
       comentário.

       O conteúdo dessas opções depende do tipo de sequência é (especificado numa entrada do
       'hash'):

       type="tag"
           A sequência encontrada é o conteúdo de uma etiqueta traduzível. A entrada
           "tag_options" contém os carateres de opção na frente da hierarquia das etiquetas na
           opção do módulo "tags".

       type="attribute"
           Significa que a sequência encontrada é o valor de um atributo traduzível. A entrada
           "attribute" tem o nome do atributo.

       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 sequências.

   MODIFICANDO TIPOS DE ETIQUETAS (A FAZER)
       Este é mais complexo, mas permite uma personalização (quase) total. É baseado em uma lista
       de 'hashes', cada uma definindo o comportamento de um tipo de etiqueta. A lista deve ser
       ordenada para que as etiquetas mais gerais estão antes das mais concretas (ordenadas
       primeiro no início e, depois, por as chaves de fecho). Para definir um tipo de etiqueta
       você vai ter que fazer um hash com as seguintes chaves:

       beginning
           Especifice o princípio da etiqueta, depois de "<".

       end Especifice o fim da etiqueta, depois de ">".

       breaking
           Ele 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 uma outra etiqueta. Pode
           levar o valor falso (0), verdadeiro (1) ou indefinido. Se você deixar este indefinido,
           você 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.

       f_breaking
           É uma função que vai dizer se a próxima etiqueta é uma quebra ou não. Ele deve ser
           definido se a opção breaking não é.

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

       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
           sequência.

INTERNAL FUNCTIONS used to write derivative parsers

   TRABALHANDO COM ETIQUETAS
       get_path()
           Esta função retorna o caminho para a etiqueta corrente a partir da raiz do documento
           na forma <html><body><p>.

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

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

           Here, the tag has structure started by < and end by > and it can contain multiple
           lines.

           This works on the array "@{$self->{TT}{doc_in}}" holding input document data and
           reference indirectly via "$self->shiftline()" and "$self->unshiftline($$)".

       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.

           This works on the array "@{$self->{TT}{doc_in}}" holding input document data and
           reference indirectly via "$self->shiftline()" and "$self->unshiftline($$)".

       get_tag_name(@)
           Esta função retorna o nome da etiqueta passada como um argumento, no formulário da
           matriz retornada por extract_tag.

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

       treat_tag()
           Essa função converte a próxima etiqueta a partir do fluxo de entrada. Usando em cada
           etiqueta tipos personalizados de funções de tradução.

           This works on the array "@{$self->{TT}{doc_in}}" holding input document data and
           reference indirectly via "$self->shiftline()" and "$self->unshiftline($$)".

       tag_in_list($@)
           Esta função retorna um valor de sequência que diz que se o primeiro argumento (a
           hierarquia das etiquetas) corresponde a qualquer uma das etiquetas do segundo
           argumento (a lista de etiquetas ou a sua hierarquia). Se não corresponder, ele retorna
           0. contrário, retorna as opções de etiqueta correspondentes (os carateres de frente da
           etiqueta) ou 1 (se a etiqueta não tem opções).

   TRABALHANDO COM ATRIBUTOS
       treat_attributes(@)
           Essa função manipula a tradução de atributos das etiquetas. Recebe a etiqueta sem as
           marcas de início/fim e, em seguida encontram os atributos, e traduz as traduzíveis
           (especificado pela opção do módulo "atributos"). Este retorna uma sequência simples
           com a etiqueta traduzida.

   WORKING WITH TAGGED CONTENTS
       treat_content()
           This function gets the text until the next breaking tag (not inline) from the input
           stream.  Translate it using each tag type's custom translation functions.

           This works on the array "@{$self->{TT}{doc_in}}" holding input document data and
           reference indirectly via "$self->shiftline()" and "$self->unshiftline($$)".

   TRABALHANDO COM OPÇÕES DE MÓDULOS
       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).

   OBTENÇÃO DE TEXTO A PARTIR DO DOCUMENTO DE ENTRADA
       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 (o padrão) e 1, ativado.

           As opções válidas são:

           include
               Isto faz com que a matriz retornada contenha o texto procurado

           remove
               Isto remove o fluxo retornado a partir da entrada

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

       skip_spaces(\@)
           Esta função recebe como argumento a referência a um parágrafo (no formato retornado
           por get_string_until), ignora seus espaços de título e retorna-os como uma sequência
           simples.

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

STATUS DESTE MÓDULO

       Este módulo pode traduzir etiquetas e atributos.

LISTA PARAFAZER

       DOCTYPE (ENTITIES)

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

VER TAMBÉM

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

AUTORES

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

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 é software livre, você pode redistribuí-lo e/ou modificá-lo sob os termos da
       GPL (consulte o ficheiro CÓPIA).