| 
|
The .properties files must be placed in the
folders shown in figure 1. otherwise Sweet Home 3D won't be
able to use them correctly. So don't move the files out of their
folder, don't rename any folder (except the en
subdirectory of help) and don't delete any folder. |
Renaming files depending on your language
Before translating the .properties files, you should
rename each of them by adding to their name an underscore followed by
the 2 characters ISO code matching your language. You'll find this code
in the last column of the document https://www.loc.gov/standards/iso639-2/php/English_list.php.
Then, if you want to translate the help files, you should rename also
the en subdirectory of help with that 2 letters
code too.
For example, the ISO code for Czech is cs. If you want
to translate Sweet Home 3D into Czech, each file name should be suffixed
by _cs, and you should rename the files as shown in figure 2.
Figure 2. Properties files with their ISO code suffix
Translating properties files
The .properties files are plain text files and you may
edit them with any text editor like Wordpad, TextEdit
or emacs. For example, the com/eteks/sweethome3d/package.properties
file in Sweet Home 3D 3.0 contains the following text:
HomeFramePane.untitled=Untitled
MacOSXConfiguration.WINDOW_MENU.Name=Window
MacOSXConfiguration.MINIMIZE.Name=Minimize
MacOSXConfiguration.ZOOM.Name=Zoom
MacOSXConfiguration.BRING_ALL_TO_FRONT.Name=Bring all to front
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
A .properties file contains three kinds of lines:
- the lines that starts with a # character are comments (shown in
green in the previous example). Some comments contain legal information,
some give information to developers or to translators. Keep these
lines unchanged.
- empty lines are just used to separate the various parts of a
.properties
file.
- the other lines start with some text used by Sweet Home 3D as a
key to find a text displayed at screen (shown in blue in the previous
example). Following this key, each of these lines contains an equal
sign (
=) and a text in a given language. Your job starts
from the equal signs. Don't change the text of the key and replace
the English text after the equal sign by its translation.
Special cases:
- The texts starting with a
<html>
tag contains some text at HTML format. These texts contain some other
HTML tags between <
and > signs, like
<br> in the previous
example which represents a carriage return in the middle of long texts.
Don't remove these HTML tags, they help Sweet Home 3D to present correctly
some texts. Translating text between HTML tags isn't very difficult,
except maybe for the worst HTML text which is the value of WallPanel.wallOrientationLabel.text
key.
- To avoid long lines in the text editor, some lines
are splitted in two or more lines and then separated by back slashes
\, like the line starting
by SweetHome3D.3DError.message
in the previous example. In that case, don't remove the \
sign located at the end of a line because it indicates the next line
follows the current line.
- Some texts contain special characters sequence starting
with a
% sign, like %s, %d,
%1$s, %2$s... These characters sequence
will be replaced by a file name, a unit or a number when needed, so
don't remove them.
For example, the character sequence %s
in the text of the following key HomeFurniturePanel.widthLabel.text:
HomeFurniturePanel.widthLabel.text=Width (%s):
will be replaced by the unit currently in use. The two character sequences
%1$d and %2$d
that appear in the text of the following key PrintPreviewPanel.pageLabel.text:
PrintPreviewPanel.pageLabel.text=Page %1$d/%2$d
will appear at screen as a page number and the page count, and you
should translate only the word Page.
- Some texts contain also the special characters sequence
\n, like in the following
example:
HomeController.saveError=Can't save home in\n"%s"
This character sequence is displayed by Sweet Home 3D as a carriage
return to split a line at screen, and you shouldn't remove them.
- The value of the key
HelpController.helpIndex
indicates the directory where the help files can be found. If you
translate the .html help files, you should replace the
en subdirectory found by the 2 letters code of your language.
For example, if you translate help to Czech, it shoud become:
HelpController.helpIndex=/com/eteks/sweethome3d/viewcontroller/resources/help/cs/index.html
The text of the keys that ends with .mnemonic
are used by Sweet Home 3D to guess which letter in a label or a menu
item should be underlined for keyboard access. This mnemonic letter
depends on the displayed word and you should find a unique one per
dialog box or menu.
For example, the following texts and mnemonics displayed in the furniture
modification dialog box :
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
can be translated in French by:
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.
Converting properties files to ASCII encoding
If you translated texts into a language
with letters not belonging to ISO-8859-1
encoding (mainly Central and Eastern Europe languages and languages
with a non-latin alphabet), you'll have to convert all your .properties
files to an ASCII encoding supported by Sweet Home 3D. This conversion
can be done with the native2ascii tool provided with the
JDK or can be performed
with the following form.
For each .properties file, create a backup of that file,
copy/paste the text to convert in the following text area, click on
the Convert button and copy/paste the converted text back in
its .properties file.
The conversion tool will replace each non ASCII character (accented
latin letters and non-latin letters) by a sequence starting by \u
and followed by a 4 hexadecimal digits code matching that character
in Unicode. Miserably, this conversion will make your text quite unreadable
for a human, but if you don't perform it, Sweet Home 3D won't be able
to display the characters of your translation correctly. This is the
reason why you should create a backup of your original .properties
files, in case you want to change them later.
If you want to directly edit .properties files converted to ASCII, you may also use Properties Editor
application available as a Jar executable file here.
Translating the help files
A good translation of Sweet Home 3D should also include the translation
of its help files. Translating all the .html files is a
long task, but it will really help the users to learn the software and
avoid some support requests in Sweet Home 3D forum. Use any HTML editor
to translate these files, trying to keep the links it contains and its
style sheet unchanged.
Once translated, you should also create screen captures of the dialog
boxes in your language to replace the images found in com/eteks/sweethome3d/viewcontroller/resources/help/en/images. To be able to create such screen
captures, create and test a first SH3L file with the following steps (once a SH3L file containing translated .properties files exists, you may also request to
the developer of Sweet Home 3D to generate the screen captures).
Creating the SH3L file
Once all the .properties and .html files
are translated and converted to ASCII if necessary (or even before if
you want to test this procedure), you should zip them in a file. Depending
on your system, creating a zip file can be done with the following procedure:
- under Windows, select the
com folder containing all
the translated files and choose Send to > Compressed folder
from its contextual menu,
- under Mac OS X, select the
com folder containing all
the translated files and choose File > Compress « com »
menu item,
- under Linux, select the
com folder containing all
the translated files, choose Create archive... from its contextual
menu then select .zip in the format list.
Finally, change the .zip extension of the zip file
to .sh3l. A SH3L file can have any name, but to avoid conflicts
with existing SH3L files, you should name it from the language it contains
and the version of Sweet Home 3D you translated (for example, French-4.1.sh3l
could be a good name for the French translation of Sweet Home 3D 4.1).
Testing a SH3L file
To test the translation, double-click on a SH3L file or choose it with the Import language library file button 
displayed at the top of the Preferences pane. This will launch
Sweet Home 3D and translate its user interface to the language described
in the SH3L file. This will also copy the SH3L file in a folder depending
on your system:
- under Windows Vista / 7 / 8 / 10 / 11, this folder is C:\Users\user\AppData\Roaming\eTeks\Sweet
Home 3D\languages,
- under Windows XP and previous versions of Windows, this folder
is C:\Documents and Settings\user\Application Data\eTeks\Sweet
Home 3D\languages,
- under macOS, it's the subfolder Library/Application Support/eTeks/Sweet
Home 3D/languages of your user folder,
- under Linux and other Unix, it's the subfolder .eteks/sweethome3d/languages
of your user folder,
- with the portable version of Sweet Home 3D, it's the subfolder data/languages of the folder where Sweet Home 3D application is stored,
Note also that during the development of your SH3L file, you'll probably
have to relaunch Sweet Home 3D to see the changes in your SH3L file.
Distributing SH3L files
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.
Updating SH3L files
Some releases of Sweet Home 3D bring new features to translate, some
don't. If you don't translate the user interface labels matching these
new features, Sweet Home 3D will work but all the new labels will appear
in English. To find the new keys and the updated keys in .properties
files, you can use a feature offered by SourceForge.net that lets you
compare two versions of a project file:
- 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)
- Click on the
.properties or .html file
you want to update in figure 1,
- Select the two check boxes of the revision number matching the version date for the updated file,
choosing the date that is just before a version date of Sweet Home 3D,
- Click on Compare button.
The last click will show you the differences between the two versions
of that .properties file (for example, this link
will show you the differences between the version 4.6 and the version
5.0 of the file com/eteks/sweethome3d/viewcontroller/package.properties).
Once you found the differences, udpate your translation, adding new
key names if necessary, and release a new version of your translation.
