Ръководство за превод

Въведение
Основни инструкции
Подробни инструкции

Въведение

Говориш чужд език, който все още не се поддържа в Sweet Home 3D и искаш да допринесеш за превода му на този език? От версия 2.3, Sweet Home 3D поддържа SH3L файлове и това ръководство ще ти покаже как да създадеш такъв файл самостоятелно. SH3L файлът е автоматично инсталиращ се езиков файл и потребителите трябва само да кликнат два пъти върху SH3L файл, за да преведат Sweet Home 3D на езика, описан в този файл.

Основни инструкции

Създаването на SH3L файл се състои от:

downloading an English version of the files to translate,
разархивиране на изтегления файл,
добавяне на 2-буквен суфикс, съответстващ на твоя език към .properties файловете, които съдържа,
превеждане на текста в .properties файловете,
конвертиране в ASCII кодировка,
превеждане на помощния текст в .html файловете (не е задължително, но ще бъде наистина полезно за потребителите),
архивиране на .properties файловете и помощните файлове обратно във файл с разширение SH3L,
двойно кликване върху SH3L файла, за да тестваш превода си в Sweet Home 3D,
разпространение на твоя SH3L файл.

Подробни инструкции

Ако не се притесняваш от предишните основни инструкции, продължи със следващите стъпки.

Получаване на английската версия

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.

Всички .properties и .html файлове съдържат английската версия на текстовете, които трябва да преведеш на твоя език:

package.properties файловете описват етикети, менюта и елементи от менюта, показани в потребителския интерфейс на Sweet Home 3D,
basic.properties и metal.properties файловете описват стандартните етикети на диалоговите прозорци,
тези, завършващи на Catalog.properties описват имената на мебелите и текстурите, налични в софтуера,
.html файловете съдържат текста на помощната информация на Sweet Home 3D.

.properties файловете трябва да бъдат поставени в папките, показани на фигура 1. В противен случай Sweet Home 3D няма да може да ги използва правилно. Затова не премествай файловете от техните папки, не преименувай никоя папка (с изключение на en поддиректорията на help) и не изтривай никоя папка.

Преименуване на файловете според твоя език

Преди да преведеш .properties файловете, трябва да преименуваш всеки от тях, като добавиш към името им долна черта, последвана от 2-буквения ISO код, съответстващ на твоя език. Ще намериш този код в последната колона на документа https://www.loc.gov/standards/iso639-2/php/English_list.php.
След това, ако искаш да преведеш помощните файлове, трябва да преименуваш също и поддиректорията на с този 2-буквен код.
Например, ISO кодът за чешки език е . Ако искаш да преведеш Sweet Home 3D на чешки, всяко име на файл трябва да завършва с _cs, и трябва да преименуваш файловете както е показано на фигура 2.

Ръководство за превод — *Фигура 2. Properties файлове с техния ISO код суфикс*

Превеждане на properties файлове

.properties файловете са обикновени текстови файлове и можеш да ги редактираш с всеки текстов редактор като Wordpad, TextEdit или emacs. Например, com/eteks/sweethome3d/package.properties файлът в Sweet Home 3D 3.0 съдържа следния текст:

# 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

# Ресурси за HomeFramePane клас
HomeFramePane.untitled=Без име


# Ресурси за MacOSXConfiguration клас
MacOSXConfiguration.WINDOW_MENU.Name=Прозорец
MacOSXConfiguration.MINIMIZE.Name=Минимизирай
MacOSXConfiguration.ZOOM.Name=Мащабиране
MacOSXConfiguration.BRING_ALL_TO_FRONT.Name=Изведи всички напред


# Ресурси за SweetHome3D клас
SweetHome3D.3DError.message=<html> Sweet Home 3D ще се затвори поради фатална грешка
    <br>в 3D системата за рендериране. Моля, обнови DirectX/OpenGL драйверите
    <br>на твоята графична карта. 
SweetHome3D.3DError.title=3D Грешка
    
SweetHome3D.confirmSaveAfter3DError.message=<html> Sweet Home 3D трябва да се затвори поради фатална грешка в
    <br>3D системата за рендериране. Искаш ли да запазиш всички променени проекти? 
SweetHome3D.confirmSaveAfter3DError.title=3D Грешка
SweetHome3D.confirmSaveAfter3DError.save=Запази
SweetHome3D.confirmSaveAfter3DError.doNotSave=Не запазвай

.properties файлът съдържа три вида редове:

редовете, които започват със знака # са коментари (показани в зелено в предишния пример). Някои коментари съдържат правна информация, някои дават информация на разработчиците или преводачите. Запази тези редове непроменени.
празните редове се използват само за разделяне на различните части на .properties файла.
другите редове започват с текст, използван от Sweet Home 3D като ключ за намиране на текст, показван на екрана (показан в синьо в предишния пример). След този ключ, всеки от тези редове съдържа знак за равенство (=) и текст на даден език. Твоята работа започва от знаците за равенство. Не променяй текста на ключа и замени английския текст след знака за равенство с неговия превод.

Специални случаи:

Текстовете, започващи с <html> таг съдържат текст в HTML формат. Тези текстове съдържат други HTML тагове между < и > знаци, като <br> в предишния пример, който представлява нов ред в средата на дълги текстове. Не премахвай тези HTML тагове, те помагат на Sweet Home 3D да представя правилно някои текстове. Превеждането на текст между HTML тагове не е много трудно, с изключение може би на най-лошия HTML текст, който е стойността на WallPanel.wallOrientationLabel.text ключа.
За да се избегнат дълги редове в текстовия редактор, някои редове са разделени на два или повече реда и са разделени с обратни наклонени черти \, като реда, започващ с SweetHome3D.3DError.message в предишния пример. В този случай, не премахвай \ знака, разположен в края на реда, защото той показва, че следващият ред следва текущия ред.
Някои текстове съдържат специална последователност от знаци, започваща със знак %, като %s, %d, %1$s, %2$s… Тези последователности от знаци ще бъдат заменени с име на файл, мерна единица или число когато е необходимо, затова не ги премахвай.
Например, последователността от знаци %s в текста на следния ключ HomeFurniturePanel.widthLabel.text:
```
HomeFurniturePanel.widthLabel.text=Ширина (%s):
```
ще бъде заменена с текущо използваната мерна единица. Двете последователности от знаци %1$d и %2$d които се появяват в текста на следния ключ PrintPreviewPanel.pageLabel.text:
```
PrintPreviewPanel.pageLabel.text=Страница %1$d/%2$d
```
ще се появят на екрана като номер на страница и общ брой страници, и ти трябва да преведеш само думата Page.
Някои текстове съдържат също специалната последователност от знаци \n, както в следния пример:
```
HomeController.saveError=Не може да се запази проекта в
"%s"
```
Тази последователност от знаци се показва от Sweet Home 3D като нов ред за разделяне на ред на екрана и не трябва да я премахваш.
Стойността на ключа HelpController.helpIndex показва директорията, където могат да бъдат намерени помощните файлове. Ако превеждаш .html помощните файлове, трябва да замениш en поддиректорията с 2-буквения код на твоя език.
Например, ако превеждаш помощта на чешки, тя трябва да стане:
```
HelpController.helpIndex=/com/eteks/sweethome3d/viewcontroller/resources/help/cs/index.html
```

Текстът на ключовете, които завършват с .mnemonic се използва от Sweet Home 3D за да определи коя буква в етикет или елемент от меню трябва да бъде подчертана за достъп от клавиатурата. Тази мнемонична буква зависи от показваната дума и трябва да намериш уникална такава за всеки диалогов прозорец или меню.
Например, следните текстове и мнемоники показани в диалоговия прозорец за модификация на мебели:
```
HomeFurniturePanel.nameLabel.text=Име:
HomeFurniturePanel.nameLabel.mnemonic=N
HomeFurniturePanel.nameVisibleCheckBox.text=Показвай името в плана
HomeFurniturePanel.nameVisibleCheckBox.mnemonic=S
HomeFurniturePanel.widthLabel.text=Ширина (%s):
HomeFurniturePanel.widthLabel.mnemonic=W
```
могат да бъдат преведени на френски като:
```
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.

Конвертиране на properties файлове в ASCII кодировка

Ако си превел текстове на език с букви, които не принадлежат на ISO-8859-1 кодировката (главно езици от Централна и Източна Европа и езици с нелатинска азбука), ще трябва да конвертираш всички твои .properties файлове в ASCII кодировка, поддържана от Sweet Home 3D. Това конвертиране може да бъде направено с native2ascii инструмента, предоставен с JDK или може да бъде извършено със следната форма.
За всеки .properties файл, създай резервно копие на този файл, копирай/постави текста за конвертиране в следното текстово поле, кликни върху бутона Конвертирай и копирай/постави конвертирания текст обратно в неговия .properties файл.

Инструментът за конвертиране ще замени всеки не-ASCII знак (акцентирани латински букви и нелатински букви) с последователност, започваща с \u и последвана от 4-цифрен шестнадесетичен код, съответстващ на този знак в Unicode. За съжаление, това конвертиране ще направи текста ти доста нечетлив за човек, но ако не го извършиш, Sweet Home 3D няма да може да показва правилно знаците от твоя превод. Това е причината, поради която трябва да създадеш резервно копие на оригиналните си .properties файлове, в случай че искаш да ги промениш по-късно.
Ако искаш директно да редактираш .properties файлове, конвертирани в ASCII, можеш също да използваш приложението Properties Editor, налично като изпълним Jar файл тук.

Превеждане на помощните файлове

Добрият превод на Sweet Home 3D трябва да включва също и превода на помощните файлове. Превеждането на всички .html файлове е дълга задача, но наистина ще помогне на потребителите да научат софтуера и да се избегнат някои заявки за поддръжка във форума на Sweet Home 3D. Използвай всеки HTML редактор за превод на тези файлове, опитвайки се да запазиш връзките, които съдържа и неговия стилов лист непроменени.
След като са преведени, трябва също да създадеш екранни снимки на диалоговите прозорци на твоя език, за да замениш изображенията, намиращи се в com/eteks/sweethome3d/viewcontroller/resources/help/en/images. За да можеш да създадеш такива екранни снимки, създай и тествай първо SH3L файл със следващите стъпки (след като съществува SH3L файл, съдържащ преведени .properties файлове, можеш също да поискаш от разработчика на Sweet Home 3D да генерира екранните снимки).

Създаване на SH3L файл

След като всички .properties и .html файлове са преведени и конвертирани в ASCII, ако е необходимо (или дори преди, ако искаш да тестваш тази процедура), трябва да ги архивираш в zip файл. В зависимост от твоята система, създаването на zip файл може да бъде направено със следната процедура:

под Windows, избери com папката, съдържаща всички преведени файлове и избери Изпрати до > Компресирана папка от контекстното меню,
под Mac OS X, избери com папката, съдържаща всички преведени файлове и избери Файл > Компресирай « com » от менюто,
под Linux, избери com папката, съдържаща всички преведени файлове, избери Създай архив… от контекстното меню, след това избери .zip от списъка с формати.

Накрая, промени .zip разширението на zip файла на .sh3l. SH3L файлът може да има всякакво име, но за да избегнеш конфликти със съществуващи SH3L файлове, трябва да го именуваш според езика, който съдържа и версията на Sweet Home 3D, която си превел (например, French-4.1.sh3l би било добро име за френския превод на Sweet Home 3D 4.1).

Тестване на SH3L файл

За да тестваш превода, кликни два пъти върху SH3L файл или го избери с бутона Импортирай езиков библиотечен файл показан в горната част на панела Предпочитания. Това ще стартира Sweet Home 3D и ще преведе потребителския му интерфейс на езика, описан в SH3L файла. Това също ще копира SH3L файла в папка, зависеща от твоята система:

под Windows Vista / 7 / 8 / 10 / 11, тази папка е C:UsersпотребителAppDataRoamingeTeksSweet Home 3Dlanguages,
под Windows XP и предишни версии на Windows, тази папка е C:Documents and SettingsпотребителApplication DataeTeksSweet Home 3Dlanguages,
под macOS, това е подпапката Library/Application Support/eTeks/Sweet Home 3D/languages на твоята потребителска папка,
под Linux и други Unix системи, това е подпапката .eteks/sweethome3d/languages на твоята потребителска папка,
с преносимата версия на Sweet Home 3D, това е подпапката data/languages на папката, където е съхранено приложението Sweet Home 3D,

Отбележи също, че по време на разработката на твоя SH3L файл, вероятно ще трябва да рестартираш Sweet Home 3D, за да видиш промените в SH3L файла си.

Разпространение на 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.

Актуализиране на SH3L файлове

Някои версии на Sweet Home 3D добавят нови функции за превод, други не. Ако не преведеш етикетите на потребителския интерфейс, съответстващи на тези нови функции, Sweet Home 3D ще работи, но всички нови етикети ще се появят на английски. За да намериш новите ключове и актуализираните ключове в .properties файловете, можеш да използваш функция, предлагана от SourceForge.net, която ти позволява да сравниш две версии на проектен файл:

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)
Кликни върху .properties или .html файла, който искаш да актуализираш в фигура 1,
Избери двете квадратчета на номера на ревизията, съответстващи на датата на версията за актуализирания файл, като избереш датата, която е точно преди датата на версията на Sweet Home 3D,
Кликни върху бутона Сравни.

Последният клик ще ти покаже разликите между двете версии на този .properties файл (например тази връзка ще ти покаже разликите между версия 4.6 и версия 5.0 на файла com/eteks/sweethome3d/viewcontroller/package.properties).

След като намериш разликите, актуализирай превода си, добавяйки нови имена на ключове при необходимост, и пусни нова версия на превода си.