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). Ele pode levar os seguintes valores:

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.

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 "ontagerror".

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

break-pi

Por padrão, as Instruções de Processamento (ou seja, tags "<? ... ?">) 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.

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.

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

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¶

  $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;

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

FUNÇÕES INTERNAS usadas para escrever analisadores derivados¶

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