> ## Documentation Index
> Fetch the complete documentation index at: https://docs.abbyy.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Working with Dictionaries
C# samples are applicable only to FRE for Windows.
ABBYY FineReader Engine allows you to attach dictionaries of various types to a recognition language, which greatly improves recognition quality.
## Dictionary types
Dictionaries may be of several types:
This type of dictionary is already provided for the predefined languages that have built-in dictionary support (see the comments in the [list of predefined languages](/fine-reader/engine/specifications/predefined-languages)). Additionally, for some languages, there are dictionaries of specialized terms (e.g., medical and law) packed in the .zmd archive. Standard dictionaries are represented by three or four files. They have names that are usually the same as the full or short name of the language and an .amd, .amm, .amt, or .ame extension. Files with .amd, .amm, and .amt extensions are always present. They are stored in the following folders and cannot be changed: [Data/ExtendedDictionaries](/fine-reader/engine/distribution/distribution-windows/distribution-kit#dictionaries) (Linux), [Resources/ExtendedDictionaries](/fine-reader/engine/distribution/distribution-windows/distribution-kit#dictionaries) (macOS), [Data\ExtendedDictionaries](/fine-reader/engine/distribution/distribution-windows/distribution-kit#dictionaries) (Windows).
No .ame files are provided with ABBYY FineReader Engine: this is a format for storing a dictionary extension, i.e., words added to the dictionary by the user. You can create a dictionary extension in ABBYY FineReader, where it is called user dictionary, and then copy the created file to the folder mentioned above under the ABBYY FineReader Engine folder (or you may specify the full path to it in [ILanguageDatabase::DictionaryExtensionsPath](/fine-reader/engine/api-reference/language-related-objects/languagedatabase#dictionaryextensionspath) property). ABBYY FineReader stores the extensions of standard dictionaries in %appdata%\ABBYY\FineReader\15\FineReaderShell\UserDictionaries. Dictionary extensions can be edited in ABBYY FineReader Engine using [ILanguageDatabase::OpenDictionaryExtension](/fine-reader/engine/api-reference/language-related-objects/languagedatabase/opendictionaryextension-method) method.
This dictionary type is described by the [StandardDictionaryDescription](/fine-reader/engine/api-reference/language-related-objects/standarddictionarydescription) object.
Can be created using the [Dictionary](/fine-reader/engine/api-reference/language-related-objects/dictionary) object. The Dictionary object allows you to add and remove words using its methods.
In Windows, the Dictionary object also allows you to edit the dictionary with the help of the [Dictionary dialog box](/fine-reader/engine/api-reference/language-related-objects/dictionary/edit-method/dictionary-dialog-box). This dialog box allows you to import any text file in Windows ANSI and Unicode encoding (the only requirement is that words must be separated by spaces or other non-alphabetic characters).
This dictionary type is described by the [UserDictionaryDescription](/fine-reader/engine/api-reference/language-related-objects/userdictionarydescription) object.
The user dictionary in FineReader Engine has .amd file format and can be created for any language. It can take place of the standard dictionary for languages that do not have dictionary support. The user dictionary of ABBYY FineReader is called dictionary extension in FineReader Engine; it is a .ame file and can be created only for the languages with dictionary support, as an extension of standard dictionary for that language.
Specifies the rules that define what words are allowed in a language and what words are not allowed.
This dictionary type is described by the [RegExpDictionaryDescription](/fine-reader/engine/api-reference/language-related-objects/regexpdictionarydescription) object.
Allows you to implement your own type of dictionary. This dictionary is represented as the [IExternalDictionary](/fine-reader/engine/api-reference/language-related-objects/iexternaldictionary-interface) interface, which is implemented on the client-side. Guidelines for external dictionary creation you can find in the description of this interface.
This dictionary type is described by the [ExternalDictionaryDescription](/fine-reader/engine/api-reference/language-related-objects/externaldictionarydescription) object.
ABBYY FineReader Engine provides a [DictionaryDescription](/fine-reader/engine/api-reference/language-related-objects/dictionarydescription) object for describing all types of dictionaries. This is the basic object from which the descriptions of different dictionary types are inherited.
All these dictionary descriptions are elements of the [DictionaryDescriptions](/fine-reader/engine/api-reference/language-related-objects/dictionarydescriptions) collection.
## Creating a dictionary description
To create dictionary descriptions, the [AddNew](/fine-reader/engine/api-reference/language-related-objects/dictionarydescriptions/addnew-method) method of the DictionaryDescriptions object is used. This method returns a reference to the DictionaryDescription object. To obtain a reference to the object describing the corresponding dictionary type, use the [GetAsStandardDictionaryDescription](/fine-reader/engine/api-reference/language-related-objects/dictionarydescription/getasstandarddictionarydescription-method), [GetAsUserDictionaryDescription](/fine-reader/engine/api-reference/language-related-objects/dictionarydescription/getasuserdictionarydescription-method), [GetAsRegExpDictionaryDescription](/fine-reader/engine/api-reference/language-related-objects/dictionarydescription/getasregexpdictionarydescription-method), [GetAsExternalDictionaryDescription](/fine-reader/engine/api-reference/language-related-objects/dictionarydescription/getasexternaldictionarydescription-method) methods of the DictionaryDescription object.
## Dictionary properties
For each dictionary, the identification property of the dictionary must be specified:
* For a standard dictionary (StandardDictionaryDescription), specify its LanguageId property, which defines the ID of the language.
* For a user dictionary (UserDictionaryDescription), specify its FileName property, which provides the path to the user dictionary.
* For a regular-expression-based dictionary (RegExpDictionaryDescription), use the [SetText](/fine-reader/engine/api-reference/language-related-objects/regexpdictionarydescription/settext-method) method to specify the regular expression. See [Working with ABBYY FineReader Engine Regular Expressions](/fine-reader/engine/guided-tour/advanced-techniques/working-with-regular-expressions).
* For an external dictionary (ExternalDictionaryDescription), use the [SetDictionary](/fine-reader/engine/api-reference/language-related-objects/externaldictionarydescription/setdictionary-method) method to specify the dictionary.
All dictionary types are assigned a weight. The weight of a dictionary affects the weight of words from the given dictionary when they are detected during recognition. The weight parameter is a percentage and must be non-negative. A weight of 0 does not automatically mean that there is no such dictionary. Weights of more than 100 percent are allowed, but the user must be very careful when using such parameters. The weight is specified in the [IDictionaryDescription::Weight](/fine-reader/engine/api-reference/language-related-objects/dictionarydescription#weight) property and is set to 100 by default.
Standard dictionaries also have a [CanUseTrigrams](/fine-reader/engine/api-reference/language-related-objects/standarddictionarydescription#canusetrigrams) option which allows or forbids the program to use trigrams built on the basis of the selected dictionary. Trigrams are combinations of three letters. Not all of these combinations occur in real words. A word with a non-dictionary trigram is very likely to be unpronounceable. Trigrams are used to cut off unreliable words. We recommend enabling trigrams for "general" standard dictionaries and disabling them for dictionaries of terms.
## Dictionaries of a recognition language
A text recognition language (the [TextLanguage](/fine-reader/engine/api-reference/language-related-objects/textlanguage) object) can have both dictionaries containing words of the language and dictionaries with prohibited words. The first ones are specified for each [basic recognition language](/fine-reader/engine/api-reference/language-related-objects/baselanguage) of the text language and are accessible via the [IBaseLanguage::DictionaryDescriptions](/fine-reader/engine/api-reference/language-related-objects/baselanguage#dictionarydescriptions) property. A base language may have no dictionary attached to it. The prohibiting dictionaries are attached directly to the text recognition language through the [ITextLanguage::ProhibitingDictionaries](/fine-reader/engine/api-reference/language-related-objects/textlanguage#prohibitingdictionaries) property.
If you want only the dictionary words to be allowed during recognition, set the [IBaseLanguage::AllowWordsFromDictionaryOnly](/fine-reader/engine/api-reference/language-related-objects/baselanguage#allowwordsfromdictionaryonly) property to TRUE. In this case, a word that is not found in the dictionary of the base language can appear in the recognized text only if ABBYY FineReader Engine found no dictionary variants.
## How to attach a dictionary to a recognition language
1. Create a [TextLanguage](/fine-reader/engine/api-reference/language-related-objects/textlanguage) object using one of the available methods (e.g., the [CreateTextLanguage](/fine-reader/engine/api-reference/language-related-objects/languagedatabase/createtextlanguage-method) method of the [LanguageDatabase](/fine-reader/engine/api-reference/language-related-objects/languagedatabase) object).
2. Obtain the collection of base languages of the new text language (use the [BaseLanguages](/fine-reader/engine/api-reference/language-related-objects/textlanguage#baselanguages) property).
3. Create a new [BaseLanguage](/fine-reader/engine/api-reference/language-related-objects/baselanguage) object and add it to a collection of base languages.
4. Obtain the collection of dictionary descriptions of the new base language (the [DictionaryDescriptions](/fine-reader/engine/api-reference/language-related-objects/baselanguage#dictionarydescriptions) property).
5. Create a dictionary description and add it to the collection of dictionary descriptions of the base language. Use the [AddNew](/fine-reader/engine/api-reference/language-related-objects/dictionarydescriptions/addnew-method) method of the [DictionaryDescriptions](/fine-reader/engine/api-reference/language-related-objects/dictionarydescriptions) collection.
You can create several dictionaries of different types and add them to the [DictionaryDescriptions](/fine-reader/engine/api-reference/language-related-objects/dictionarydescriptions) collection of one base recognition language.
6. \[Optional] Specify the weight of the created dictionary.
7. Specify the identification property of the dictionary: the LanguageId property for a standard dictionary, the FileName property for a user dictionary, call the IRegExpDictionaryDescription::SetText method for a regular-expression-based dictionary or call the IExternalDictionaryDescription::SetDictionary method for an external dictionary.
8. \[Optional] Specify other properties of the [BaseLanguage](/fine-reader/engine/api-reference/language-related-objects/baselanguage) object.
9. \[Optional] Set the prohibiting dictionaries using the ProhibitingDictionaries property of the [TextLanguage](/fine-reader/engine/api-reference/language-related-objects/textlanguage) object.
10. Assign the created [TextLanguage](/fine-reader/engine/api-reference/language-related-objects/textlanguage) object to the TextLanguage property of the [RecognizerParams](/fine-reader/engine/api-reference/parameter-objects/preprocessing-analysis-recognition-and-synthesis-parameters/recognizerparams) object.
To implement these steps in Windows, see the code samples below.
```cpp theme={null}
// Global ABBYY FineReader Engine object
FREngine::IEnginePtr Engine;
// A LanguageDatabase object
FREngine::ILanguageDatabasePtr languageDatabase;
...
// Create a TextLanguage object and receive its collection of base languages
FREngine::ITextLanguagePtr pTextLang = languageDatabase->CreateTextLanguage();
FREngine::IBaseLanguagesPtr pBaseLangCollection = pTextLang->BaseLanguages;
// Create a BaseLanguage object and receive its collection of dictionary descriptions
FREngine::IBaseLanguagePtr pBaseLang = pBaseLangCollection->AddNew();
pBaseLang->InternalName = L"SampleBaseLanguage";
pBaseLang->PutLetterSet( FREngine::BLLS_Alphabet, L"abc123" );
FREngine::IDictionaryDescriptionsPtr pDictDescCollection = pBaseLang->DictionaryDescriptions;
// Create a standard dictionary description and add it to the collection
FREngine::IDictionaryDescriptionPtr pDicDescription =
pDictDescCollection->AddNew( FREngine::DT_SystemDictionary);
// [optional] Specify the weight of the created dictionary
pDicDescription->Weight = 100;
// Specify the identification property of the dictionary
FREngine::IStandardDictionaryDescriptionPtr pStandardDic = pDicDescription->GetAsStandardDictionaryDescription();
pStandardDic->LanguageId = FREngine::LI_EnglishUnitedStates;
// [optional] Specify other properties of the BaseLanguage base language
pBaseLang->AllowWordsFromDictionaryOnly = VARIANT_TRUE;
// Create a RecognizerParams object
FREngine::IRecognizerParamsPtr pParams = Engine->CreateRecognizerParams();
// Assign the created TextLanguage object to the TextLanguage property
pParams->TextLanguage = pTextLang;
...
```
```csharp theme={null}
// Global ABBYY FineReader Engine object
FREngine.IEngine engine;
// A LanguageDatabase object
FREngine.ILanguageDatabase languageDatabase;
...
// Create a TextLanguage object and receive its collection of base languages
FREngine.ITextLanguage TextLang = languageDatabase.CreateTextLanguage();
FREngine.IBaseLanguages BaseLangCollection = TextLang.BaseLanguages;
// Create a BaseLanguage object and receive its collection of dictionary descriptions
FREngine.IBaseLanguage BaseLang = BaseLangCollection.AddNew();
BaseLang.InternalName = "SampleBaseLanguage";
BaseLang.set_LetterSet( FREngine.BaseLanguageLetterSetEnum.BLLS_Alphabet, "abc123" );
FREngine.IDictionaryDescriptions DictDescCollection = BaseLang.DictionaryDescriptions;
// Create a standard dictionary description and add it to the collection
FREngine.IDictionaryDescription DicDescription = DictDescCollection.AddNew( FREngine.DictionaryTypeEnum.DT_SystemDictionary );
// [optional] Specify the weight of the created dictionary
DicDescription.Weight = 100;
// Specify the identification property of the dictionary
FREngine.IStandardDictionaryDescription StandardDic = DicDescription.GetAsStandardDictionaryDescription();
StandardDic.LanguageId = FREngine.LanguageIdEnum.LI_EnglishUnitedStates;
// [optional] Specify other properties of the BaseLanguage base language
BaseLang.AllowWordsFromDictionaryOnly = true;
// Create a RecognizerParams object
FREngine.IRecognizerParams recParams = engine.CreateRecognizerParams();
// Assign the created TextLanguage object to the TextLanguage property
recParams.TextLanguage = TextLang;
...
```
## Cache dictionary
A cache dictionary is a small dictionary (about a hundred words) that can be changed easily during processing. Cache dictionaries can be used when it is possible to select a dictionary more precisely, e.g., if you find new information about the document during processing. Such dictionaries are suitable for field-level recognition.
For example, suppose there are two fields on a form you need to recognize: the name of a city and the name of a street. You have recognized the name of the city, and you have the list of streets in this city. In this case, you may load the appropriate cache dictionary with the street names and thus recognize the name of the street more quickly and accurately.
ABBYY FineReader Engine provides the [AddWordsToCacheDictionary](/fine-reader/engine/api-reference/document-related-objects/frpage/addwordstocachedictionary-method), [AddWordToCacheDictionary](/fine-reader/engine/api-reference/document-related-objects/frpage/addwordtocachedictionary-method), and [CleanCacheDictionary](/fine-reader/engine/api-reference/document-related-objects/frpage/cleancachedictionary-method) methods of the [FRPage](/fine-reader/engine/api-reference/document-related-objects/frpage) object for working with cache dictionaries.
To use the cache dictionary, you should set the [IEngine::AutoCleanRecognizerSession](/fine-reader/engine/api-reference/engine-object-iengine-interface/properties#autocleanrecognizersession) property to FALSE. The AutoCleanRecognizerSession property is set to TRUE by default, which means that FineReader Engine cleans its recognition session after recognition of each page, in which case the cache dictionary is cleaned too. To prevent accidental destruction of user data, FineReader Engine prohibits using of cache dictionaries in this mode. If you use the cache dictionary, it is your concern to clean the recognition session manually by calling the [IEngine::CleanRecognizerSession](/fine-reader/engine/api-reference/engine-object-iengine-interface/supplementary-methods/cleanrecognizersession-method) method when necessary. See the description of the method to find out when it is necessary to clean the recognition session.
## See also
[Working with Languages](/fine-reader/engine/guided-tour/advanced-techniques/working-with-languages)
[Recognizing Words with Spaces](/fine-reader/engine/guided-tour/advanced-techniques/recognizing-words-with-spaces)