Vertaalgids

Inleiding
Basisinstructies
Gedetailleerde instructies

Inleiding

Je spreekt een vreemde taal die nog niet wordt ondersteund in Sweet Home 3D en wilt graag bijdragen aan de vertaling naar die taal? Vanaf versie 2.3 ondersteunt Sweet Home 3D SH3L-bestanden en deze gids leert je hoe je zelf zo’n bestand kunt maken. Een SH3L-bestand is een automatisch installeerbaar taalbestand en gebruikers hoeven alleen maar te dubbelklikken op een SH3L-bestand om Sweet Home 3D te vertalen naar de taal die in dat bestand wordt beschreven.

Basisinstructies

Het maken van een SH3L-bestand bestaat uit:

het downloaden van een Engelse versie van de bestanden om te vertalen,
het uitpakken van het gedownloade bestand,
het toevoegen van een 2-letterige achtervoegsel die overeenkomt met je taal aan de .properties bestanden die het bevat,
het vertalen van de tekst in de .properties bestanden,
het converteren naar ASCII-codering,
het vertalen van de helptekst in de .html bestanden (niet verplicht maar wel erg nuttig voor gebruikers),
het terugzetten van de .properties bestanden en de helpbestanden in een bestand met een SH3L-extensie,
dubbelklikken op het SH3L-bestand om je vertaling in Sweet Home 3D te testen,
het verspreiden van je SH3L-bestand.

Gedetailleerde instructies

Als je niet bang bent voor de vorige basisinstructies, ga dan verder met de volgende stappen.

De Engelse versie verkrijgen

Download het archief op https://www.sweethome3d.com/SweetHome3DTranslation.zip (versie 7.5) en pak het uit met de tools van je systeem.
SweetHome3DTranslation.zip bevat een set bestanden met .properties en .html extensies geplaatst in submappen zoals getoond in figuur 1.

Alle .properties en .html bestanden bevatten de Engelse versie van de teksten die je moet vertalen naar je taal:

de package.properties bestanden beschrijven labels, menu’s en menu-items die worden getoond in de gebruikersinterface van Sweet Home 3D,
de basic.properties en metal.properties bestanden beschrijven standaard dialoglabels,
degene die eindigen op Catalog.properties beschrijven de namen van de meubels en texturen die beschikbaar zijn in de software,
de .html bestanden bevatten de tekst van de help van Sweet Home 3D.

De .properties bestanden moeten worden geplaatst in de mappen die getoond worden in figuur 1, anders kan Sweet Home 3D ze niet correct gebruiken. Verplaats de bestanden dus niet uit hun map, hernoem geen enkele map (behalve de en submap van help) en verwijder geen enkele map.

Bestanden hernoemen afhankelijk van je taal

Voordat je de .properties bestanden vertaalt, moet je elk van hen hernoemen door aan hun naam een underscore toe te voegen gevolgd door de 2-karakters ISO-code die overeenkomt met je taal. Je vindt deze code in de laatste kolom van het document https://www.loc.gov/standards/iso639-2/php/English_list.php.
Als je vervolgens de helpbestanden wilt vertalen, moet je ook de en submap van help hernoemen met die 2-lettercode.
Bijvoorbeeld, de ISO-code voor Tsjechisch is cs. Als je Sweet Home 3D naar het Tsjechisch wilt vertalen, moet elke bestandsnaam worden voorzien van het achtervoegsel _cs, en moet je de bestanden hernoemen zoals getoond in figuur 2.

Vertaalgids — *Figuur 2. Properties-bestanden met hun ISO-code achtervoegsel*

Properties-bestanden vertalen

De .properties bestanden zijn platte tekstbestanden en je kunt ze bewerken met elke teksteditor zoals Wordpad, TextEdit of emacs. Bijvoorbeeld, het com/eteks/sweethome3d/package.properties bestand in Sweet Home 3D 3.0 bevat de volgende tekst:

# 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=Untitled


# Resources for MacOSXConfiguration class
MacOSXConfiguration.WINDOW_MENU.Name=Window
MacOSXConfiguration.MINIMIZE.Name=Minimize
MacOSXConfiguration.ZOOM.Name=Zoom
MacOSXConfiguration.BRING_ALL_TO_FRONT.Name=Bring all to front


# Resources for SweetHome3D class
SweetHome3D.3DError.message=<html> Sweet Home 3D will exit now because of a fatal error
    <br>in 3D rendering system. Please update the DirectX/OpenGL drivers
    <br>of your computer graphics card. 
SweetHome3D.3DError.title=3D Error
    
SweetHome3D.confirmSaveAfter3DError.message=<html> Sweet Home 3D must exit now because of a fatal error in
    <br>3D rendering system. Do you want to save all modified homes? 
SweetHome3D.confirmSaveAfter3DError.title=3D Error
SweetHome3D.confirmSaveAfter3DError.save=Save
SweetHome3D.confirmSaveAfter3DError.doNotSave=Do not save

Een .properties bestand bevat drie soorten regels:

de regels die beginnen met een # teken zijn opmerkingen (getoond in groen in het vorige voorbeeld). Sommige opmerkingen bevatten juridische informatie, sommige geven informatie aan ontwikkelaars of vertalers. Laat deze regels ongewijzigd.
lege regels worden alleen gebruikt om de verschillende delen van een .properties bestand te scheiden.
de andere regels beginnen met tekst die door Sweet Home 3D wordt gebruikt als sleutel om tekst te vinden die op het scherm wordt weergegeven (getoond in blauw in het vorige voorbeeld). Na deze sleutel bevat elk van deze regels een gelijkteken (=) en een tekst in een bepaalde taal. Je werk begint vanaf de gelijktekens. Verander de tekst van de sleutel niet en vervang de Engelse tekst na het gelijkteken door de vertaling ervan.

Speciale gevallen:

De teksten die beginnen met een <html> tag bevatten tekst in HTML-formaat. Deze teksten bevatten andere HTML-tags tussen < en > tekens, zoals <br> in het vorige voorbeeld dat een regeleinde voorstelt in het midden van lange teksten. Verwijder deze HTML-tags niet, ze helpen Sweet Home 3D om sommige teksten correct weer te geven. Het vertalen van tekst tussen HTML-tags is niet erg moeilijk, behalve misschien voor de ergste HTML-tekst die de waarde is van WallPanel.wallOrientationLabel.text sleutel.
Om lange regels in de teksteditor te vermijden, worden sommige regels gesplitst in twee of meer regels en vervolgens gescheiden door backslashes \, zoals de regel die begint met SweetHome3D.3DError.message in het vorige voorbeeld. Verwijder in dat geval het \ teken aan het einde van een regel niet omdat het aangeeft dat de volgende regel volgt op de huidige regel.
Sommige teksten bevatten speciale karakterreeksen die beginnen met een % teken, zoals %s, %d, %1$s, %2$s… Deze karakterreeksen worden vervangen door een bestandsnaam, een eenheid of een getal wanneer nodig, dus verwijder ze niet.
Bijvoorbeeld, de karakterreeks %s in de tekst van de volgende sleutel HomeFurniturePanel.widthLabel.text:
```
HomeFurniturePanel.widthLabel.text=Width (%s):
```
wordt vervangen door de eenheid die momenteel in gebruik is. De twee karakterreeksen %1$d en %2$d die verschijnen in de tekst van de volgende sleutel PrintPreviewPanel.pageLabel.text:
```
PrintPreviewPanel.pageLabel.text=Page  %1$d/%2$d
```
verschijnen op het scherm als een paginanummer en het aantal pagina’s, en je moet alleen het woord Page vertalen.
Sommige teksten bevatten ook de speciale karakterreeks \n, zoals in het volgende voorbeeld:
```
HomeController.saveError=Can't save home in
"%s"
```
Deze karakterreeks wordt door Sweet Home 3D weergegeven als een regeleinde om een regel op het scherm te splitsen, en je moet ze niet verwijderen.
De waarde van de sleutel HelpController.helpIndex geeft de map aan waar de helpbestanden kunnen worden gevonden. Als je de .html helpbestanden vertaalt, moet je de en submap vervangen door de 2-lettercode van je taal.
Bijvoorbeeld, als je help naar het Tsjechisch vertaalt, moet het worden:
```
HelpController.helpIndex=/com/eteks/sweethome3d/viewcontroller/resources/help/cs/index.html
```

De tekst van de sleutels die eindigen op .mnemonic worden door Sweet Home 3D gebruikt om te raden welke letter in een label of menu-item onderstreept moet worden voor toetsenbordtoegang. Deze geheugensteunletter hangt af van het weergegeven woord en je moet een unieke vinden per dialoogvenster of menu.
Bijvoorbeeld, de volgende teksten en geheugensteunletters die worden weergegeven in het meubelwijzigingsdialoogvenster:

HomeFurniturePanel.nameLabel.text=Name:
HomeFurniturePanel.nameLabel.mnemonic=N
HomeFurniturePanel.nameVisibleCheckBox.text=Display name in plan
HomeFurniturePanel.nameVisibleCheckBox.mnemonic=S
HomeFurniturePanel.widthLabel.text=Width (%s):
HomeFurniturePanel.widthLabel.mnemonic=W

kunnen in het Frans worden vertaald als:

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

Gebruik Sweet Home 3D of 3d models import page om je te helpen bij het vertalen van de .properties bestanden die eindigen op Catalog.properties.

Properties-bestanden converteren naar ASCII-codering

Als je teksten hebt vertaald naar een taal met letters die niet behoren tot ISO-8859-1 codering (voornamelijk Centraal- en Oost-Europese talen en talen met een niet-Latijns alfabet), moet je al je .properties bestanden converteren naar een ASCII-codering die wordt ondersteund door Sweet Home 3D. Deze conversie kan worden gedaan met de native2ascii tool die wordt geleverd met de JDK of kan worden uitgevoerd met het volgende formulier.
Voor elk .properties bestand, maak een backup van dat bestand, kopieer/plak de te converteren tekst in het volgende tekstgebied, klik op de Convert knop en kopieer/plak de geconverteerde tekst terug in het .properties bestand.

De conversietool vervangt elk niet-ASCII karakter (geaccentueerde Latijnse letters en niet-Latijnse letters) door een reeks die begint met \u en gevolgd wordt door een 4-cijferige hexadecimale code die overeenkomt met dat karakter in Unicode. Helaas maakt deze conversie je tekst vrij onleesbaar voor een mens, maar als je dit niet doet, kan Sweet Home 3D de karakters van je vertaling niet correct weergeven. Dit is de reden waarom je een backup van je originele .properties bestanden moet maken, voor het geval je ze later wilt wijzigen.
Als je direct .properties bestanden wilt bewerken die zijn geconverteerd naar ASCII, kun je ook de Properties Editor applicatie gebruiken die beschikbaar is als een Jar uitvoerbaar bestand hier.

De helpbestanden vertalen

Een goede vertaling van Sweet Home 3D moet ook de vertaling van de helpbestanden bevatten. Het vertalen van alle bestanden is een lange taak, maar het zal gebruikers echt helpen om de software te leren en enkele ondersteuningsverzoeken in het Sweet Home 3D forum te vermijden. Gebruik een HTML-editor om deze bestanden te vertalen, probeer de links die het bevat en het stylesheet ongewijzigd te laten.
Eenmaal vertaald, moet je ook schermafbeeldingen maken van de dialoogvensters in je taal om de afbeeldingen te vervangen die gevonden worden in com/eteks/sweethome3d/viewcontroller/resources/help/en/images. Om zulke schermafbeeldingen te kunnen maken, maak en test een eerste SH3L-bestand met de volgende stappen (zodra een SH3L-bestand met vertaalde .properties bestanden bestaat, kun je ook aan de ontwikkelaar van Sweet Home 3D vragen om de schermafbeeldingen te genereren).

Het SH3L-bestand maken

Zodra alle .properties en .html bestanden zijn vertaald en indien nodig geconverteerd naar ASCII (of zelfs daarvoor als je deze procedure wilt testen), moet je ze inpakken in een bestand. Afhankelijk van je systeem kan het maken van een zip-bestand worden gedaan met de volgende procedure:

onder Windows, selecteer de com map die alle vertaalde bestanden bevat en kies Send to > Compressed folder uit het contextmenu,
onder Mac OS X, selecteer de com map die alle vertaalde bestanden bevat en kies File > Compress « com » menu-item,
onder Linux, selecteer de com map die alle vertaalde bestanden bevat, kies Create archive… uit het contextmenu en selecteer vervolgens .zip in de formaatlijst.

Verander ten slotte de .zip extensie van het zip-bestand naar .sh3l. Een SH3L-bestand kan elke naam hebben, maar om conflicten met bestaande SH3L-bestanden te vermijden, moet je het benoemen naar de taal die het bevat en de versie van Sweet Home 3D die je hebt vertaald (bijvoorbeeld, French-4.1.sh3l zou een goede naam kunnen zijn voor de Franse vertaling van Sweet Home 3D 4.1).

Een SH3L-bestand testen

Om de vertaling te testen, dubbelklik op een SH3L-bestand of kies het met de Import language library file knop die wordt weergegeven bovenaan het Preferences paneel. Dit start Sweet Home 3D en vertaalt de gebruikersinterface naar de taal die wordt beschreven in het SH3L-bestand. Dit kopieert ook het SH3L-bestand naar een map afhankelijk van je systeem:

onder Windows Vista / 7 / 8 / 10 / 11, is deze map C:UsersuserAppDataRoamingeTeksSweet Home 3Dlanguages,
onder Windows XP en eerdere versies van Windows, is deze map C:Documents and SettingsuserApplication DataeTeksSweet Home 3Dlanguages,
onder macOS, is het de submap Library/Application Support/eTeks/Sweet Home 3D/languages van je gebruikersmap,
onder Linux en andere Unix, is het de submap .eteks/sweethome3d/languages van je gebruikersmap,
met de draagbare versie van Sweet Home 3D, is het de submap data/languages van de map waar de Sweet Home 3D applicatie is opgeslagen,

Let er ook op dat je tijdens de ontwikkeling van je SH3L-bestand waarschijnlijk Sweet Home 3D opnieuw moet opstarten om de wijzigingen in je SH3L-bestand te zien.

SH3L-bestanden distribueren

Zodra je SH3L-bestand klaar is, kun je het aan iedereen aanbieden en het bekend maken aan Sweet Home 3D-gebruikers in het forumgedeelte voor vreemde talen of op andere plaatsen. Als je akkoord gaat, kan het beschikbaar worden gesteld op deze website op de pagina over vertalingen die door Sweet Home 3D worden ondersteund.

SH3L-bestanden bijwerken

Sommige releases van Sweet Home 3D brengen nieuwe functies met zich mee die vertaald moeten worden, andere niet. Als je de labels van de gebruikersinterface voor deze nieuwe functies niet vertaalt, zal Sweet Home 3D wel werken maar zullen alle nieuwe labels in het Engels verschijnen. Om de nieuwe en bijgewerkte sleutels in .properties bestanden te vinden, kun je gebruik maken van een functie van SourceForge.net waarmee je twee versies van een projectbestand kunt vergelijken:

Zoek de data van de Sweet Home 3D-versies die je wilt vergelijken in de geschiedenis (bijvoorbeeld 19 juli 2015 voor versie 5.0 en 2 februari 2015 voor versie 4.6)
Klik op het .properties of .html bestand dat je wilt bijwerken in figuur 1,
Selecteer de twee selectievakjes van het revisienummer dat overeenkomt met de versiedatum voor het bijgewerkte bestand, waarbij je de datum kiest die net voor een versiedatum van Sweet Home 3D ligt,
Klik op de knop Vergelijken.

De laatste klik laat je de verschillen zien tussen de twee versies van dat .properties bestand (bijvoorbeeld, deze link laat je de verschillen zien tussen versie 4.6 en versie 5.0 van het bestand com/eteks/sweethome3d/viewcontroller/package.properties).

Zodra je de verschillen hebt gevonden, werk je je vertaling bij, voeg indien nodig nieuwe sleutelnamen toe en breng een nieuwe versie van je vertaling uit.