". Pelo bem da simplicidade, assumimos que o documento está bem formatado, ou seja, que etiquetas \*(Aq
são as etiquetas apenas presentes e que esta marca é no início de cada parágrafo. .PP .Vb 2 \& sub parse { \& my $self = shift; \& \& PARAGRAPH: while (1) { \& my ($paragraph,$pararef)=("",""); \& my $first=1; \& my ($line,$lref)=$self\->shiftline(); \& while (defined($line)) { \& if ($line =~ m/
/ && !$first\-\-; ) { \& # Not the first time we see
. \& # Reput the current line in input, \& # and put the built paragraph to output \& $self\->unshiftline($line,$lref); \& \& # Now that the document is formed, translate it: \& # \- Remove the leading tag \& $paragraph =~ s/^
//s; \& \& # \- push to output the leading tag (untranslated) and the \& # rest of the paragraph (translated) \& $self\->pushline( "
"
\& . $self\->translate($paragraph,$pararef)
\& );
\&
\& next PARAGRAPH;
\& } else {
\& # Append to the paragraph
\& $paragraph .= $line;
\& $pararef = $lref unless(length($pararef));
\& }
\&
\& # Reinit the loop
\& ($line,$lref)=$self\->shiftline();
\& }
\& # Did not get a defined line? End of input file.
\& return;
\& }
\& }
.Ve
.PP
Depois de implementar a função de análise, pode usar a sua classe de
documento, usando a interface pública apresentada na próxima secção.
.SH "INTERFACE PÚBLICA para scripts que usam o seu analisador"
.IX Header "INTERFACE PÚBLICA para scripts que usam o seu analisador"
.SS Construtor
.IX Subsection "Construtor"
.IP process(%) 4
.IX Item "process(%)"
Esta função pode fazer tudo o que precisa fazer com um documento po4a numa
invocação. Os argumentos dela devem ser empacotados como uma \*(Aqhash\*(Aq. AÇÕES:
.RS 4
.IP a. 3
.IX Item "a."
Lê todos os ficheiros PO especificados em po_in_name
.IP b. 3
.IX Item "b."
Lê todos os documentos originais especificados em file_in_name
.IP c. 3
.IX Item "c."
Analisa o documento
.IP d. 3
.IX Item "d."
Lê e aplica todas as adendas especificadas
.IP e. 3
.IX Item "e."
Escreve o documento traduzido para o nome_ficheiro_saída (se dado)
.IP f. 3
.IX Item "f."
Escreve o ficheiro PO extraído para nome_po_saída (se dado)
.RE
.RS 4
.Sp
ARGUMENTOS, além daqueles aceites pelo \fBnew()\fR (com o tipo esperado):
.IP "file_in_name (@)" 4
.IX Item "file_in_name (@)"
Lista de nomes de ficheiros onde devemos ler o documento de entrada.
.IP "file_in_charset ($)" 4
.IX Item "file_in_charset ($)"
Conjunto de caracteres usado no documento de entrada (se não for
especificado, usa UTF\-8).
.IP "file_out_name ($)" 4
.IX Item "file_out_name ($)"
Nome do ficheiro onde devemos escrever o documento de saída.
.IP "file_out_charset ($)" 4
.IX Item "file_out_charset ($)"
Conjunto de caracteres usado no documento de saída (se não for especificado,
usa UTF\-8).
.IP "po_in_name (@)" 4
.IX Item "po_in_name (@)"
Lista de nomes de ficheiros onde devemos ler os ficheiros de entrada do PO,
que contêm a tradução que irá ser usada para traduzir o documento.
.IP "po_out_name ($)" 4
.IX Item "po_out_name ($)"
Nome do ficheiro onde devemos escrever a saída do ficheiro PO, que contém as
cadeias extraídas do documento de entrada.
.IP "addendum (@)" 4
.IX Item "addendum (@)"
Lista de nomes de ficheiros de onde devemos ler a adenda.
.IP "addendum_charset ($)" 4
.IX Item "addendum_charset ($)"
Conjunto de caracteres para a adenda.
.RE
.RS 4
.RE
.IP new(%) 4
.IX Item "new(%)"
Cria um novo documento de po4a. Opções aceites (no hash passado como
parâmetro):
.RS 4
.IP "verbose ($)" 4
.IX Item "verbose ($)"
Define o nível de detalhe.
.IP "debug ($)" 4
.IX Item "debug ($)"
Define a depuração.
.IP "wrapcol ($)" 4
.IX Item "wrapcol ($)"
A coluna na qual devemos fazer a quebra de texto no documento de saída
(predefinição: 76).
.Sp
O valor negativo significa não quebrar as linhas.
.RE
.RS 4
.Sp
Também aceita as próximas opções para ficheiros PO subjacentes: \fBporefs\fR,
\&\fBcopyright\-holder\fR, \fBmsgid\-bugs\-address\fR, \fBpackage\-name\fR,
\&\fBpackage\-version\fR, \fBwrap\-po\fR.
.RE
.SS "Manipulando ficheiros de documentos"
.IX Subsection "Manipulando ficheiros de documentos"
.IP read($$$) 4
.IX Item "read($$$)"
Adiciona outros dados do documento de entrada no final da array existente
\&\f(CW\*(C`@{$self\->{TT}{doc_in}}\*(C'\fR.
.Sp
Esta função recebe dois argumentos obrigatórios e um opcional.
* O nome do ficheiro a ser lido no disco;
* O nome a ser usado como nome do ficheiro ao construir a referência no ficheiro PO;
* O conjunto de caracteres a ser usado para ler esse ficheiro (UTF\-8 por predefinição)
.Sp
Esta matriz \f(CW\*(C`@{$self\->{TT}{doc_in}}\*(C'\fR detém os dados desse documento de
entrada como uma matriz de cadeias com significados alternativos.
* A cadeia \f(CW$textline\fR que detém cada linha de dados de texto de entrada.
* A cadeia \f(CW\*(C`$filename:$linenum\*(C'\fR que detém a sua localização e chamada
como "referência" (\f(CW\*(C`linenum\*(C'\fR starts with 1)..
.Sp
Por favor, note que ele não analisa nada. Deve usar a função \fBparse()\fR quando
está feito com o empacotamento de ficheiros de entrada no documento.
.IP escrever($) 4
.IX Item "escrever($)"
Escreva o documento traduzido no nome do ficheiro dado.
.Sp
Os dados desse documento traduzido são fornecidos por:
* \f(CW\*(C`$self\->docheader()\*(C'\fR a deter o texto de cabeçalho para o plugin e
* \f(CW\*(C`@{$self\->{TT}{doc_out}}\*(C'\fR a deter cada linha do principal texto traduzido na matriz.
.SS "Manipulando ficheiros PO"
.IX Subsection "Manipulando ficheiros PO"
.IP readpo($) 4
.IX Item "readpo($)"
Adiciona o conteúdo dum ficheiro (que o nome é passado como argumento) para
o actual PO de entrada. O conteúdo antigo não é descartado.
.IP writepo($) 4
.IX Item "writepo($)"
Gravar o ficheiro PO extraído no nome do ficheiro dado.
.IP \fBstats()\fR 4
.IX Item "stats()"
Retorna algumas estatísticas sobre a tradução feita até agora. Note que não
é a mesma estatística que aquela escrita por msgfmt\-\-statistic. Aqui, são
estatísticas sobre o uso recente do ficheiro PO, enquanto msgfmt relata o
estado do ficheiro. Ele é um envolvido para função
Locale::Po4a::Po::stats_get aplicada ao ficheiro de entrada PO. Exemplo de
uso:
.Sp
.Vb 1
\& [uso normal do documento po4a...]
\&
\& ($percent,$hit,$queries) = $document\->stats();
\& print "Encontramos traduções para $percent\e% ($hit from $queries) de cadeias.\en";
.Ve
.SS "Manipulando a adenda"
.IX Subsection "Manipulando a adenda"
.IP addendum($) 4
.IX Item "addendum($)"
Por favor, consulte \fBpo4a\fR\|(7) para obter mais informações sobre o
que são adendas e como os tradutores devem escrevê\-las. Para aplicar uma
adenda ao documento traduzido, basta passar o nome do ficheiro para esta
função e está feito ;)
.Sp
Esta função retorna um inteiro não nulo em caso de erro.
.SH "FUNÇÕES INTERNAS usadas para escrever analisadores derivados"
.IX Header "FUNÇÕES INTERNAS usadas para escrever analisadores derivados"
.SS "Obter a entrada, fornecer a saída"
.IX Subsection "Obter a entrada, fornecer a saída"
Quatro funções são fornecidas para obter entrada e retornar a saída. Elas
são muito parecidas com shift/unshift e push/pop de Perl.
.PP
.Vb 4
\& * Perl shift retorna o primeiro item da matriz e solta\-o da matriz.
\&* Perl unshift preenche um item da matriz como o primeiro item da matriz.
\&* Perl pop retorna o último item da matriz e solta\-o da matriz.
\&* Perl push acrescenta um item da matriz como o último item da matriz.
.Ve
.PP
O primeiro par é sobre entrada, enquanto ao segundo é sobre
saída. Mnemônico: na entrada, está interessada na primeira linha, que é o
que o shift fornece e na saída quer adicionar o seu resultado ao final, como
o push faz.
.IP \fBshiftline()\fR 4
.IX Item "shiftline()"
Esta função retorna a primeira linha a ser analisada e a referência dele
correspondente (empacotada como uma matriz) da matriz \f(CW\*(C`@{$self\->{TT}{doc_in}}\*(C'\fR e descarta estes 2 primeiros itens da
matriz. Aqui, a referência é fornecida por uma cadeia \f(CW\*(C`$filename:$linenum\*(C'\fR.
.IP unshiftline($$) 4
.IX Item "unshiftline($$)"
Desloca a última linha deslocada do documento de entrada e a referência dele
correspondente de volta ao cabeçalho de \f(CW\*(C`{$self\->{TT}{doc_in}}\*(C'\fR.
.IP pushline($) 4
.IX Item "pushline($)"
Força uma nova linha no fim de \f(CW\*(C`{$self\->{TT}{doc_out}}\*(C'\fR.
.IP \fBpopline()\fR 4
.IX Item "popline()"
Estoira a última linha forçada do final de \f(CW\*(C`{$self\->{TT}{doc_out}}\*(C'\fR.
.SS "Marcando cadeias como traduzíveis"
.IX Subsection "Marcando cadeias como traduzíveis"
Uma função é fornecida para lidar com o texto que deve ser traduzido.
.IP translate($$$) 4
.IX Item "translate($$$)"
Argumentos obrigatórios:
.RS 4
.IP \- 2
Uma cadeia para traduzir
.IP \- 2
A referência desta cadeia (ou seja, posição no ficheiro de entrada)
.IP \- 2
O tipo desta cadeia (ou seja, a descrição textual do papel estrutural dele;
usado em \fBLocale::Po4a::Po::gettextization()\fR; ver também \fBpo4a\fR\|(7),
secção \fBGettextization: how does it work?\fR)
.RE
.RS 4
.Sp
Esta função também pode ter alguns argumentos extras. Eles devem ser
organizadas como uma \*(Aqhash\*(Aq. Um exemplo:
.Sp
.Vb 2
\& $self\->translate("string","ref","type",
\& \*(Aqwrap\*(Aq => 1);
.Ve
.IP \fBwrap\fR 4
.IX Item "wrap"
booleano que indica se podemos considerar que os espaços em branco na cadeia
não são importantes. Se sim, a função canoniza a cadeia antes de procurar a
tradução ou extraí\-la, e envolve a tradução.
.IP \fBwrapcol\fR 4
.IX Item "wrapcol"
a coluna na qual devemos fazer a quebra da linha (predefinição: o valor de
\&\fBwrapcol\fR especificado durante a criação do TransTractor ou 76).
.Sp
O valor negativo será subtraído da predefinição.
.IP \fBcomment\fR 4
.IX Item "comment"
um comentário adicional para a entrada.
.RE
.RS 4
.Sp
Ações:
.IP \- 2
Coloca a cadeia de referência e tipo em po_out.
.IP \- 2
Retorna a tradução da cadeia (como encontrada em po_in), de modo que o
analisador pode construir o doc_out.
.IP \- 2
Lida com os conjuntos de caracteres para recodificar as cadeias antes de as
enviar para po_out e antes de voltar às traduções.
.RE
.RS 4
.RE
.SS "Funções diversas"
.IX Subsection "Funções diversas"
.IP \fBverbose()\fR 4
.IX Item "verbose()"
Retorna se a opção \*(Aqverbose\*(Aq foi passada durante a criação do TransTractor.
.IP \fBdebug()\fR 4
.IX Item "debug()"
Retorna se a opção de depuração foi passada durante a criação
doTransTractor.
.IP \fBget_in_charset()\fR 4
.IX Item "get_in_charset()"
Esta função retorna o charset que foi fornecido como o conjunto de
caracteres mestre
.IP \fBget_out_charset()\fR 4
.IX Item "get_out_charset()"
Esta função irá retornar o conjunto de carácteres, que deviam ser usados na
saída (em geral, útil para substituir os conjuntos de carácteres detetados à
entrada do documento onde foi encontrado).
.Sp
Vai usar o conjunto de caracteres de saída especificado na linha de
comando. Se não fosse especificado, seria usado o conjunto de caracteres do
PO de entrada e, se a entrada de PO tem o "CHARSET" predefinido, irá
retornar um conjunto de carácteres do documento de entrada, de modo a que
nenhuma codificação é realizada.
.SH "DIREÇÕES FUTURAS"
.IX Header "DIREÇÕES FUTURAS"
Uma falha do TransTractor atual é que ele não pode tratar de documentos
traduzidos que contém todos os idiomas, como modelos debconf, ou ficheiros
\&.desktop.
.PP
Para resolver este problema, as únicas mudanças na interface necessárias
são:
.IP \- 2
obter um \*(Aqhash\*(Aq como po_in_name (uma lista por idioma)
.IP \- 2
adicionar um argumento para traduzir para indicar a língua apontada
.IP \- 2
fazer uma função pushline_all, que deveria fazer pushline do conteúdo dele
para todos idiomas, a usar uma sintaxe tipo mapa:
.Sp
.Vb 3
\& $self\->pushline_all({ "Description[".$langcode."]=".
\& $self\->translate($line,$ref,$langcode)
\& });
.Ve
.PP
Vamos ver se é suficiente ;)
.SH AUTORES
.IX Header "AUTORES"
.Vb 3
\& Denis Barbier