Guida alla traduzione

Introduzione
Istruzioni di base
Istruzioni dettagliate

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 tale file 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:

downloading an English version of the files to translate,
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à molto utile per gli utenti),
comprimere i file .properties e i file della guida in un file con estensione SH3L,
fare doppio clic sul file SH3L per testare la tua traduzione in Sweet Home 3D,
distribuire il tuo file SH3L.

Istruzioni dettagliate

Se le precedenti istruzioni di base non ti spaventano, prosegui con i passaggi successivi.

Ottenere la versione inglese

Download the archive at https://www.sweethome3d.com/SweetHome3DTranslation.zip (version 7.5) and unzip it with the tools of your system.
SweetHome3DTranslation.zip contains a set of files with .properties and .html extensions placed in subfolders as shown in figure 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 mostrati 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.

I file .properties devono essere posizionati nelle cartelle mostrate nella figura 1, altrimenti Sweet Home 3D non sarà in grado di usarli correttamente. Quindi non spostare i file dalle loro cartelle, non rinominare alcuna cartella (eccetto la sottodirectory en di help) e non eliminare alcuna cartella.

Rinominare i file in base alla tua lingua

Prima di tradurre i file .properties, dovresti rinominare ciascuno di essi aggiungendo al loro nome un underscore seguito dal codice ISO di 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.
Poi, se vuoi tradurre i file della guida, dovresti rinominare anche la sottodirectory di con quel codice di 2 lettere.
Ad esempio, il codice ISO per il ceco è . Se vuoi tradurre Sweet Home 3D in ceco, ogni nome di file dovrebbe essere suffissato da _cs, e dovresti rinominare i file come mostrato nella figura 2.

Guida alla traduzione — *Figura 2. File di proprietà con il loro suffisso del codice ISO*

Traduzione dei file di proprietà

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 oct. 2007
# 
# Copyright (c) 2024 Space Mushrooms <[email protected]>. All Rights Reserved.
# 
# This program is free software; you can redistribute it and/or modify it under
# the terms of the GNU General Public License as published by the Free Software
# Foundation; either version 2 of the License, or (at your option) any later
# version.
# 
# This program is distributed in the hope that it will be useful, but WITHOUT
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
# FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
# details.
# 
# You should have received a copy of the GNU General Public License along with
# this program; if not, write to the 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 verrà chiuso a causa di un errore fatale
    <br>nel sistema di rendering 3D. Aggiorna i driver DirectX/OpenGL
    <br>della scheda grafica del tuo computer. 
SweetHome3D.3DError.title=Errore 3D
    
SweetHome3D.confirmSaveAfter3DError.message=<html> Sweet Home 3D deve essere chiuso a causa di un errore fatale nel
    <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 agli sviluppatori o ai traduttori. Mantieni queste righe invariate.
le righe vuote sono usate solo per separare le varie parti di un file .properties.
le altre righe iniziano con un testo usato 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 data 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 <html> tag 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 i 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 poi separate da barre rovesciate \, come la riga che inizia con SweetHome3D.3DError.message nell’esempio precedente. In quel 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 di 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à sostituita 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 numero di pagina e conteggio delle pagine, e tu 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
"%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 rimuoverli.
Il valore della chiave HelpController.helpIndex indica la directory dove si trovano i file della guida. Se traduci i file della guida .html, dovresti sostituire la sottodirectory en trovata con il codice di 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 termina con .mnemonic viene utilizzato da Sweet Home 3D per indovinare quale lettera in un’etichetta o una voce di menu dovrebbe essere sottolineata per l’accesso da tastiera. Questa lettera mnemonica dipende dalla parola visualizzata e dovresti trovarne una unica per ogni finestra di dialogo o menu.
Ad esempio, i seguenti testi e mnemoniche visualizzati nella finestra di dialogo di modifica dei mobili:

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

può essere tradotto in francese con:

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

Use Sweet Home 3D or 3d models import page to help you translate the .properties files ending by Catalog.properties.

Conversione dei file di proprietà 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 nell’area di testo seguente, clicca 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 di 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 volessi modificarli in seguito.
Se vuoi modificare direttamente i file .properties convertiti in ASCII, puoi anche usare 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 eviterà alcune richieste di supporto nel forum di Sweet Home 3D. Usa qualsiasi editor HTML per tradurre questi file, cercando di mantenere i collegamenti che contiene e il suo foglio di stile invariati.
Una volta tradotto, dovresti anche creare delle catture di schermo delle finestre di dialogo nella tua lingua per sostituire le immagini trovate in com/eteks/sweethome3d/viewcontroller/resources/help/en/images. Per poter creare tali catture di schermo, 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 catture di schermo).

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 comprimerli in un file. A seconda del tuo sistema, la creazione di un file zip può essere fatta con la seguente procedura:

sotto Windows, seleziona la cartella com contenente tutti i file tradotti e scegli Invia a > Cartella compressa dal suo menu contestuale,
sotto Mac OS X, seleziona la cartella com contenente tutti i file tradotti e scegli la voce di menu File > Comprimi « com »,
sotto Linux, seleziona la cartella com contenente tutti i file tradotti, scegli Crea archivio… dal suo menu contestuale e poi 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 in base alla lingua che contiene e alla 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:

sotto Windows Vista / 7 / 8 / 10 / 11, questa cartella è C:\Users\utente\AppData\Roaming\eTeks\Sweet Home 3D\languages,
sotto Windows XP e versioni precedenti di Windows, questa cartella è C:\Documents and Settings\utente\Application Data\eTeks\Sweet Home 3D\languages,
sotto macOS, è la sottocartella Library/Application Support/eTeks/Sweet Home 3D/languages della tua cartella utente,
sotto 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,

Tieni presente inoltre che, durante lo sviluppo del tuo file SH3L, probabilmente dovrai riavviare Sweet Home 3D per vedere le modifiche nel tuo file SH3L.

Distribuzione di file SH3L

Once your SH3L file is ready, you can propose it to anyone, announce it to Sweet Home 3D users in the forum part reserved to foreign languages or in other places. If you agree, it can be made available on this web site in the page about translations supported by Sweet Home 3D.

Aggiornamento dei file SH3L

Alcune versioni di Sweet Home 3D portano 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 appariranno in inglese. Per trovare le nuove chiavi e le chiavi aggiornate nei file .properties, puoi utilizzare una funzionalità offerta da SourceForge.net che ti consente di confrontare due versioni di un file di progetto:

Search the dates of Sweet Home 3D versions you want to compare in history (for example, July 19, 2015 for version 5.0 and February 2, 2015 for version 4.6)
Clicca sul file .properties o .html che vuoi 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,
Clicca sul pulsante Confronta.

L’ultimo clic ti mostrerà le differenze tra le due versioni di quel file .properties (ad esempio, questo link ti 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.