Guide de traduction Sweet Home 3D

Introduction

Vous parlez une langue étrangère qui n’est pas encore prise en charge par Sweet Home 3D et vous aimeriez contribuer à sa traduction dans cette langue ? À partir de la version 2.3, Sweet Home 3D prend en charge les fichiers SH3L et ce guide vous apprendra comment créer vous-même un tel fichier. Un fichier SH3L est un fichier de langue auto-installable et les utilisateurs n’ont qu’à double-cliquer sur un fichier SH3L pour traduire Sweet Home 3D dans la langue décrite par ce fichier.

Instructions de base

La création d’un fichier SH3L consiste à :

télécharger une version anglaise des fichiers à traduire,
décompresser le fichier téléchargé,
ajouter un suffixe de 2 lettres correspondant à votre langue aux fichiers .properties qu’il contient,
traduire le texte dans les fichiers .properties,
les convertir en codage ASCII,
traduire le texte d’aide dans les fichiers .html (non obligatoire, mais très utile pour les utilisateurs),
recompresser les fichiers .properties et les fichiers d’aide dans un fichier avec une extension SH3L,
double-cliquer sur le fichier SH3L pour tester votre traduction dans Sweet Home 3D,
distribuer votre fichier SH3L.

Instructions détaillées

Si les instructions de base précédentes ne vous font pas peur, passez aux étapes suivantes.

Obtenir la version anglaise

Téléchargez l’archive à l’adresse /SweetHome3DTranslation.zip (version 7.5) et décompressez-la avec les outils de votre système.
SweetHome3DTranslation.zip contient un ensemble de fichiers avec les extensions .properties et .html placés dans des sous-dossiers comme indiqué dans la figure 1.

Tous les fichiers .properties et .html contiennent la version anglaise des textes que vous devrez traduire dans votre langue :

les fichiers package.properties décrivent les étiquettes, les menus et les éléments de menu affichés dans l’interface utilisateur de Sweet Home 3D,
les fichiers basic.properties et metal.properties décrivent les étiquettes de dialogue standard,
ceux qui se terminent par Catalog.properties décrivent les noms des meubles et des textures disponibles dans le logiciel,
les fichiers .html contiennent le texte de l’aide de Sweet Home 3D.

Renommer les fichiers en fonction de votre langue

Avant de traduire les fichiers .properties, vous devez renommer chacun d’eux en ajoutant à leur nom un trait de soulignement suivi du code ISO à 2 caractères correspondant à votre langue. Vous trouverez ce code dans la dernière colonne du document https://www.loc.gov/standards/iso639-2/php/English_list.php.
Ensuite, si vous voulez traduire les fichiers d’aide, vous devez également renommer le sous-répertoire de avec ce code à 2 lettres.
Par exemple, le code ISO pour le tchèque est . Si vous voulez traduire Sweet Home 3D en tchèque, chaque nom de fichier doit être suffixé par _cs, et vous devez renommer les fichiers comme indiqué dans la figure 2.

Figure 2. Fichiers de propriétés avec leur suffixe de code ISO

Traduction des fichiers de propriétés

Les fichiers .properties sont des fichiers de texte brut et vous pouvez les modifier avec n’importe quel éditeur de texte comme Wordpad, TextEdit ou emacs. Par exemple, le fichier com/eteks/sweethome3d/package.properties dans Sweet Home 3D 3.0 contient le texte suivant :

# 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

# Resources for HomeFramePane class
HomeFramePane.untitled=Sans titre


# Resources for MacOSXConfiguration class
MacOSXConfiguration.WINDOW_MENU.Name=Fenêtre
MacOSXConfiguration.MINIMIZE.Name=Réduire
MacOSXConfiguration.ZOOM.Name=Zoom
MacOSXConfiguration.BRING_ALL_TO_FRONT.Name=Tout ramener au premier plan


# Resources for SweetHome3D class
SweetHome3D.3DError.message=<html> Sweet Home 3D va maintenant se fermer en raison d'une erreur fatale
    <br>dans le système de rendu 3D. Veuillez mettre à jour les pilotes DirectX/OpenGL
    <br>de votre carte graphique. 
SweetHome3D.3DError.title=Erreur 3D
    
SweetHome3D.confirmSaveAfter3DError.message=<html> Sweet Home 3D doit maintenant se fermer en raison d'une erreur fatale dans
    <br>le système de rendu 3D. Voulez-vous enregistrer toutes les maisons modifiées ? 
SweetHome3D.confirmSaveAfter3DError.title=Erreur 3D
SweetHome3D.confirmSaveAfter3DError.save=Enregistrer
SweetHome3D.confirmSaveAfter3DError.doNotSave=Ne pas enregistrer

Un fichier .properties contient trois types de lignes :

les lignes qui commencent par un caractère # sont des commentaires (affichés en vert dans l’exemple précédent). Certains commentaires contiennent des informations légales, d’autres donnent des informations aux développeurs ou aux traducteurs. Gardez ces lignes inchangées.
les lignes vides sont juste utilisées pour séparer les différentes parties d’un fichier .properties.
les autres lignes commencent par un texte utilisé par Sweet Home 3D comme clé pour trouver un texte affiché à l’écran (affiché en bleu dans l’exemple précédent). Après cette clé, chacune de ces lignes contient un signe égal (=) et un texte dans une langue donnée. Votre travail commence à partir des signes égaux. Ne modifiez pas le texte de la clé et remplacez le texte anglais après le signe égal par sa traduction.

Cas particuliers :

Les textes commençant par une balise « <html> » contiennent du texte au format HTML. Ces textes contiennent d’autres balises HTML entre les signes « < » et « > », comme « <br> » dans l’exemple précédent, qui représente un retour chariot au milieu de longs textes. Ne supprimez pas ces balises HTML, elles aident Sweet Home 3D à présenter correctement certains textes. Traduire du texte entre des balises HTML n’est pas très difficile, sauf peut-être pour le pire texte HTML qui est la valeur de la clé WallPanel.wallOrientationLabel.text .
Pour éviter les longues lignes dans l’éditeur de texte, certaines lignes sont divisées en deux ou plusieurs lignes et ensuite séparées par des barres obliques inverses « \», comme la ligne commençant par « SweetHome3D.3DError.message » dans l’exemple précédent. Dans ce cas, ne supprimez pas le signe « \ » situé à la fin d’une ligne, car il indique que la ligne suivante suit la ligne actuelle.
Certains textes contiennent une séquence de caractères spéciaux commençant par un signe % , comme %s, %d, %1$s, %2$s… Ces séquences de caractères seront remplacées par un nom de fichier, une unité ou un nombre si nécessaire, alors ne les supprimez pas.
Par exemple, la séquence de caractères « %s » dans le texte de la clé suivante « HomeFurniturePanel.widthLabel.text:
```
HomeFurniturePanel.widthLabel.text=Largeur (%s):
```
» sera remplacée par l’unité actuellement utilisée. Les deux séquences de caractères « %1$d » et « %2$d » qui apparaissent dans le texte de la clé suivante « PrintPreviewPanel.pageLabel.text:
```
PrintPreviewPanel.pageLabel.text=Page  %1$d/%2$d
```
» apparaîtront à l’écran comme un numéro de page et le nombre de pages, et vous ne devriez traduire que le mot Page.
Certains textes contiennent également la séquence de caractères spéciaux « \n», comme dans l’exemple suivant : «
```
HomeController.saveError=Impossible d'enregistrer la maison dans\n"%s"
```
». Cette séquence de caractères est affichée par Sweet Home 3D comme un retour chariot pour diviser une ligne à l’écran, et vous ne devriez pas les supprimer.
La valeur de la clé HelpController.helpIndex indique le répertoire où les fichiers d’aide peuvent être trouvés. Si vous traduisez les fichiers d’aide .html, vous devriez remplacer le sous-répertoire en trouvé par le code à 2 lettres de votre langue.
Par exemple, si vous traduisez l’aide en tchèque, cela devrait devenir :
```
HelpController.helpIndex=/com/eteks/sweethome3d/viewcontroller/resources/help/cs/index.html
```

Le texte des clés qui se terminent par .mnemonic est utilisé par Sweet Home 3D pour deviner quelle lettre dans une étiquette ou un élément de menu doit être soulignée pour l’accès au clavier. Cette lettre mnémonique dépend du mot affiché et vous devriez en trouver une unique par boîte de dialogue ou menu.
Par exemple, les textes et les mnémoniques suivants affichés dans la boîte de dialogue de modification des meubles :

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=W

peut être traduit en français par :

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

Utilisez Sweet Home 3D ou la page d’importation de modèles 3D pour vous aider à traduire les fichiers .properties se terminant par Catalog.properties.

Conversion des fichiers de propriétés en codage ASCII

Si vous avez traduit des textes dans une langue dont les lettres n’appartiennent pas au codage ISO-8859-1 (principalement les langues d’Europe centrale et orientale et les langues avec un alphabet non latin), vous devrez convertir tous vos fichiers .properties en un codage ASCII pris en charge par Sweet Home 3D. Cette conversion peut être effectuée avec l’outil native2ascii fourni avec le JDK ou peut être effectuée avec le formulaire suivant.
Pour chaque fichier .properties, créez une sauvegarde de ce fichier, copiez/collez le texte à convertir dans la zone de texte suivante, cliquez sur le bouton Convertir et copiez/collez le texte converti dans son fichier .properties.

L’outil de conversion remplacera chaque caractère non ASCII (lettres latines accentuées et lettres non latines) par une séquence commençant par \u et suivie d’un code de 4 chiffres hexadécimaux correspondant à ce caractère en Unicode. Malheureusement, cette conversion rendra votre texte assez illisible pour un humain, mais si vous ne l’effectuez pas, Sweet Home 3D ne pourra pas afficher correctement les caractères de votre traduction. C’est la raison pour laquelle vous devriez créer une sauvegarde de vos fichiers .properties originaux, au cas où vous voudriez les modifier plus tard.
Si vous voulez modifier directement les fichiers .properties convertis en ASCII, vous pouvez également utiliser l’application Properties Editor disponible sous forme de fichier exécutable Jar ici.

Traduction des fichiers d’aide

Une bonne traduction de Sweet Home 3D devrait également inclure la traduction de ses fichiers d’aide. Traduire tous les fichiers .html est une tâche longue, mais cela aidera vraiment les utilisateurs à apprendre le logiciel et à éviter certaines demandes de support dans le forum Sweet Home 3D. Utilisez n’importe quel éditeur HTML pour traduire ces fichiers, en essayant de garder les liens qu’il contient et sa feuille de style inchangés.
Une fois traduits, vous devriez également créer des captures d’écran des boîtes de dialogue dans votre langue pour remplacer les images trouvées dans com/eteks/sweethome3d/viewcontroller/resources/help/en/images. Pour pouvoir créer de telles captures d’écran, créez et testez un premier fichier SH3L avec les étapes suivantes (une fois qu’un fichier SH3L contenant des fichiers .properties traduits existe, vous pouvez également demander au développeur de Sweet Home 3D de générer les captures d’écran).

Création du fichier SH3L

Une fois que tous les fichiers .properties et .html sont traduits et convertis en ASCII si nécessaire (ou même avant si vous voulez tester cette procédure), vous devriez les compresser dans un fichier. Selon votre système, la création d’un fichier zip peut être effectuée avec la procédure suivante :

sous Windows, sélectionnez le dossier com contenant tous les fichiers traduits et choisissez Envoyer vers > Dossier compressé dans son menu contextuel,
sous Mac OS X, sélectionnez le dossier com contenant tous les fichiers traduits et choisissez l’élément de menu Fichier > Compresser « com »,
sous Linux, sélectionnez le dossier com contenant tous les fichiers traduits, choisissez Créer une archive… dans son menu contextuel, puis sélectionnez .zip dans la liste des formats.

Enfin, remplacez l’extension .zip du fichier zip par .sh3l. Un fichier SH3L peut avoir n’importe quel nom, mais pour éviter les conflits avec les fichiers SH3L existants, vous devriez le nommer à partir de la langue qu’il contient et de la version de Sweet Home 3D que vous avez traduite (par exemple, French-4.1.sh3l pourrait être un bon nom pour la traduction française de Sweet Home 3D 4.1).

Test d’un fichier SH3L

Pour tester la traduction, double-cliquez sur un fichier SH3L ou choisissez-le avec le bouton Importer un fichier de bibliothèque de langue affiché en haut du panneau Préférences. Cela lancera Sweet Home 3D et traduira son interface utilisateur dans la langue décrite dans le fichier SH3L. Cela copiera également le fichier SH3L dans un dossier en fonction de votre système :

sous Windows Vista / 7 / 8 / 10 / 11, ce dossier est C:\Users\utilisateur\AppData\Roaming\eTeks\Sweet Home 3D\languages,
sous Windows XP et les versions précédentes de Windows, ce dossier est C:\Documents and Settings\utilisateur\Application Data\eTeks\Sweet Home 3D\languages,
sous macOS, c’est le sous-dossier Library/Application Support/eTeks/Sweet Home 3D/languages de votre dossier utilisateur,
sous Linux et autres Unix, c’est le sous-dossier .eteks/sweethome3d/languages de votre dossier utilisateur,
avec la version portable de Sweet Home 3D, c’est le sous-dossier data/languages du dossier où l’application Sweet Home 3D est stockée,

Note également que pendant le développement de votre fichier SH3L, vous devrez probablement relancer Sweet Home 3D pour voir les modifications apportées à votre fichier SH3L.

Distribution des fichiers SH3L

Une fois votre fichier SH3L prêt, vous pouvez le proposer à qui vous voulez, l’annoncer aux utilisateurs de Sweet Home 3D dans la partie du forum réservée aux langues étrangères ou ailleurs. Si vous êtes d’accord, il pourra être mis à disposition sur ce site web dans la page concernant les traductions prises en charge par Sweet Home 3D.

Mise à jour des fichiers SH3L

Certaines versions de Sweet Home 3D apportent de nouvelles fonctionnalités à traduire, d’autres non. Si vous ne traduisez pas les étiquettes de l’interface utilisateur correspondant à ces nouvelles fonctionnalités, Sweet Home 3D fonctionnera, mais toutes les nouvelles étiquettes apparaîtront en anglais. Pour trouver les nouvelles clés et les clés mises à jour dans les fichiers .properties, vous pouvez utiliser une fonctionnalité offerte par SourceForge.net qui vous permet de comparer deux versions d’un fichier de projet :

Recherchez les dates des versions de Sweet Home 3D que vous souhaitez comparer dans l’historique (par exemple, le 19 juillet 2015 pour la version 5.0 et le 2 février 2015 pour la version 4.6)
Cliquez sur le fichier .properties ou .html que vous souhaitez mettre à jour dans la figure 1,
Cochez les deux cases du numéro de révision correspondant à la date de la version du fichier mis à jour, en choisissant la date qui précède immédiatement une date de version de Sweet Home 3D,
Cliquez sur le bouton Compare.

Le dernier clic vous montrera les différences entre les deux versions de ce fichier .properties (par exemple, ce lien vous montrera les différences entre la version 4.6 et la version 5.0 du fichier com/eteks/sweethome3d/viewcontroller/package.properties).

Une fois que vous avez trouvé les différences, mettez à jour votre traduction, en ajoutant de nouveaux noms de clés si nécessaire, et publiez une nouvelle version de votre traduction.