Siegfried Locale Editor Userguide

Using the Siegfried Locale Editor

Start

To start the Siegfried Locale Editor double click the program icon. A double click on an existing "locale" file starts the editor and loads the file automatically.

It's also possible to start the editor from the terminal:

LocaleEditor <RETURN>

To work correctly the Siegfried Locale Editor needs the "sfliblocale.so" library at the local "lib" folder or "/boot/home/config/lib" folder. If the editor can't find the library during start up, an error message appears ("Could not open "LocaleEditor" (Missing library: sfliblocale.so)") and the editor terminates.


Structure of "locale" files

"locale" files contain mostly the text data of an application. But they include additional data:

This information can be shown/edited above the edit area (fields "Language", "Version" and "Application ID".

The name of the language (e.g. "Deutsch", "English") is the name that is returned by the language evaluation of a "locale" file. It's the native language name of the text data. The language name must not be the filename of a "locale" file. Theoretically a "locale" file for swedish can be named "Tomato.locale" or "Shuaheli.locale", but this isn't rich in meaning. Normally a "locale" is named for the native language that the file supports. If needed the application name can be added (eg. "SFImageFrancais.locale").

The application ID is a unique identifier for an application that is using "locale" files. The ID shows whether a "locale" file can be used by the application or not. Nothing brings up more strange effects than a "locale" file that isn't directed to the application ;-). The application ID is created by the developer of an application. All "locale" files of an application must have the same ID. Files with other IDs are ignored by the application. The developer is free to decide what kind of string is used for the application ID. It's a good idea if there is a reference to the application. For example, the Siegfried Locale Editor is using as application ID "siegfried localeeditor locale".

Note for developers: it's possible to use as ID the BApplication object signature of the application, because it's sffice unique.


The edit area

The edit area is the most important part of the Siegfried Locale Editor. All text to localize for an application will be managed here. The texts are organized in rows and seperated by a <RETURN>. The order of the texts is forcing! An application identifies the texts with the row number of the text. The principle of the text management is a table. Every row of the table is a text for the application. If, for example, the application need the 10th. text, a ten as argument is delivered to the sfliblocale.so library.

Texts that are longer as the width of the editor window will be automatically wrapped. The wrapping doesn't include a <RETURN>! Every table row is used as floating text. Empty rows are ignored by the editor. Additional comments can be included. A comment line is marked by a semicolon " ; " at the start of the line. The end of a comment is marked by a <RETURN>. Comment lines are shown in the color red. Important: comment lines will be not saved to the "locale" file. Comment lines are always temporary to a session!

When an existing "locale" file is edited, the new text is always appended to the end of the table. Inserting new rows between existing text results in a break of backward compatibility and is definitely a kind of "SF_DONT_DO_THAT"! :-)

The edit area includes the standard edit functionalty ("Cut/Copy/Paste/Undo"). But be aware while using the edit function. Unintensional removing or inserting of text between the rows can be result in an unexpected shifting of the rows. This brings strange results when using such a modified "locale" file. Wrong text will be printed.


Loading a reference

A reference assists a user by editing "locale" files. References are comment lines. A reference is created from an existing "locale" file or direct from an application which supports the "sfliblocale.so" library. Every text row is translated in a two line comment:

; #ID1:
; #ID1:
; First text line

; #ID2:
; Second text line

; #ID3:
; Third text line

   :
   :
   :
; #IDn:
; n-th. text line

The first comment line shows the row number of the table and the second line includes the text of the table row. That all is for simplification to translate the language text. If a new "locale" file is created there only needs to be translated text inserted between the empty lines. If an existing "locale" file is to edited it's easy to see which parts are to translate:

; #ID1:
; First text line
Erste Textzeile
; #ID2:
; Second text line
Zweite Textzeile
; #ID3:
; Third text line
Dritte Textzeile
   :
   :
   :
; #IDn-1:
; (n-1)th text line

; #IDn:
; n-th text line

There are two ways to load a reference:

  1. Loading an exitsing "locale" file as a reference. Every "locale" file can by loaded as a reference. To load a "locale" file as a reference use the "Load" button right of the reference line. A file requester opens where any given "locale" file can be selected.
  2. Get the texts directly from an application which supports the "sfliblocale.so" library. Every application which supports the "sfliblocale.so" library correctly offer the possibility to get the build-in (english) texts by using the BeOS scripting. To get the build-in texts the Siegfried Locale Editor and the targert application need to be started. The popup menu right of reference line shows every running application that supports the "sfliblocale.so" library. By selecting an application the Siegfried Locale Editor gets the complete text data as reference, the name of the language (normaly english) and the application ID. The popup menu shows a minimum of one application, the Siegfried Locale Editor itself.

If there was a previously loaded reference it will be replaced by the new one. Existing text will not be deleted. The new reference is inserted between the text.


Creating a new "locale" file

A new "locale" file is created by using an existing "locale" file as reference, or the text data will be grabbed directly from the running application. In both cases the loaded text is shown as a reference comment. In the most cases the second way is the better one, to load the a reference by using the BeOS scripting. By this it's always sure that the loaded data includes all text of an application. If an existing "locale" file is loaded it's possible the file isn't up to date (because the file was delivered with an older version of the application).

To create a new "locale" file 5 steps are necessary:

  1. Loading a reference by using the "Application" popup menu or the "Load" button of the reference line. The loaded data creates reference comments and stores the ID of the "locale" file to the application ID field.
  2. Enter the name for the language at the field "Language". The name is always written in the native language for the new "locale" file. If, for example, a german "locale" file is to be created, the name to be inserted for the language is "Deutsch" or for a spanish file "Espanol". This name is used later by the application to show the available languages. Pay attention to the upper and lower case for the name. Simple rule: write the first character in upper case and the rest in lower case.
  3. Set a version number at the "Version" field. The version should have the format "##.##" incl. tralling zeros (eg. "01.00").
  4. Insert the translated text below the reference comments. If there is no translation for a text row, insert the english text. The order of the text is important. Don't change the order otherwise the application will produce unexpected text output results.
  5. Save the new "locale" file. By using the "Save" button of the "Language" line a file requester opens. The filename can be set free, but it's recommended to use the language name as file name or the language name in addition with the application name. Where the "locale" is saved depends on the application. Normaly the application uses a folder named "locale" in the same directory where the application is found. This convention isn't binding, but it's recommended.

Edit an existing "locale" file

Editing an existing "locale" file is needed to correct typing errors or to add new text.

To edit a "locale" file use the "Load" button of the "Language" line. A file requester opens and the "locale" file can be selected. The editor loads the text of the file into the edit area. In addition the fields "Language", "Version" and "Application ID" will be set.

It's possible to load a reference after a "locale" file is loaded. To load a reference use the "Load" button or the "Application" popup menu of the reference line. The reference text will be inserted automatically between the text lines. It's all the same if the text or the reference is loaded first. In every case the data is inserted correctly.

To get the newest text, it's recommend to load the refernce by using "Application" popup menu. Scrolling to the end of the text area shows if new text have to add.