Guida alla traduzione - Sweet Home 3D

Introduzione

Parli una lingua straniera non ancora supportata in Sweet Home 3D e vorresti contribuire alla sua traduzione in quella lingua? Dalla versione 2.3, Sweet Home 3D supporta i file SH3L e questa guida ti insegnerà come creare un file di questo tipo da solo. Un file SH3L è un file di lingua auto-installabile e gli utenti devono solo fare doppio clic su un file SH3L per tradurre Sweet Home 3D nella lingua descritta da quel file.

Istruzioni di base

La creazione di un file SH3L consiste in:

scaricare una versione inglese dei file da tradurre,
decomprimere il file scaricato,
aggiungere un suffisso di 2 lettere corrispondente alla tua lingua ai file .properties che contiene,
tradurre il testo nei file .properties,
convertirli in codifica ASCII,
tradurre il testo della guida nei file .html (non obbligatorio, ma sarà davvero utile per gli utenti),
zippare nuovamente i file .properties e i file della guida in un file con estensione SH3L,
fare doppio clic sul file SH3L per testare la traduzione in Sweet Home 3D,
distribuire il file SH3L.

Istruzioni dettagliate

Se non hai paura delle istruzioni di base precedenti, vai avanti con i passaggi successivi.

Ottenere la versione inglese

Scarica l’archivio all’indirizzo /SweetHome3DTranslation.zip (versione 7.5) e decomprimilo con gli strumenti del tuo sistema.
SweetHome3DTranslation.zip contiene una serie di file con estensioni .properties e .html posizionati in sottocartelle come mostrato nella figura 1.

Tutti i file .properties e .html contengono la versione inglese dei testi che dovrai tradurre nella tua lingua:

i file package.properties descrivono etichette, menu e voci di menu visualizzati nell’interfaccia utente di Sweet Home 3D,
i file basic.properties e metal.properties descrivono le etichette standard delle finestre di dialogo,
quelli che terminano con Catalog.properties descrivono i nomi dei mobili e delle texture disponibili nel software,
i file .html contengono il testo della guida di Sweet Home 3D.

Rinominare i file a seconda della lingua

Prima di tradurre i file .properties, dovresti rinominare ciascuno di essi aggiungendo al loro nome un trattino basso seguito dal codice ISO a 2 caratteri corrispondente alla tua lingua. Troverai questo codice nell’ultima colonna del documento https://www.loc.gov/standards/iso639-2/php/English_list.php.
Quindi, se vuoi tradurre i file della guida, dovresti rinominare anche la sottodirectory en di help con quel codice a 2 lettere.
Ad esempio, il codice ISO per il ceco è cs. Se vuoi tradurre Sweet Home 3D in ceco, ogni nome di file dovrebbe avere il suffisso _cs e dovresti rinominare i file come mostrato nella figura 2.

Figura 2. File Properties con il loro suffisso di codice ISO

Traduzione dei file properties

I file .properties sono file di testo semplice e puoi modificarli con qualsiasi editor di testo come Wordpad, TextEdit o emacs. Ad esempio, il file com/eteks/sweethome3d/package.properties in Sweet Home 3D 3.0 contiene il seguente testo:

# package.properties 10 ott. 2007
# 
# Copyright (c) 2024 Space Mushrooms <[email protected]>. Tutti i diritti riservati.
# 
# Questo programma è software libero; puoi ridistribuirlo e/o modificarlo secondo
# i termini della GNU General Public License pubblicata dalla Free Software
# Foundation; sia la versione 2 della licenza, sia (a tua scelta) qualsiasi versione successiva
# versione.
# 
# Questo programma è distribuito nella speranza che sia utile, ma SENZA
# ALCUNA GARANZIA; senza nemmeno la garanzia implicita di COMMERCIABILITÀ o IDONEITÀ
# PER UN PARTICOLARE SCOPO.  Vedi la GNU General Public License per maggiori
# dettagli.
# 
# Avresti dovuto ricevere una copia della GNU General Public License insieme a
# questo programma; in caso contrario, scrivi a Free Software Foundation, Inc., 59 Temple
# Place, Suite 330, Boston, MA 02111-1307 USA

# Risorse per la classe HomeFramePane
HomeFramePane.untitled=Senza titolo


# Risorse per la classe MacOSXConfiguration
MacOSXConfiguration.WINDOW_MENU.Name=Finestra
MacOSXConfiguration.MINIMIZE.Name=Riduci a icona
MacOSXConfiguration.ZOOM.Name=Zoom
MacOSXConfiguration.BRING_ALL_TO_FRONT.Name=Porta tutto in primo piano


# Risorse per la classe SweetHome3D
SweetHome3D.3DError.message=<html> Sweet Home 3D si chiuderà ora a causa di un errore irreversibile
    <br>nel sistema di rendering 3D. Aggiorna i driver DirectX/OpenGL
    <br>della tua scheda grafica. 
SweetHome3D.3DError.title=Errore 3D
    
SweetHome3D.confirmSaveAfter3DError.message=<html> Sweet Home 3D deve chiudersi ora a causa di un errore irreversibile in
    <br>sistema di rendering 3D. Vuoi salvare tutte le case modificate? 
SweetHome3D.confirmSaveAfter3DError.title=Errore 3D
SweetHome3D.confirmSaveAfter3DError.save=Salva
SweetHome3D.confirmSaveAfter3DError.doNotSave=Non salvare

Un file .properties contiene tre tipi di righe:

le righe che iniziano con un carattere # sono commenti (mostrati in verde nell’esempio precedente). Alcuni commenti contengono informazioni legali, altri forniscono informazioni a sviluppatori o traduttori. Mantieni queste righe invariate.
le righe vuote vengono utilizzate solo per separare le varie parti di un file .properties.
le altre righe iniziano con del testo utilizzato da Sweet Home 3D come chiave per trovare un testo visualizzato sullo schermo (mostrato in blu nell’esempio precedente). Dopo questa chiave, ciascuna di queste righe contiene un segno di uguale (=) e un testo in una determinata lingua. Il tuo lavoro inizia dai segni di uguale. Non modificare il testo della chiave e sostituisci il testo inglese dopo il segno di uguale con la sua traduzione.

Casi speciali:

I testi che iniziano con un tag <html> contengono del testo in formato HTML. Questi testi contengono altri tag HTML tra < e > segni, come <br> nell’esempio precedente che rappresenta un ritorno a capo nel mezzo di testi lunghi. Non rimuovere questi tag HTML, aiutano Sweet Home 3D a presentare correttamente alcuni testi. Tradurre il testo tra tag HTML non è molto difficile, tranne forse per il testo HTML peggiore che è il valore della chiave WallPanel.wallOrientationLabel.text .
Per evitare righe lunghe nell’editor di testo, alcune righe sono divise in due o più righe e quindi separate da barre rovesciate \, come la riga che inizia con SweetHome3D.3DError.message nell’esempio precedente. In tal caso, non rimuovere il segno \ situato alla fine di una riga perché indica che la riga successiva segue la riga corrente.
Alcuni testi contengono sequenze di caratteri speciali che iniziano con un segno % , come %s, %d, %1$s, %2$s… Queste sequenze di caratteri verranno sostituite da un nome file, un’unità o un numero quando necessario, quindi non rimuoverle.
Ad esempio, la sequenza di caratteri %s nel testo della seguente chiave HomeFurniturePanel.widthLabel.text:
```
HomeFurniturePanel.widthLabel.text=Larghezza (%s):
```
verrà sostituito dall’unità attualmente in uso. Le due sequenze di caratteri %1$d e %2$d che appaiono nel testo della seguente chiave PrintPreviewPanel.pageLabel.text:
```
PrintPreviewPanel.pageLabel.text=Pagina  %1$d/%2$d
```
appariranno sullo schermo come un numero di pagina e il conteggio delle pagine, e dovresti tradurre solo la parola Page.
Alcuni testi contengono anche la sequenza di caratteri speciali \n, come nel seguente esempio:
```
HomeController.saveError=Impossibile salvare la casa in\n"%s"
```
Questa sequenza di caratteri viene visualizzata da Sweet Home 3D come un ritorno a capo per dividere una riga sullo schermo e non dovresti rimuoverla.
Il valore della chiave HelpController.helpIndex indica la directory in cui è possibile trovare i file della guida. Se traduci i file della guida .html, dovresti sostituire la sottodirectory en trovata con il codice a 2 lettere della tua lingua.
Ad esempio, se traduci la guida in ceco, dovrebbe diventare:
```
HelpController.helpIndex=/com/eteks/sweethome3d/viewcontroller/resources/help/cs/index.html
```

Il testo delle chiavi che terminano con .mnemonic viene utilizzato da Sweet Home 3D per indovinare quale lettera in un’etichetta o in una voce di menu deve essere sottolineata per l’accesso da tastiera. Questa lettera mnemonica dipende dalla parola visualizzata e dovresti trovarne una univoca per ogni finestra di dialogo o menu.
Ad esempio, i seguenti testi e mnemonici visualizzati nella finestra di dialogo di modifica dei mobili:

HomeFurniturePanel.nameLabel.text=Nome:
HomeFurniturePanel.nameLabel.mnemonic=N
HomeFurniturePanel.nameVisibleCheckBox.text=Visualizza nome nel piano
HomeFurniturePanel.nameVisibleCheckBox.mnemonic=S
HomeFurniturePanel.widthLabel.text=Larghezza (%s):
HomeFurniturePanel.widthLabel.mnemonic=W

può essere tradotto in francese da:

HomeFurniturePanel.nameLabel.text=Nom :
HomeFurniturePanel.nameLabel.mnemonic=N
HomeFurniturePanel.nameVisibleCheckBox.text=Afficher le nom dans le plan
HomeFurniturePanel.nameVisibleCheckBox.mnemonic=S
HomeFurniturePanel.widthLabel.text=Largeur (%s) :
HomeFurniturePanel.widthLabel.mnemonic=L

Usa Sweet Home 3D o la pagina di importazione dei modelli 3D per aiutarti a tradurre i file .properties che terminano con Catalog.properties.

Conversione dei file properties in codifica ASCII

Se hai tradotto testi in una lingua con lettere non appartenenti alla codifica ISO-8859-1 (principalmente lingue dell’Europa centrale e orientale e lingue con un alfabeto non latino), dovrai convertire tutti i tuoi file .properties in una codifica ASCII supportata da Sweet Home 3D. Questa conversione può essere eseguita con lo strumento native2ascii fornito con il JDK o può essere eseguita con il seguente modulo.
Per ogni file .properties, crea un backup di quel file, copia/incolla il testo da convertire nella seguente area di testo, fai clic sul pulsante Converti e copia/incolla il testo convertito nel suo file .properties.

Lo strumento di conversione sostituirà ogni carattere non ASCII (lettere latine accentate e lettere non latine) con una sequenza che inizia con \u e seguita da un codice a 4 cifre esadecimali corrispondente a quel carattere in Unicode. Purtroppo, questa conversione renderà il tuo testo piuttosto illeggibile per un essere umano, ma se non la esegui, Sweet Home 3D non sarà in grado di visualizzare correttamente i caratteri della tua traduzione. Questo è il motivo per cui dovresti creare un backup dei tuoi file .properties originali, nel caso in cui volessi modificarli in seguito.
Se vuoi modificare direttamente i file .properties convertiti in ASCII, puoi anche utilizzare l’applicazione Properties Editor disponibile come file eseguibile Jar qui.

Traduzione dei file della guida

Una buona traduzione di Sweet Home 3D dovrebbe includere anche la traduzione dei suoi file della guida. Tradurre tutti i file .html è un compito lungo, ma aiuterà davvero gli utenti a imparare il software ed evitare alcune richieste di supporto nel forum di Sweet Home 3D. Usa qualsiasi editor HTML per tradurre questi file, cercando di mantenere invariati i collegamenti che contiene e il suo foglio di stile.
Una volta tradotto, dovresti anche creare schermate delle finestre di dialogo nella tua lingua per sostituire le immagini trovate in com/eteks/sweethome3d/viewcontroller/resources/help/en/images. Per essere in grado di creare tali schermate, crea e testa un primo file SH3L con i seguenti passaggi (una volta che esiste un file SH3L contenente file .properties tradotti, puoi anche richiedere allo sviluppatore di Sweet Home 3D di generare le schermate).

Creazione del file SH3L

Una volta che tutti i file .properties e .html sono tradotti e convertiti in ASCII se necessario (o anche prima se vuoi testare questa procedura), dovresti zipparli in un file. A seconda del tuo sistema, la creazione di un file zip può essere eseguita con la seguente procedura:

in Windows, seleziona la cartella com contenente tutti i file tradotti e scegli Invia a > Cartella compressa dal suo menu contestuale,
in Mac OS X, seleziona la cartella com contenente tutti i file tradotti e scegli la voce di menu File > Comprimi « com »,
in Linux, seleziona la cartella com contenente tutti i file tradotti, scegli Crea archivio… dal suo menu contestuale, quindi seleziona .zip nell’elenco dei formati.

Infine, cambia l’estensione .zip del file zip in .sh3l. Un file SH3L può avere qualsiasi nome, ma per evitare conflitti con i file SH3L esistenti, dovresti nominarlo dalla lingua che contiene e dalla versione di Sweet Home 3D che hai tradotto (ad esempio, French-4.1.sh3l potrebbe essere un buon nome per la traduzione francese di Sweet Home 3D 4.1).

Testare un file SH3L

Per testare la traduzione, fai doppio clic su un file SH3L o sceglilo con il pulsante Importa file libreria lingua visualizzato nella parte superiore del pannello Preferenze. Questo avvierà Sweet Home 3D e tradurrà la sua interfaccia utente nella lingua descritta nel file SH3L. Questo copierà anche il file SH3L in una cartella a seconda del tuo sistema:

in Windows Vista / 7 / 8 / 10 / 11, questa cartella è C:\Users\utente\AppData\Roaming\eTeks\Sweet Home 3D\languages,
in Windows XP e versioni precedenti di Windows, questa cartella è C:\Documents and Settings\utente\Application Data\eTeks\Sweet Home 3D\languages,
in macOS, è la sottocartella Library/Application Support/eTeks/Sweet Home 3D/languages della tua cartella utente,
in Linux e altri Unix, è la sottocartella .eteks/sweethome3d/languages della tua cartella utente,
con la versione portatile di Sweet Home 3D, è la sottocartella data/languages della cartella in cui è memorizzata l’applicazione Sweet Home 3D,

Si noti inoltre che durante lo sviluppo del file SH3L, probabilmente sarà necessario riavviare Sweet Home 3D per visualizzare le modifiche nel file SH3L.

Distribuzione di file SH3L

Una volta che il file SH3L è pronto, è possibile proporlo a chiunque, annunciarlo agli utenti di Sweet Home 3D nella parte del forum riservata alle lingue straniere o in altri luoghi. Se sei d’accordo, può essere reso disponibile su questo sito web nella pagina relativa alle traduzioni supportate da Sweet Home 3D.

Aggiornamento dei file SH3L

Alcune versioni di Sweet Home 3D apportano nuove funzionalità da tradurre, altre no. Se non traduci le etichette dell’interfaccia utente corrispondenti a queste nuove funzionalità, Sweet Home 3D funzionerà, ma tutte le nuove etichette verranno visualizzate in inglese. Per trovare le nuove chiavi e le chiavi aggiornate nei file .properties, è possibile utilizzare una funzione offerta da SourceForge.net che consente di confrontare due versioni di un file di progetto:

Cerca le date delle versioni di Sweet Home 3D che vuoi confrontare nella cronologia (ad esempio, 19 luglio 2015 per la versione 5.0 e 2 febbraio 2015 per la versione 4.6)
Fare clic sul file .properties o .html che si desidera aggiornare nella figura 1,
Seleziona le due caselle di controllo del numero di revisione corrispondente alla data della versione per il file aggiornato, scegliendo la data immediatamente precedente a una data di versione di Sweet Home 3D,
Fare clic sul pulsante Confronta.

L’ultimo clic mostrerà le differenze tra le due versioni di quel file .properties (ad esempio, questo link mostrerà le differenze tra la versione 4.6 e la versione 5.0 del file com/eteks/sweethome3d/viewcontroller/package.properties).

Una volta trovate le differenze, aggiorna la tua traduzione, aggiungendo nuovi nomi di chiave se necessario, e rilascia una nuova versione della tua traduzione.