# Stonevoice Translator User Guide

## Status

This document contains detailed information about some of the Stonevoice Translator features, but consider that:

- This document is NOT exhaustive.
- This document does not contain information already provided in the Features Overview and the Glossary.

Information in this document is organized sequentially.

## File Types

### Supported Text File Formats

Stonevoice Translator supports the following text file formats:

- Generic INI-like language files (`*.ini`)
- Inno Setup INI-like language files (`*.isl`)
- BSplayer INI-like language files (`*.lng`)
- FlasKMPEG-like language files (`*.flask`; `*.lng`)
- ASP/VBScript "Variable = String" (`*.dat.asp`)
- JavaScript "Variable = String" (`*.dat.js`)

Stonevoice Translator preserves all the comments and unrecognized parts of the file, even if they are different between the reference and the translation. The recognized strings are made available for translation in the Contents tree view.

The `Examples` folder installed with Stonevoice Translator contains some text files that demonstrate special features, like Translation Notes and Subsections.

### Supported Binary File Formats

Stonevoice Translator supports the following binary file formats:

- Sounds (`*.wav`)
- Images (`*.gif`;`*.jpg`;`*.bmp`;`*.ico`)

Although it is possible to open binary files one at a time, they are usually loaded as part of a translator tree (`*.svt`).

### Opening Multiple Files at Once

The most common use of Stonevoice Translator is to work with one file that contains all the strings to be translated.

Stonevoice Translator can also open multiple files at once using a translator tree, a special file with a `.svt` extension that contains references to other files with the actual strings to be translated. Translator trees also allow the loading of multiple binary files at once, for example from a folder containing sevaral images and sounds to be translated.

The `Examples\Advanced` folder installed with Stonevoice Translator contains an example of a simple translator tree.

Note - If you create a new translation starting from a reference translator tree, the new translation must be saved in a different folder.

## Open Modes

A file (or a translator tree) may be opened using one of four open modes:

1. Reference (read-only)
   This is the original version, usually in English. It is the reference for the localization process.
2. Old Translation (read-only)
   This is the translation of the previous version of the application in your language. It can be used as a reference or automatically imported in the translation.
3. Translation
   This is the result of the localization process. The structure of this file (number and name of the entries) should be identical to the structure of the reference file. You may click on the New button near the Translation label (or press `Ctrl-N`) to create a new translation file with the structure of the reference.
4. Test Output (write-only)
   This open mode is used to test your work in real-time.

## Node Types

All the localizable files and strings can be browsed using the Contents tree view.

There are different types of nodes in the tree view, shown in different colors:

- Structural nodes for navigation (expandable nodes and file names)
- Translatable entries
- Reference-only (locked) entries (present in the old translation but not available in the new one)
- Auto set nodes (by using the dictionary or import features)
- Verified nodes (marked by pressing the Set Verified Flag button)

The translatable entries are bold if they are untranslated (if the translation is empty or identical to the reference).

Tip - To mark an untranslated string as translated, either modify it or use the Set Verified Flag button.

## Navigation

You can move through entries using the Previous and Next buttons or the `PgUp` / `PgDn` keys.

Note - The `PgUp` / `PgDn` keys do not work as expected when the Contents tree view is selected.

You can change the move mode by clicking on the drop-down arrow near the Next button, and selecting:

- All Entries
  All the entries, but not the structural nodes.
- Untranslated
  Entries which have the "untranslated" property set.
- Unmatched
  Entries which have the "unmatched" property set. This move mode is not visible by default.
- Auto Set
  Entries which have the "auto set" property set.
- Not Verified
  Entries not explicitly marked with the "verified" flag (see the Set Verified Flag button).
- To Be Verified
  Entries explicitly marked with the "to be verified" flag (see the Set To Be Verified Flag button).
- Search Results (1, 2, 3)
  Moves through nodes using one of the custom search criteria.

> Tip - To modify the search criteria, use the Find button.

## Test Save Modes

You can change the test save mode by clicking on the drop-down arrow near the Save button in the Test Output row, and selecting:

- Save Test File on Demand
  The test file will not be saved unless you click on the Save button in the Test Output row.
- Save Test File with Translation (default)
  Every time you click on the Save button in the Translation row or switch to another translation file, the test file will be saved.
- Save Test File on Every Change
  Every time you manually translate an entry and then move to another one, the affected file will be saved. This allows for real-time testing of the translation.

## Decorations

### Symmetrical and Asymmetrical Decoration Characters

Consider the following two strings:

> [no filter applied]

> Users %1-%2 of %3 (%4 selected)

In the first case, the square brackets are clearly decorations and can be hidden during the translation. In the second string, the rightmost parenthesis isn't a decoration and should not be hidden. To take this into account, all kinds of parentheses are considered symmetrical decorations, because they must be considered only if there is a matching symbol on the other side of the string. Spaces and newlines can be removed freely and are asymmetrical decorations.

### Decoration Eating

Firstly, if both a reference and a translation is available, decoration hiding is applied. Asymmetrical decorations present at the beginning or at the end of both strings are removed, then the symmetrical ones are also removed. If Stonevoice Translator finds out that after the removal of the symmetrical decorations there are new asymmetrical decorations to remove, the process is repeated.

Secondly, decoration identification is applied. The remaining symmetrical and asymmetrical decorations are identified, and any difference is taken into account.

### Decoration Characters

To see or modify which characters are considered decorations, open the Options window and select the Decorations category.

## Advanced Search

To open the Search window, click on the Find button.

The Search window is organized in tabs. Only nodes that match the criteria specified in ALL the tabs at the same time will be found. When you specify search criteria in a tab, the tab icon changes to the active version.

Stonevoice Translator stores search criteria in search slots. You may switch to another search slot by clicking on the drop-down arrow near the Last button, and selecting the appropriate menu item.

## Work on Search Results

You can modify all the nodes that are part of the current slot's search results. To do it:

1. Enter the search criteria in the Find window.
2. Click on the drop-down arrow near the Find button.
3. Click on the Work on Search Results menu item.
4. Select the operations you want to perform.
5. Click on the OK button.