# Details

## Command line options

StarDict usage:

stardict options query_word

query_word

  With query_word you request StarDict to look up the specified word just after startup. It has the same effect as if you had typed that word in the Search field. You may use pattens, fuzzy query and other supported modes.

-m, --message-level=integer

  This option specifies the minimum severity level of message that should be printed on console. The value may range from 0 to 6, where 0 means to suppress all output, 6 ‒ print all produced messages, including debug ones. Default value is 4 which passes informational messages, like what dictionaries are loaded during startup.

-l, --log-level=integer

  This option specifies the minimum severity level of message that should be logged. The value may range from 0 to 6, where 0 means to suppress all output, 6 ‒ print all produced messages, including debug ones. Default value is 0, that is log file is not used. See Logging for details about StarDict log.

-h, --hide

  Do not show splash screen during startup and hide the Main window. Only notification area icon will be visible.

-n, --new

  Start a new instance of StarDict. By default StarDict checks if the application is already running and prevents starting the second instance.

  This option is only available in Windows edition and Gnome edition of StarDict.

-q, --quit

  Quit an existing instance of StarDict.

  This option is only available in Gnome edition of StarDict.

--dirs-config

  Specifies path to the StarDict directory configuration file. See StarDict directories for details about StarDict directories and configuration file.

  This option is only available in Windows edition of StarDict.

--portable-mode

  Activate portable mode, see StarDict Portable. Specifying the option is not enough to make StarDict to be StarDict Portable. You should avoid using this option unless you know what you are doing.

  This option is only available in Windows edition of StarDict.

## Dictionary Management

To manage the dictionaries, click the Manage dictionaries button at the bottom-right corner of the Main window, or click the Main menu button and choose Dict manage.

In the dictionary management dialog, you can disable dictionaries that you don't need, and you can set the order in which the dictonaries are queried.

StarDict will search the dictionary files at "~/.stardict/dic" and "/usr/share/stardict/dic", and search tree dictionary files at "~/.stardict/treedict" and "/usr/share/stardict/treedict"

## Help

Inside StarDict you may open documentation either by pressing the `F1` key or by clicking the Main menu button, then the Help item in the popup menu. StarDict documentation has different formats depending on application edition. The primary documentation format is DocBook. StarDict installs documentation in DocBook format only in Gnome edition. In this edition documentation seamlessly integrates with Gnome documentation system. It can be read through Help Browser. Documentation was translated into a number of languages. You are presented with localized version if it's available. Gnome allows to configure the prefered language.

In other editions of StarDict documentation is available in html format. You need to configure Web browser to view documentation, see Web browser. Choosing documentation language, StarDict roughly follows gettext package locale selection algorithm. The LANGUAGE enviroment variable is checked first. It's expected to contain a list of language codes in the order of preference. If the LANGUAGE variable is not set, the current locale is inspected. Finally, if documentation in prefered languages is not available, the english documentation is shown.

In Windows edition of StarDict the default language corresponds to the language selected in the Regional and Language Options dialog.

### Changing default language

Open Control Panel, Regional and Language Options. Regional and Language Options dialog pops up. On the Regional Options tab select a language in the Stardards and formats group.

You may override the default language with the LANGUAGE environment variable.

Normally, help files can be found in the C:\Program Files\StarDict\help directory. Each directory corresponds to one language. Directories are named after language codes.

## StarDict directories

StarDict uses a number of directories to store application data, load and save configuration settings. Default directories are assigned at build time, but some of them can be overriden with stardict-dirs.cfg file. Overriding StarDict directories is useful for debugging, preparing special configurations like StarDict-portable for Windows, an ordinary user does not need this.

StarDict searches for the stardict-dirs.cfg file in the user_config_dir directory. You may override location of the stardict-dirs.cfg file with STARDICT_DIRS_CONFIG_FILE environment variable or with --dirs-config command line option. Command line option takes the highest precedence, then the environment variable is inspected, and finally the file in the user_config_dir directory. The first specified file wins, it will be probed as a configuration file. If load fails, no other files will be tried.

The stardict-dirs.cfg file is a .ini-like config file. The syntax of .ini files is described in detail in the Desktop Entry Specification. All keys must belong to “general” group.

Do not forget to double backslash characters in values. Backslash is used as path separator in Windows.

Example of stardict-dirs.cfg file for Windows:

    [general]
    data_dir=C:\\Program Files\\StarDict
    dll_dir=C:\\StarDict\\msvc_2008\\Debug
    plugin_dir=C:\\StarDict\\msvc_2008\\Debug

### StarDict directories

user_config_dir

  A directory of configuration files.

  Windows default: C:\Documents and Settings\%USERNAME%\Application Data\StarDict.

  Other default: ~/.stardict.

  Environment variable: STARDICT_CONFIG_PATH.

  stardict-dirs.cfg key: user_config_dir.

user_cache_dir

  User cache directory.

  Windows default: C:\Documents and Settings\%USERNAME%\Temporary Internet Files\stardict.

  Other default: ~/.cache/stardict.

  stardict-dirs.cfg key: user_cache_dir.

data_dir

  Data directory.

  Windows default: C:\Program Files\StarDict.

  Other default: /usr/share/stardict.

  stardict-dirs.cfg key: data_dir.

dll_dir

  A directory of hook dlls, in Windows edition only.

  Windows default: data_dir.

  stardict-dirs.cfg key: dll_dir.

plugin_dir

  A directory of StarDict plugins.

  Windows default: data_dir + "/plugins".

  Other default: /usr/lib/stardict/plugins.

  stardict-dirs.cfg key: plugins_dir.

help_dir

  A directory of help files, in all editions except Gnome edition.

  Default: data_dir + "/help".

  stardict-dirs.cfg key: help_dir.

log_dir

  A directory for log files.

  Windows default: C:\Documents and Settings\%USERNAME%\Local Settings\Temp\StarDict.

  Other default: /var/tmp/stardict.

  stardict-dirs.cfg key: log_dir.

Default values in the list above are given for the purpose of illustrating possible values of variables. Actual default value depends on a number of factors and cannot be computed easily. See AppDirs class in the conf.h file for details on how the default value is calculated.

## Logging

StarDict may log messages into a file. By default logging is turned off, you may enable it specifing non-zero log level with --log-level command line option, see Command line options.

By default messages are printed on to console, log file may be useful if console is not available like in Windows. Log may be useful in troubleshooting startup problems.

For default location of the log directory see StarDict directories, log_dir parameter. StarDict log files are named like stardict-process_number.log. We need to use process numbers to create unique log files, since multiple StarDict instances may run at the same time. To find the log file belonging to the most recently started instance of StarDict, consider file creation time.

## Interface language

This section describes the algorithm used to select interface language in StarDict.

1. Retrieve STARDICTLANG environment variable. Goto 3 if the variable is defined.

2. Retrieve the user default locale (to set the default locale: Control Panel ▸ Regional and Language Options ▸ Regional Options ▸ Standards and formats ▸ Language). If locale is not defined, use "en".

3. Assign the language code to the LANG environment variable.

4. Retrieve the value of the environment variable LANGUAGE. This is a GNU extension. Its value can be a colon-separated list of locale names. If defined, goto 8.

5. The value of the environment variable LC_ALL, LC_xxx, or LANG. More precisely, the first among these that is set to a non-empty value. This is how POSIX specifies it. The value is a single locale name. If defined, goto 8.

6. A system-dependent preference list of languages. Its value can be a colon-separated list of locale names. If defined, goto 8.

7. A system-dependent default locale name. If defined, goto 8.

8. Processes the found value as a colon-separated list of language codes. Select the first available language. If none is available, select no translation.

Steps 4 through 8 describe translation selection algorithm of the gettext package. The actual procedure may be different.

The best way to specify interface language of StarDict is to define STARDICTLANG environment variable. It should contain language code. See $StarDictDataDir/locale for the list of supported languages.

## StarDict dictionaries

StarDict supports two types of dictionaries: index (normal) dictionaries and tree dictionaries. The vast majority of dictionaries for StarDict you may find on Internet are of the index type. In fact, you hardly find a tree dictionary for StarDict. An index dictionary contain a list of words in one file and corresponding definitions in other file. That index of words is the reason we call it an index dictionary. An index dictionary may contain other data as well. In a tree dictionary data are organized in a tree that is why it name. StarDict searches index and tree dictionaries in different directories.

Almost all files constituting a dictionary are binary. It does not make sense to open them in a text editor. A notable exception is .ifo file, it contains dictionary description.

### Index dictionary files and directories

dictname.ifo

  Information about the dictionary. This a text file, you may open it in a text editor. You may found useful information here like dictionary description, author name and e-mail.

dictname.idx or dictname.idx.gz

  Index of words available in the dictionary.

dictname.dict or dictname.dict.dz

  Main content of the dictionary ‒ articles.

dictname.syn

  Index of synonyms. Optional.

dictname.idx.oft

  Cache for the index file. This file is created by StarDict to speedup dictionaries loading. You should not redistribute this file.

dictname.syn.oft

  Cache for the synonyms file. This file is created by StarDict to speedup dictionaries loading. You should not redistribute this file.

dictname.idx.clt

  Collation file for the index file. This file is created by StarDict when you use collations to modify sorting order of words. You should not redistribute this file.

dictname.syn.clt

  Collation file for the synonyms file. This file is created by StarDict when you use collations to modify sorting order of words. You should not redistribute this file.

res.rifo, res.ridx, res.rdic

  Files of resource database. It contains resources like images, sound and video files used in the dictionary. Optional.

res.ridx.oft

  Cache for the resource index file. This file is created by StarDict to speedup resource database loading. You should not redistribute this file.

res

  A directory containing dictionary resources. This is alternative to res.rifo, res.ridx, res.rdic collection of files. Optional.

### Tree dictionary files

dictname.ifo

  Information about the dictionary. This a text file, you may open it in a text editor. You may found useful information here like dictionary description, author name and e-mail.

dictname.tdx or dictname.tdx.gz

  A word list forming a tree.

dictname.dict or dictname.dict.dz

  Main content of the dictionary ‒ articles.

### Directories

This section describes directories where StarDict searches dictionaries.

Under Unix, StarDict searches ~/.stardict/dic and /usr/share/stardict/dic directories for index dictionaries and ~/.stardict/treedict and /usr/share/stardict/treedict directories for tree dictionaries. If you build StarDict with non-standard prefix, the application searches a pair of additional directories for dictionaries. It checks $(datadir)/dic for index dictionaries and $(datadir)/treedict for tree dictionaries. Here $(datadir) is an autoconf directory variable.

Under Windows, StarDict searches C:\Program Files\StarDict\dic for index dictionaries and C:\Program Files\StarDict\treedict for tree dictionaries, assuming that StarDict was installed into C:\Program Files\StarDict. If you've install StarDict into a different directory, replace C:\Program Files\StarDict with real installation path.

Under Windows, you may overwrite $data_dir variable, see StarDict directories. By default it matches the StarDict installation directory. In this case StarDict will search $data_dir\dic for index dictionaries and $data_dir\treedict for tree dictionaries.

All directories are processed recusively.