
        *****************************************************
        *           GENERATED FILE, DO NOT EDIT             *
        * THIS IS NO SOURCE FILE, BUT RESULT OF COMPILATION *
        *****************************************************

This file was generated by po4a(7). Do not store it (in VCS, for example),
but store the PO file used as source file by po4a-translate.

In fact, consider this as a binary, and the PO file as a regular .c file:
If the PO get lost, keeping this translation up-to-date will be harder.

=encoding UTF-8

=head1 NOME

Locale::Po4a::Xml - converte documenti XML e derivati da/verso file PO

=head1 DESCRIZIONE

L'obiettivo del progetto po4a (PO per tutto) è di facilitare le traduzioni
(e cosa più interessante, la manutenzione delle traduzioni) usando gli
strumenti associati a gettext in aree inaspettate come la documentazione.

Locale::Po4a::Xml è un modulo che aiuta la traduzione in altre lingue della
documentazione in formato XML. Può anche essere usato come base per scrivere
moduli per documenti basati su XML.

=head1 TRADURRE CON PO4A::XML

Questo modulo può essere utilizzato direttamente per gestire documenti XML
generici. Estrarrà tutto il contenuto del tag e nessun attributo, poiché è
lì che viene scritto il testo nella gran parte dei documenti basati su XML.

Ci sono alcune opzioni (descritte nella sezione successiva) che possono
personalizzare questo comportamento.  Se questo non dovesse adattarsi
sufficientemente al formato del proprio documento si incoraggia a scriverne
uno per il proprio modulo derivandolo da questo, per descrivere i dettagli
del proprio formato. Consultare la prossima sezione B<SCRIVERE MODULI
DERIVATI> più sotto, per la descrizione del processo.

=head1 OPZIONI ACCETTATE DA QUESTO MODULO

L'opzione di debug globale fa sì che questo modulo mostri le stringhe
escluse, per vedere se salta qualcosa di importante.

Queste sono le opzioni speciali per questo modulo:

=over 4

=item B<nostrip>

Previene la rimozione degli spazi attorno alle stringhe estratte.

=item B<wrap>

Canonizza la stringa da tradurre, considerando che gli spazi bianchi non
siano importanti, e formatta il documento tradotto. Questa opzione può
essere superata da opzioni tag personalizzate. Vedere l'opzione
B<translated> sotto.

=item B<unwrap_attributes>

Gli attributi vengono formattati per impostazione predefinita. Questa
opzione disabilita la formattazione.

=item B<caseinsensitive>

Fa in modo che la ricerca di tag e attributi funzioni senza distinzione tra
maiuscole e minuscole. Se è definito, tratterà E<lt>BookE<gt>laNG ed
E<lt>BOOKE<gt>Lang come E<lt>bookE<gt>lang.

=item B<escapequotes>

Virgolette di escape nelle stringhe in uscita. Necessario, ad esempio, per
creare risorse stringa da utilizzare con gli strumenti di build Android.

Vedere anche:
https://developer.android.com/guide/topics/resources/string-resource.html

=item B<includeexternal>

Se definite, le entità esterne verranno incluse nel documento generato
(tradotto) e per l'estrazione delle stringhe. Se non è definito, si dovrà
tradurre gli elementi esterni separatamente come documenti indipendenti.

=item B<ontagerror>

Questa opzione definisce il comportamento del modulo quando incontra una
sintassi XML non valida (un tag di chiusura che non corrisponde all'ultimo
tag di apertura). Può assumere i seguenti valori:

=over

=item I<fail>

Questo è il valore predefinito. Il modulo uscirà con un errore.

=item I<warn>

L'esecuzione del modulo continuerà, e genererà un avvertimento.

=item I<silent>

Il modulo continuerà senza alcun avvertimento.

=back

Attenzione a usare questa opzione.  Generalmente si raccomanda di sistemare
il file in ingresso.

=item B<tagsonly>

Nota: questa opzione è sconsigliata.

Estrae solo i tag specificati nell'opzione B<tags>. Altrimenti, estrarrà
tutti i tag tranne quelli specificati.

=item B<doctype>

Stringa di cui verrà verificata la corrispondenza con la prima riga del
doctype del documento (se definito). Nel caso non corrisponda, un avviso
indicherà che il documento potrebbe essere di tipo non valido.

=item B<addlang>

Stringa indicante il percorso (es. E<lt>bbbE<gt>E<lt>aaaE<gt>) di un tag a
cui deve essere aggiunto un attributo lang="...". La lingua sarà definita
come il nome di base del file PO senza alcuna estensione .po.

=item B<optionalclosingtag>

Valore booleano indicante se i tag di chiusura sono facoltativi (come in
HTML). Per impostazione predefinita, i tag di chiusura mancanti generano un
errore gestito secondo B<ontagerror>.

=item B<tags>

Nota: questa opzione è sconsigliata. In alternativa si consiglia di usare le
opzioni B<translated> e B<untranslated>.

Elenco separato da spazi di tag che si vuole tradurre o saltare. Per
impostazione predefinita, i tag specificati verranno esclusi, ma se si usa
l'opzione "tagsonly", i tag specificati saranno gli unici inclusi. I tag
devono essere nella forma E<lt>aaaE<gt>, ma si può unirne alcuni
(E<lt>bbbE<gt>E<lt>aaaE<gt>) per dire che il contenuto del tag E<lt>aaaE<gt>
verrà tradotto solo quando è in un tag E<lt>bbbE<gt>.

Si può anche specificare alcune opzioni di tag inserendo alcuni caratteri
davanti alla gerarchia dei tag. Ad esempio, si può inserire I<w> (a capo) o
I<W> (non a capo) per sovrascrivere il comportamento predefinito specificato
dall'opzione globale B<wrap>.

Esempio: WE<lt>chapterE<gt>E<lt>titleE<gt>

=item B<attributes>

Elenco separato da spazi di attributi del tag che si desidera tradurre. Si
può specificare gli attributi in base al loro nome (ad esempio, "lang"), ma
si può anche anteporre una gerarchia di tag, per specificare che questo
attributo verrà tradotto solo quando si trova nel tag specificato. Ad
esempio: E<lt>bbbE<gt>E<lt>aaaE<gt>lang specifica che l'attributo lang verrà
tradotto solo se si trova in un tag E<lt>aaaE<gt> in un tag E<lt>bbbE<gt>.

=item B<foldattributes>

Non tradurre gli attributi nei tag in linea. Invece, sostituisci tutti gli
attributi di un tag con po4a-id=<id>.

Utile quando gli attributi non devono essere tradotti, poiché semplifica le
stringhe per i traduttori ed evita errori di battitura.

=item B<customtag>

Elenco separato da spazi di tag che non devono essere trattati come
tag. Questi tag sono trattati come in linea e non devono essere chiusi.

=item B<break>

Elenco separato da spazi di tag che dovrebbero interrompere la sequenza. Per
impostazione predefinita, tutti i tag interrompono la sequenza.

I tag devono essere nella forma <aaa>, ma si possono unire ad altri, ad
esempio (<bbb><aaa>), se il tag (<aaa>) deve essere considerato solo quando
si trova all'interno di un altro tag (<bbb>).

Tenere presente che un tag deve essere elencato solo in una delle stringhe
di impostazione B<break>, B<inline> B<placeholder> o B<customtag>.

=item B<inline>

Elenco separato da spazi di tag che devono essere trattati come in
linea. Per impostazione predefinita, tutti i tag interrompono la sequenza.

I tag devono essere nella forma <aaa>, ma si possono unire ad altri, ad
esempio (<bbb><aaa>), se il tag (<aaa>) deve essere considerato solo quando
si trova all'interno di un altro tag (<bbb>).

=item B<placeholder>

Elenco separato da spazi di tag che devono essere trattati come
segnaposto. I segnaposto non interrompono la sequenza, ma il contenuto dei
segnaposto viene tradotto separatamente.

La posizione del segnaposto nel suo blocco sarà contrassegnata da una
stringa simile a:

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

I tag devono essere nella forma <aaa>, ma si possono unire ad altri, ad
esempio (<bbb><aaa>), se il tag (<aaa>) deve essere considerato solo quando
si trova all'interno di un altro tag (<bbb>).

=item B<break-pi>

Per impostazione predefinita, le istruzioni di elaborazione (ovvero i tag
C<E<lt>? ... ?E<gt>>) vengono gestite come tag in linea. Passare questa
opzione se si vuole che il PI venga gestito come tag di rottura. Si noti che
i tag PHP non elaborati vengono gestiti come istruzioni di elaborazione
dall'analizzatore.

=item B<nodefault>

Elenco di tag separati da spazi che il modulo non dovrebbe provare a
impostare per impostazione predefinita in nessuna categoria.

Se si ha un tag che ha la sua impostazione predefinita dalla sottoclasse di
questo modulo ma si vuole impostare un'impostazione alternativa, si deve
elencare quel tag come parte della stringa di impostazione B<nodefault>.

=item B<cpp>

Supporta le direttive del preprocessore C. Quando questa opzione è
impostata, po4a considererà le direttive del preprocessore come separatori
di paragrafo. Ciò è importante se il file XML deve essere preprocessato
perché altrimenti le direttive potrebbero essere inserite in mezzo alle
righe, se po4a le considerasse appartenenti al paragrafo corrente, e quindi
non verrebbero riconosciute dal preprocessore. Nota: le direttive del
preprocessore devono apparire solo tra i tag (non devono interrompere un
tag).

=item B<translated>

Elenco separato da spazi di marcatori che si intende tradurre.

I tag devono essere nella forma <aaa>, ma si possono unire ad altri, ad
esempio (<bbb><aaa>), se il tag (<aaa>) deve essere considerato solo quando
si trova all'interno di un altro tag (<bbb>).

Si può inoltre specificare alcune opzioni di tag, inserendo alcuni caratteri
davanti alla gerarchia dei tag. Ciò supera il comportamento predefinito
specificato dalle opzioni globali B<wrap> e B<defaulttranslateoption>.

=over

=item I<w>

I tag devono essere tradotti e il contenuto può essere riformattatato.

=item I<W>

I tag devono essere tradotti e il contenuto non può essere riformattatato.

=item I<i>

I tag devono essere tradotti in linea.

=item I<p>

I tag devono essere tradotti come segnaposto.

=back

Internamente, l'analizzatore XML si preoccupa solo di queste quattro
opzioni: I<w> I<W> I<i> I<p>.

* I tag elencati in B<break> sono impostati a I<w> o I<W> a seconda
dell'opzione B<wrap>.

* I tag elencati in B<inline> sono impostati a I<i>.

* I tag elencati in B<placeholder> sono impostati a I<p>.

* I tag elencati in B<untranslated> sono senza alcuna di queste opzioni
impostate.

È possibile verificare il comportamento effettivo dei parametri interni
invocando B<po4a> con l'opzione B<--debug>.

Esempio: WE<lt>chapterE<gt>E<lt>titleE<gt>

Si noti che un tag va elencato nella stringa di impostazione B<translated> o
B<untranslated>.

=item B<untranslated>

Elenco separato da spazi di marcatori che non si intende tradurre.

I tag devono essere nella forma <aaa>, ma si possono unire ad altri, ad
esempio (<bbb><aaa>), se il tag (<aaa>) deve essere considerato solo quando
si trova all'interno di un altro tag (<bbb>).

Si noti che un tag in linea traducibile in un tag non tradotto viene
trattato come un tag di rottura traducibile, l'impostazione I<i> viene
eliminata e I<w> o I<W> viene impostato a seconda dell'opzione B<wrap>.

=item B<defaulttranslateoption>

Le categorie predefinite, per i tag che non fanno parte di translated,
untranslated, break, inline o placeholder.

È un insieme di lettere come definito in B<translated> e questa impostazione
è valida solo per i tag traducibili.

=back

=head1 SCRIVERE MODULI DERIVATI

=head2 DEFINIRE CHE MARCATORI E ATTRIBUTI TRADURRE

La personalizzazione più semplice consiste nel definire quali tag e
attributi si desidera che l'analizzatore traduca. Ciò dovrebbe essere fatto
nella funzione di inizializzazione. Per prima cosa si dovrebbe chiamare
l'inizializzazione principale, per ottenere le opzioni della riga di
comando, quindi aggiungere le proprie definizioni personalizzate all'hash
delle opzioni. Se vuole trattare alcune nuove opzioni dalla riga di comando,
si deve definirle prima di chiamare l'inizializzazione principale:

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

Si dovrebbe usare le opzioni B<_default_inline>, B<_default_break>,
B<_default_placeholder>, B<_default_translated>, B<_default_untranslated> e
B<_default_attributes> nei moduli derivati. Ciò consente di superare il
comportamento predefinito definito nel modulo, con le opzioni a riga di
comando.

=head2 SUPERARE IL COMPORTAMENTO PREDEFINITO CON OPZIONI DA RIGA DI COMANDO

Se non ci piace il comportamento predefinito di questo modulo xml e dei suoi
moduli derivati, si può fornire delle opzioni a riga di comando per
modificarne il comportamento.

Consultare L<Locale::Po4a::Docbook(3pm)|Locale::Po4a::Docbook>,

=head2 SOSTITUZIONE DELLA FUNZIONE found_string

Un altro semplice passo è fare l'override della funzione "found_string", che
riceve le stringhe estratte dall'analizzatore, in modo da tradurle. Lì si
può controllare quali stringhe si vuole tradurre ed eseguire trasformazioni
su esse, prima o dopo la traduzione stessa.

Riceve il testo estratto, il riferimento su dove si trovava e un hash che
contiene informazioni extra per controllare quali stringhe tradurre, come
tradurle e generare il commento.

Il contenuto di queste opzioni dipende dal tipo di stringa (specificato in
una voce di questo hash):

=over

=item type="tag"

La stringa trovata è il contenuto di un tag traducibile. La voce
"tag_options" contiene i caratteri dell'opzione prima della gerarchia delle
variabili nell'opzione "tag" del modulo.

=item type="attributo"

Significa che la stringa trovata è il valore di un attributo traducibile. La
voce "attributo" ha il nome dell'attributo.

=back

Deve restituire il testo che sostituirà l'originale nel documento
tradotto. Ecco un esempio di base di questa funzione:

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

C'è un altro semplice esempio nel nuovo modulo Dia, che filtra solo alcune
stringhe.

=head2 MODIFICA DEI TIPI DI TAG (TODO)

Questo è più complesso, ma consente una personalizzazione (quasi) totale. Si
basa su un elenco di hash, ognuno dei quali definisce il comportamento di un
tipo di tag. L'elenco dovrebbe essere ordinato in modo che i tag più
generali vengano dopo quelli più specifici (ordinati prima per l'inizio e
poi per le chiavi di fine). Per definire un tipo di tag si dovrà creare un
hash con le seguenti chiavi:

=over 4

=item B<beginning>

Specifica l'inizio del tag, dopo del "E<lt>".

=item B<end>

Specifica la fine del tag, prima del "E<gt>".

=item B<breaking>

Indica se la classe tag è una classe di tag di interruzione (breaking). Un
tag di non interruzione (non-breaking) (in linea) è untag che può essere
preso come parte del contenuto di un altro tag. Può assumere i valori falso
(0), vero (1) o non definito. Se si lascia indefinito, si dovrà definire la
funzione f_breaking che dirà se un tag effettivamente di questa classe è un
tag di interruzione o meno.

=item B<f_breaking>

È una funzione che dirà se il tag successivo è di interruzione o
meno. Dovrebbe essere definita se l'opzione B<breaking> non lo è.

=item B<f_extract>

Se si lascia questa chiave indefinita, la funzione di estrazione generica
dovrà estrarre il tag stesso. È utile per i tag che possono avere altri tag
o strutture speciali al loro interno, in modo che l'analizzatore principale
non vada in confusione. Questa funzione riceve un booleano che dice se il
tag deve essere rimosso o meno dal flusso di ingresso.

=item B<f_translate>

Questa funzione riceve il tag (nel formato get_string_until()) e restituisce
il tag tradotto (attributi tradotti o tutte le trasformazioni necessarie) in
forma di stringa singola.

=back

=head1 FUNZIONI INTERNE usate per scrivere parser derivati

=head2 LAVORARE CON I TAG

=over 4

=item get_path()

Questa funzione restituisce il percorso del tag corrente dalla radice del
documento, nella forma E<lt>htmlE<gt>E<lt>bodyE<gt>E<lt>pE<gt>.

Si può passare come argomento anche una schiera array di tag (senza
parentesi) aggiuntivi. Questi elementi del percorso vengono aggiunti alla
fine del percorso corrente.

=item tag_type()

Questa funzione restituisce l'indice dall'elenco tag_types che si adatta al
tag successivo nel flusso di ingresso o -1 se si trova alla fine del file di
ingresso.

Qui, il tag ha una struttura che inizia con E<lt> e finisce con E<gt> e può
contenere più righe.

Questo funziona sull'array C<< @{$self->{TT}{doc_in}} >> che contiene i dati
del documento in ingresso e fa riferimento indirettamente tramite C<<
$self->shiftline() >> e C<< $self- >unshiftline($$) >>.

=item extract_tag($$)

Questa funzione restituisce il tag successivo dal flusso di ingresso senza
l'inizio e la fine, in forma di matrice, per mantenere i riferimenti dal
file di ingresso. Ha due parametri: il tipo del tag (come restituito da
tag_type) e un valore booleano, che indica se deve essere rimosso dal flusso
di ingresso.

Questo funziona sull'array C<< @{$self->{TT}{doc_in}} >> che contiene i dati
del documento in ingresso e fa riferimento indirettamente tramite C<<
$self->shiftline() >> e C<< $self- >unshiftline($$) >>.

=item get_tag_name(@)

Questa funzione restituisce il nome del tag passato come argomento, nel
formato array restituito da extract_tag.

=item breaking_tag()

Questa funzione restituisce un valore booleano che dice se il tag successivo
nel flusso di ingresso è un tag di interruzione o meno (tag in
linea). Lascia intatto il flusso di ingresso.

=item treat_tag()

Questa funzione traduce il tag successivo dal flusso di ingresso. Usata
dalle funzioni di traduzione personalizzate di tutti i tipi di tag.

Questo funziona sull'array C<< @{$self->{TT}{doc_in}} >> che contiene i dati
del documento in ingresso e fa riferimento indirettamente tramite C<<
$self->shiftline() >> e C<< $self- >unshiftline($$) >>.

=item tag_in_list($@)

Questa funzione restituisce un valore stringa che indica se il primo
argomento (una gerarchia di tag) corrisponde a uno dei tag del secondo
argomento (un elenco di tag o gerarchie di tag). Se non corrisponde,
restituisce 0. Altrimenti, restituisce le opzioni del tag corrispondente (i
caratteri davanti al tag) o 1 (se quel tag non ha opzioni).

=back

=head2 LAVORARE CON GLI ATTRIBUTI

=over 4

=item treat_attributes(@)

Questa funzione gestisce la traduzione degli attributi dei tag. Riceve il
tag senza i segni di inizio/fine, quindi trova gli attributi e traduce
quelli traducibili (specificati dall'opzione del modulo B<attributes>). Ciò
restituisce una stringa semplice con il tag tradotto.

=back

=head2 LAVORARE CON CONTENUTI MARCATI

=over 4

=item treat_content()

Questa funzione ottiene il testo fino al successivo tag di interruzione (non
in linea) dal flusso di ingresso. La si traduca usando le funzioni di
traduzione personalizzate di ciascun tipo di tag.

Questo funziona sull'array C<< @{$self->{TT}{doc_in}} >> che contiene i dati
del documento in ingresso e fa riferimento indirettamente tramite C<<
$self->shiftline() >> e C<< $self- >unshiftline($$) >>.

=back

=head2 LAVORARE CON LE OPZIONI DEL MODULO

=over 4

=item treat_options()

Questa funzione riempie le strutture interne che contengono i tag, gli
attributi e i dati in linea con le opzioni del modulo (specificate nella
riga di comando o nella funzione di inizializzazione).

=back

=head2 RICAVARE IL TESTO DAL DOCUMENTO IN INGRESSO

=over

=item get_string_until($%)

Questa funzione restituisce un array con le righe (e i riferimenti) dal
documento di ingresso finché non trova il primo argomento. Il secondo
argomento è un hash di opzioni. Il valore 0 significa disabilitata (valore
predefinito) e 1, abilitata.

Le opzioni valide sono:

=over 4

=item B<include>

Questo fa in modo che l'array restituito contenga il testo cercato

=item B<remove>

Questo rimuove il flusso restituito dall'ingresso

=item B<unquoted>

Questo si assicura che il testo cercato sia fuori da ogni virgolettatura

=item B<regex>

Indica che il primo argomento è un'espressione regolare piuttosto che una
semplice stringa

=back

=item skip_spaces(\@)

Questa funzione riceve come argomento il riferimento a un paragrafo (nel
formato restituito da get_string_until), salta i suoi spazi di intestazione
e li restituisce come stringa semplice.

=item join_lines(@)

Questa funzione restituisce una stringa semplice con il testo dall'array di
argomenti (senza i riferimenti).

=back

=head1 STATO DI QUESTO MODULO

Questo modulo può tradurre tag e attributi.

=head1 ELENCO DEI DAFARE

TIPO DI DOCUMENTO (ENTITÀ)

C'è un supporto minimo per la traduzione di entità. Vengono tradotte in un
blocco e i tag non vengono presi in considerazione. Le entità multilinea non
sono supportate; le entità vengono sempre riformattate durante la
traduzione.

MODIFICA I TIPI DI TAG DAI MODULI EREDITATI (sposta la struttura tag_types
all'interno dell'hash $self?)

=head1 VEDERE ANCHE

L<Locale::Po4a::TransTractor(3pm)|Locale::Po4a::TransTractor>,
L<po4a(7)|po4a.7>

=head1 AUTORI

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


=head1 TRADUZIONE

 Danilo Piazzalunga <danilopiazza@libero.it>
 Marco Ciampa <ciampix@posteo.net>

=head1 COPYRIGHT E LICENZA

 Copyright © 2004 Jordi Vilalta  <jvprat@gmail.com>
 Copyright © 2008-2009 Nicolas François <nicolas.francois@centraliens.net>

Questo programma è software libero; è lecito ridistribuirlo o modificarlo
secondo i termini della licenza GPL v2.0 o successive (vedere il file
COPYING).
