diff --git a/apiconcepts/terminology/adding_terms.md b/apiconcepts/terminology/adding_terms.md index 1ebb014789..2bb5ee3741 100644 --- a/apiconcepts/terminology/adding_terms.md +++ b/apiconcepts/terminology/adding_terms.md @@ -1,43 +1,50 @@ -Adding Terms -===== -You can configure your custom terminology provider to support adding and editing of terminology entries. Learn how to implement some simplified functionality for adding source and target terms to your delimited text list. +# Adding Terms +Configure your custom terminology provider to support adding and editing terminology entries. This article explains simplified functionality for adding source and target terms to a delimited text list. -In Var:ProductName, you can add source and target terms on the fly by marking them in the Editor and by then clicking either the **Add New Term** button, or the **Quick Add New Term** button. +In **Var:ProductName**, you can add source and target terms on the fly by marking them in the Editor and then clicking either **Add New Term** or **Quick Add New Term**. -The difference between these two buttons in the standard, MultiTerm-based implementation of Var:ProductName is that **Add New Term** does not immediately save the term pair to the termbase, but opens up an editor control in the **Termbase Viewer** window that allows you to make changes to the terms before saving them. **Quick Add New Term** adds the term pair directly to the terminology source and displays the newly-created entry in the **Termbase Viewer** window. Our simplified implementation will not offer any editing function. This means that the same thing will happen in our implementation, regardless of whether you click Add New Term or Quick Add New Term. +In the standard, MultiTerm-based implementation of **Var:ProductName**: -Open the **MyTerminologyProviderViewerWinFormsUI.cs** class and go to the **AddTerm()** function. Var:ProductName passes the currently selected source and target term to this function through the **source** and **target** string parameters. We then implement the following functionality, which works like this: +* **Add New Term** opens an editor control in the **Termbase Viewer** window so you can modify terms before saving. +* **Quick Add New Term** adds the term pair directly to the terminology source and displays the newly created entry in the **Termbase Viewer** window. -* Open the glossary text file. -* Loop to the end of the text file, while counting the lines to determine the next entry id. -* Insert the new source and target term (with empty definition). -* Display the newly-created entry in the Internet Explorer control of the **Termbase Viewer** window. +In this simplified implementation, no editing function is provided, so both buttons perform the same action. + +To implement this behavior: + +1. Open the **MyTerminologyProviderViewerWinFormsUI.cs** class and go to the **AddTerm()** function. +2. **Var:ProductName** passes the selected source and target terms through the **source** and **target** string parameters. +3. Implement the following steps: + * Open the glossary text file. + * Loop to the end of the text file while counting lines to determine the next entry ID. + * Insert the new source and target terms (with an empty definition). + * Display the newly created entry in the Internet Explorer control of the **Termbase Viewer** window. # [Adding Terms Functionality](#tab/tabid-1) [!code-csharp[MyTerminologyProvider](code_samples/MyTerminologyProviderViewerWinFormsUI.cs#L66-L102)] *** -When a new source/target term pair has been added, the following will, for example, be displayed in the **Termbase Viewer** window: +When a new source/target term pair is added, the following appears in the **Termbase Viewer** window: -You can also implement your terminology provider to support editing. However, in this simplified example, we will not actually add any editing functionality. This would require us to implement an editing control in the **Termbase Viewer** window. All we are doing for the moment is to output a message in the **AddAndEditTerm()** function of the **MyTerminologyProviderViewerWinFormsUI.cs** class: +You can also implement your terminology provider to support editing. However, this simplified example does not add editing functionality. Supporting editing would require an editing control in the **Termbase Viewer** window. For now, the **AddAndEditTerm()** function in the **MyTerminologyProviderViewerWinFormsUI.cs** class outputs a message: # [Adding and Editing Terms](#tab/tabid-2) [!code-csharp[MyTerminologyProviderViewerWinFormsUI](code_samples/MyTerminologyProviderViewerWinFormsUI.cs#L59-L64)] *** -When you try to add a term that has already been added, Var:ProductName throws the following message that prompts you to: +If you try to add a term that already exists, **Var:ProductName** displays a message that prompts you to: * Edit the entry by clicking **Yes**. -* Add the term again, thus risking creating a duplicate entry by clicking **No**. -* Abort the entire term add operation with **Cancel**. +* Add the term again, risking a duplicate entry, by clicking **No**. +* Cancel the entire add operation by clicking **Cancel**. -If you click **Yes** to edit the entry, the following message box will be displayed in our implementation and the **Termbase Viewer** window remains empty. In a 'real' implementation, the entry content will be shown in an edit control where you can still edit it. +If you click **Yes** to edit the entry, the following message box is displayed in this implementation and the **Termbase Viewer** window remains empty. In a real implementation, the entry content is shown in an edit control where you can still modify it. diff --git a/apiconcepts/terminology/displaying_entry_content.md b/apiconcepts/terminology/displaying_entry_content.md index 734e35c22e..189f9a7308 100644 --- a/apiconcepts/terminology/displaying_entry_content.md +++ b/apiconcepts/terminology/displaying_entry_content.md @@ -1,31 +1,34 @@ -Displaying Entry Content -==== -The full content of an entry can be displayed in the **Termbase Viewer** window. Learn how to show the content of a line of your glossary file in Var:ProductName. +# Displaying Entry Content -When you right-click a term in the **Term Recognition** or in the **Termbase Search** window, you can use the command **View term details** to show the full entry content in the **Termbase Viewer** window. +Display the full content of an entry in the **Termbase Viewer** window. This guide explains how to show the content of a glossary file line in **Var:ProductName**. -We need to add an Internet Explorer control in which we can display the entry content in HTML format. To do this, add a user control to your project and call it **TermProviderControl.cs**, for example. Add an Internet Explorer control to it: +Right-click a term in the **Term Recognition** or **Termbase Search** window and select **View term details** to display the full entry content in the **Termbase Viewer** window. + +1. Add an Internet Explorer control to display entry content in HTML format: + - Create a user control in your project named **TermProviderControl.cs**. + - Add an Internet Explorer control to the user control. -Go to the **MyTerminologyProviderViewerWinFormsUI.cs** class and declare the following term controller object: +2. Open the **MyTerminologyProviderViewerWinFormsUI.cs** class. +3. Declare the following term controller object: # [The Term Controller Object](#tab/tabid-1) [!code-csharp[MyTerminologyProvider](code_samples/MyTerminologyProvider.cs#L18-L19)] *** -Modify the following **TermProviderControl** property (which is implemented by the **ITerminologyProviderViewerWinFormsUI** interface) as shown below to create and return the control element: +4. Modify the **TermProviderControl** property (implemented by the **ITerminologyProviderViewerWinFormsUI** interface) as shown below to create and return the control element: # [Returning the Controller Element](#tab/tabid-2) [!code-csharp[MyTerminologyProvider](code_samples/MyTerminologyProvider.cs#L21-L30)] *** -When the you right-click a term and call up the command **View term details**, the corresponding entry content should be shown in the newly-created control. +5. When you right-click a term and select **View term details**, the corresponding entry content should appear in the newly created control. -You need to modify the **JumpToTerm()** method as shown below. Var:ProductName passes the ID of the selected entry, which you can use to: +6. Modify the **JumpToTerm()** method as shown below. **Var:ProductName** passes the ID of the selected entry, which you can use to: * Retrieve the corresponding line from the glossary text file. -* Parse the line and generate the HTML output for the Internet Explorer controller object. +* Parse the line and generate HTML output for the Internet Explorer control. # [Jumping to a Term](#tab/tabid-3) [!code-csharp[MyTerminologyProvider](code_samples/MyTerminologyProviderViewerWinFormsUI.cs#L123-L161)] diff --git a/apiconcepts/terminology/images/general_01_add_tb.jpg b/apiconcepts/terminology/images/general_01_add_tb.jpg index 0c9c3178f2..d2b2d1020e 100644 Binary files a/apiconcepts/terminology/images/general_01_add_tb.jpg and b/apiconcepts/terminology/images/general_01_add_tb.jpg differ diff --git a/apiconcepts/terminology/images/general_02_add_tb.jpg b/apiconcepts/terminology/images/general_02_add_tb.jpg index c71438ced3..fc17ae7f5c 100644 Binary files a/apiconcepts/terminology/images/general_02_add_tb.jpg and b/apiconcepts/terminology/images/general_02_add_tb.jpg differ diff --git a/apiconcepts/terminology/images/general_03_add_tb.jpg b/apiconcepts/terminology/images/general_03_add_tb.jpg index bdaaccaa47..9f89110e20 100644 Binary files a/apiconcepts/terminology/images/general_03_add_tb.jpg and b/apiconcepts/terminology/images/general_03_add_tb.jpg differ diff --git a/apiconcepts/terminology/images/general_05_term_rec.jpg b/apiconcepts/terminology/images/general_05_term_rec.jpg index 545826bcaf..f870930057 100644 Binary files a/apiconcepts/terminology/images/general_05_term_rec.jpg and b/apiconcepts/terminology/images/general_05_term_rec.jpg differ diff --git a/apiconcepts/terminology/images/general_06_term_rec.jpg b/apiconcepts/terminology/images/general_06_term_rec.jpg index bb754c8212..8982d53097 100644 Binary files a/apiconcepts/terminology/images/general_06_term_rec.jpg and b/apiconcepts/terminology/images/general_06_term_rec.jpg differ diff --git a/apiconcepts/terminology/images/general_07_search.jpg b/apiconcepts/terminology/images/general_07_search.jpg index e91ce7cc7c..dbc2aa20b6 100644 Binary files a/apiconcepts/terminology/images/general_07_search.jpg and b/apiconcepts/terminology/images/general_07_search.jpg differ diff --git a/apiconcepts/terminology/images/general_08_search.jpg b/apiconcepts/terminology/images/general_08_search.jpg index 9c699b20a9..977d7ce422 100644 Binary files a/apiconcepts/terminology/images/general_08_search.jpg and b/apiconcepts/terminology/images/general_08_search.jpg differ diff --git a/apiconcepts/terminology/images/general_10_tb_viewer.jpg b/apiconcepts/terminology/images/general_10_tb_viewer.jpg index c4ece86da9..8fcc080a87 100644 Binary files a/apiconcepts/terminology/images/general_10_tb_viewer.jpg and b/apiconcepts/terminology/images/general_10_tb_viewer.jpg differ diff --git a/apiconcepts/terminology/images/general_11_add_term.jpg b/apiconcepts/terminology/images/general_11_add_term.jpg index 09486a18cf..9ab6131eed 100644 Binary files a/apiconcepts/terminology/images/general_11_add_term.jpg and b/apiconcepts/terminology/images/general_11_add_term.jpg differ diff --git a/apiconcepts/terminology/images/search_settings.jpg b/apiconcepts/terminology/images/search_settings.jpg index 755a39f8d4..8dc59f1611 100644 Binary files a/apiconcepts/terminology/images/search_settings.jpg and b/apiconcepts/terminology/images/search_settings.jpg differ diff --git a/apiconcepts/terminology/overview.md b/apiconcepts/terminology/overview.md index 0c22220736..1d57860346 100644 --- a/apiconcepts/terminology/overview.md +++ b/apiconcepts/terminology/overview.md @@ -1,41 +1,36 @@ -Terminology Overview -========= +# Terminology Overview -This section gives an overview of what terminology providers in Var:ProductName are and how they are used. +This section provides an overview of terminology providers in Var:ProductName and their usage. -What is a Terminology Provider? -------- +## What is a Terminology Provider? -A terminology provider plug-in enables Var:ProductName to smoothly integrate terminology sources, such as termbases and glossaries. These terminology sources can then be used to: +A terminology provider plug-in allows Var:ProductName to integrate terminology sources, such as termbases and glossaries. These sources can be used to: * look up terminology by searching for a specific string that the user enters, similar to an electronic dictionary lookup * search a sentence for any known terminology * add term entries to the terminology source * edit terminology in the terminology source -Selecting the Terminology Provider -------- +## Selecting the Terminology Provider When you implement a custom terminology provider, you need to consider a number of features that such plug-ins typically have. First, you select the terminology provider in Var:ProductName. By default, Var:ProductName features two standard terminology providers for connecting to MultiTerm termbase files or MultiTerm server termbases: -The name of your plug-in will have to feature in the list of terminology providers. Your implementation would then have to call up a user interface in which the terminology source (e.g. a glossary text file) can be selected. In case of a file-based resource, it would be an **Open File** dialogue box, e.g.: +Your plug-in name must appear in the list of terminology providers. The implementation should display a user interface where the terminology source (e.g. a glossary text file) can be selected. For file-based resources, this would typically be an **Open File** dialogue box, e.g.: -Selecting the Terminology Resource languages -------- +## Selecting the Terminology Resource Languages A terminology resource typically has terms in several languages. These languages can be named in various ways. For example, the language 'English' might be called 'ENG', 'Anglais', 'Englisch', 'Inglés', etc. When selecting a terminology resource, Var:ProductName assigns the languages of the terminology resource to the corresponding project language in Var:ProductName. This is done in the background using locales, e.g. 'en-US' for US English, as the language labels used in the terminology resource cannot always be predicted. If Var:ProductName fails to assign the correct languages, you can manually assign the correct language using a dropdown list in Var:ProductName, which shows all the languages offered by the terminology resource, e.g.: -This is also why, after selecting a terminology resource, Var:ProductName prompts you to make sure that the correct languages of the terminology resource have been picked, i.e.: +After selecting a terminology resource, Var:ProductName prompts you to confirm that the correct languages have been picked, i.e.: -Active Terminology Recognition -------- +## Active Terminology Recognition When the terminology provider is selected, it will search search the segments in Var:ProductName for any known terminology. It will mark the recognized term (e.g. *photo printer*) with a red line, and display the term and its translation in the **Term Recognition** window, e.g.: @@ -47,8 +42,7 @@ You can insert the target term into the target segment by typing the first lette By default, terms in the source segment should only be recognized when there is a target equivalent, as a source term without a translation is normally of no use during translation. -Search Settings -------- +## Search Settings Users can switch to the **Termbase Search** window and enter search terms manually. The window will then display any hits with source and target terms. @@ -57,22 +51,19 @@ You can also activate the **Fuzzy Search** option to make the search tolerant, s -The Termbase Viewer -------- +## The Termbase Viewer A terminology entry can have more than just the source and the target term. It can have additional information, such as definitions, notes, remarks, etc. As the **Term Recognition** and **Termbase Search** window by default only show the source and target terms, you can view any further information in the **Termbase Viewer** window, which you can call up through the **View term details** command: Depending on the nature and content of the terminology resources supported by your custom implementation, this window can show different things. For a MultiTerm termbase, it shows a MultiTerm entry (see screenshot above), for an MS Excel glossary, it can show, for example, the terminology in a tabular format. The display control used here will be part of your custom implementation. In this window, you can also implement editing functionality, so that users can modify the content of the terminology resource. Your custom plug-in can feature editing functionality or not. -Adding Terminology ------- +## Adding Terminology The implementation can also be made to support adding term pairs. In this case, you select the source and target term, and use the corresponding command in Var:ProductName to add the term pair to the terminology resource. You can programmatically retrieve the source and target string, and then add term pair to the terminology resource. -Term Search Settings ------- +## Term Search Settings Var:ProductName features a page through which you can configure various search settings. For example, you can decide whether or not source terms without any target term will be shown to the users. These settings are passed through the terminology provider interface and can be used in your custom term provider implementation. diff --git a/apiconcepts/terminology/searching_terms.md b/apiconcepts/terminology/searching_terms.md index 7a6daec1ac..3873db80f1 100644 --- a/apiconcepts/terminology/searching_terms.md +++ b/apiconcepts/terminology/searching_terms.md @@ -1,56 +1,58 @@ -Searching Terms -==== -Searching the terminology source through your term provider is arguably the most important function of your implementation. A term provider can still be useful without the editing function, but is of no use if no term look-up and term recognition functionality is available. +# Searching Terms +Searching the terminology source is a critical part of your term provider implementation. Editing can be optional, but term look-up and recognition are essential. -How to search and recognize terms ----- +## Searching and recognizing terms -When you click inside a segment in Var:ProductName, the segment is scanned for any terminology contained in the term resource. If terms are recognized, they are highlighted with a red line and displayed in the **Term Recognition** window: +1. Click inside a segment in **Var:ProductName**. The segment is scanned for terminology from the term resource. Recognized terms are highlighted with a red line and shown in the **Term Recognition** window: -You can also manually look up terms in the **Termbase Search** window: +2. You can also manually look up terms in the **Termbase Search** window: -How to implement the search functionality ------ -Open the **MyTerminologyProvider.cs** class and go to the **Search()** function (which is implemented by the **AbstractTerminologyProvider** interface). This function is called when you click inside a segment or launch a search in the Termbase Search window. Note that Var:ProductName passes a number of useful parameters: +## Implementing the search functionality +Open the **MyTerminologyProvider.cs** class and go to the **Search()** function (implemented by the **AbstractTerminologyProvider** interface). This function is called when you click inside a segment or launch a search in the **Termbase Search** window. **Var:ProductName** passes several useful parameters: -* **text**: the search string. When the user selects a segment in Var:ProductName, this will be the source segment text. When you launch a search manually, this will be the search string entered by you. -* **maxResultsCount**: the maximum number of hits to show, i.e. the search depth. -* **mode**: the search mode, i.e. fuzzy or normal. When selecting a segment in Var:ProductName, the mode is 'fuzzy' by default. When you do a manual lookup, the search mode is 'normal' by default (unless you clicked the **Fuzzy Search** button in the **Termbase Search**) window. -* **targetRequired**: boolean parameter that decides whether source terms without any target term should be shown or not. This parameter is controlled by you through the Var:ProductName UI. Depending on the value returned, your implementation needs to decide whether an entry without a target term should be displayed or not. +* **text**: the search string. When the user selects a segment in **Var:ProductName**, this is the source segment text. When you launch a manual search, this is the search string entered by the user. +* **maxResultsCount**: the maximum number of hits to show (search depth). +* **mode**: the search mode, either fuzzy or normal. When selecting a segment in **Var:ProductName**, the default mode is `fuzzy`. For manual lookup, the default mode is `normal` unless the **Fuzzy Search** button is selected in **Termbase Search**. +* **targetRequired**: a Boolean parameter that determines whether source terms without a target term should be shown. This parameter is controlled through the **Var:ProductName** UI. -Below is the page of the Var:ProductName UI where the user can, for example, determine the search depth or whether to display entries without a target term: +Below is the **Var:ProductName** UI page where users can determine search depth and whether to display entries without a target term: -The **Search** function returns a list of results to be displayed in Var:ProductName. In our simplified implementation, we loop through the glossary text file and look for any matching source terms. We assume that when the search mode is 'normal', we just check whether there are any source terms in the glossary that start with the search string. If the search string is fuzzy, we check whether there are any source terms in the glossary that are contained in the search string (i.e. in the segment). Of course, your 'real-life' implementation might have a much more sophisticated way of performing fuzzy searches than the **StartsWith()** or **Contains()** methods. For each search result object, you set the following properties: +The **Search()** function returns a list of results to display in **Var:ProductName**. In this simplified implementation, we loop through a glossary text file and look for matching source terms: -* **Text**: the source term, this will also be the term that is going to be highlighted with a red line in Var:ProductName. -* **Score**: the fuzzy score. In our simple implementation, we will simply set it to 100%. Depending on how you implement your fuzzy logic, you may assign different values. -* **Id**: the id of the entry that the search result needs to be associated with. Note that in Var:ProductName, you do not output the search result list, but rather the entries that you need to construct in a different function (see below). The search result objects are linked to the entries using the unique ID. This is also the reason why, in our implementation, every line in the glossary file is preceded with a unique number. +* In `normal` mode, check for source terms that start with the search string. +* In `fuzzy` mode, check for source terms contained in the search string (for example, in the segment text). + +A production implementation can use more advanced fuzzy search logic than **StartsWith()** or **Contains()**. For each search result object, set the following properties: + +* **Text**: the source term. This is also the term highlighted with a red line in **Var:ProductName**. +* **Score**: the fuzzy score. In this simplified implementation, set it to 100%. With custom fuzzy logic, you can assign other values. +* **Id**: the ID of the entry associated with the search result. In **Var:ProductName**, you do not output the search result list directly; instead, you output entries constructed in a separate function (see below). Search result objects are linked to entries through this unique ID. This is why each glossary line in this sample is preceded by a unique number. -The **Search()** function of our implementation would look as shown below: +The **Search()** function in our implementation would look like this: # [The Search Function](#tab/tabid-1) [!code-csharp[MyTerminologyProvider](code_samples/MyTerminologyProvider.cs#L142-L197)] *** -As mentioned above, the results list needs to be associated with the corresponding entry that you construct in the following helper function: +As noted above, the results list needs to be associated with the corresponding entry, which you construct in the following helper function: # [Constructing the Entry Content](#tab/tabid-2) [!code-csharp[MyTerminologyProvider](code_samples/MyTerminologyProvider.cs#L201-L237)] *** -Make sure that you add the following entry list object to the terminology provider class: +Add the following entry list object to the terminology provider class: # [The Entry List Object](#tab/tabid-3) [!code-csharp[MyTerminologyProvider](code_samples/MyTerminologyProvider.cs#L13-L15)] *** -Besides the **Search()** method, the term provider interface also calls the **GetEntry()** method, which then outputs the entry with the corresponding entry based on the id parameter: +Besides the **Search()** method, the term provider interface also calls the **GetEntry()** method, which outputs the corresponding entry based on the ID parameter: # [Getting the Entries](#tab/tabid-4) [!code-csharp[MyTerminologyProvider](code_samples/MyTerminologyProvider.cs#L90-L95)] diff --git a/apiconcepts/terminology/selecting_the_glossary_file.md b/apiconcepts/terminology/selecting_the_glossary_file.md index 626e4d311a..b163e8242c 100644 --- a/apiconcepts/terminology/selecting_the_glossary_file.md +++ b/apiconcepts/terminology/selecting_the_glossary_file.md @@ -1,29 +1,29 @@ -Selecting the Glossary File -===== -Learn how to select the delimited text file as a terminology provider for our implementation. +# Selecting the Glossary File -How to return the Term Provider URI, Name and Description -------- +Learn how to configure a delimited text file as a terminology provider in your implementation. + +## Returning the Term Provider URI, Name, and Description -Open the **MyTerminologyProvider.cs** class. Add the following public string variable which stores the delimited text file name: +Open the **MyTerminologyProvider.cs** class. +Add the following public string variable to store the delimited text file name: # [The Text File Name](#tab/tabid-1) [!code-csharp[MyTerminologyProvider](code_samples/MyTerminologyProvider.cs#L18-L19)] *** -Modify the following members to return the term provider URI, which includes the text file name: +Modify the following members to return the term provider URI, including the text file name: # [The Term Provider Uri](#tab/tabid-2) [!code-csharp[MyTerminologyProvider](code_samples/MyTerminologyProvider.cs#L79-L86)] *** -Then add the following member, which allows us to pass any settings to the term provider. In our implementation, this will be the path to the glossary file: +Add the following member to pass settings to the term provider. In this implementation, it specifies the glossary file path: # [The Term Provider Settings](#tab/tabid-3) [!code-csharp[MyTerminologyProvider](code_samples/MyTerminologyProvider.cs#L23-L27)] *** -Modify the two following members to return the term provider name and definition: +Modify the following members to return the term provider name and definition: # [The Term Provider Name and Definition](#tab/tabid-4) [!code-csharp[MyTerminologyProvider](code_samples/MyTerminologyProvider.cs#L63-L86)] @@ -41,7 +41,8 @@ Open the **MyTerminologyProviderWinFormsUI.cs** class and modify the **Browse()* [!code-csharp[MyTerminologyProviderWinFormsUI](code_samples/MyTerminologyProviderWinFormsUI.cs#L43-L58)] *** -Go to the **MyTerminologyProviderViewerWinFormsUI.cs** class and create a terminology provider object. Make sure that your provider object is initialized as follows: +Open the **MyTerminologyProviderViewerWinFormsUI.cs** class. +Create and initialize a terminology provider object as follows: # [The Term Provider Object](#tab/tabid-6) [!code-csharp[MyTerminologyProviderViewerWinFormsUI](code_samples/MyTerminologyProviderViewerWinFormsUI.cs#L12-L14)] @@ -55,14 +56,13 @@ Go to the **MyTerminologyProviderViewerWinFormsUI.cs** class and create a termin [!code-csharp[MyTerminologyProviderViewerWinFormsUI](code_samples/MyTerminologyProviderViewerWinFormsUI.cs#L34-L40)] *** -When selecting the text file, Var:ProductName will try to retrieve the languages from the terminology list. As we have not implemented the corresponding functionality yet, simply change the **GetLanguages()** method of the **MyTerminologyProvider.cs** class to return null for the moment. +When selecting the text file, Var:ProductName attempts to retrieve the languages from the terminology list. Because the corresponding functionality is not implemented yet, change the **GetLanguages()** method of the **MyTerminologyProvider.cs** class to return null for now. We will implement the required language retrieval functionality in the next chapter. -The Terminology Provider Factory Class ------ +## The Terminology Provider Factory Class -Open the class **MyTerminologyProviderFactory.cs** and create your term provider object as show below. Only then will Var:ProductName be able to access and display your provider in the UI: +Open the **MyTerminologyProviderFactory.cs** class and create your term provider object as shown below. Only then can Var:ProductName access and display your provider in the UI: # [Creating the Terminology Provider Object](#tab/tabid-9) [!code-csharp[MyTerminologyProviderFactory](code_samples/MyTerminologyProviderFactory.cs#L10-L15)] diff --git a/apiconcepts/terminology/setting_the_glossary_fields.md b/apiconcepts/terminology/setting_the_glossary_fields.md index b03e7a15c5..e284e25311 100644 --- a/apiconcepts/terminology/setting_the_glossary_fields.md +++ b/apiconcepts/terminology/setting_the_glossary_fields.md @@ -1,28 +1,27 @@ -Setting the Glossary Fields -==== -Apart from the actual source and target terms, a terminology source can also contain additional information such as a definition, a note or an example. Such additional information is referred to as 'descriptive fields'. +# Setting the Glossary Fields +In addition to source and target terms, a terminology source can include additional information such as definitions, notes, or examples. This additional information is referred to as **descriptive fields**. -How to declare the Definition Field ------ -Our glossary text file foresees a definition text in the forth column: +## Declaring the Definition Field +The glossary text file includes a definition in the fourth column: *1;photo printer;Fotodrucker;Peripheral device for creating hardcopies of pictures.* -Such information can also be shown when looking up terminology in Var:ProductName. When the descriptive field is declared, it can be selected in the Var:ProductName UI: +This information can also be shown when looking up terminology in **Var:ProductName**. When the descriptive field is declared, it can be selected in the **Var:ProductName** UI: -If you select to display the field, the content (the definition) is shown alongside the search results: +If you select the field for display, the content (for example, the definition) is shown alongside the search results: -Go to the **MyTerminologyProvider.cs** class and add the following member. It creates a descriptive field labelled 'Definition', which - in turn - can contain a text string. The example field has the field level 'Entry', i.e. it is not specific to a particular term or language. Instead, in the entry structure, it applies to the whole entry. +1. Go to the **MyTerminologyProvider.cs** class. +2. Add the following member. It creates a descriptive field labeled 'Definition' that can contain a text string. The example field has the field level 'Entry', meaning it is not specific to a particular term or language and instead applies to the whole entry. # [Setting the Glossary Descriptive Field](#tab/tabid-1) [!code-csharp[MyTerminologyProvider](code_samples/MyTerminologyProvider.cs#L43-L59)] *** -This function then needs to be called from the following property, which also calls the **GetLanguages()** method to create the full terminology source definition. The terminology source definition then becomes exposed in the Var:ProductName UI, where you can select what fields to display (see screenshot above). +3. Call this function from the following property, which also calls the **GetLanguages()** method to create the full terminology source definition. The terminology source definition is then exposed in the **Var:ProductName** UI, where you can select which fields to display (see screenshot above). # [Retrieving the Glossary Languages](#tab/tabid-2) [!code-csharp[MyTerminologyProvider](code_samples/MyTerminologyProvider.cs#L31-L39)] diff --git a/apiconcepts/terminology/setting_the_source_and_target_language.md b/apiconcepts/terminology/setting_the_source_and_target_language.md index c66d26382e..c5eabb3653 100644 --- a/apiconcepts/terminology/setting_the_source_and_target_language.md +++ b/apiconcepts/terminology/setting_the_source_and_target_language.md @@ -1,19 +1,22 @@ -Setting the Source and Target Language -==== -In this chapter you will learn how to retrieve and set the terminology provider source and target language. +# Setting the Source and Target Language -How to read the source and target language from the glossary file header ------ -Open the **MyTerminologyProvider.cs** class and go to the **GetLanguages()** function. Our implementation is based on the assumption that the first line in the text file contains the source and target language name and locale in the following form: *1;English,en-US;German,de-DE* +Learn how to retrieve and set the source and target languages for the terminology provider. -The source and target language are separated with a semicolon, the language name and locale are comma-separated. +## Reading the Source and Target Language from the Glossary File Header -Modify the **GetLanguages()** function as shown below. In this function, we parse the first line of the text file to retrieve the language label (for example 'English') and the locale (for example 'en-US'). Based on the locale, Var:ProductName assigns the glossary languages to the corresponding project language. After parsing the first line, the method creates two language objects which are added to the results list that the method returns. +1. Open the **MyTerminologyProvider.cs** class. +2. Go to the **GetLanguages()** function. This implementation assumes that the first line in the text file contains the source and target language name and locale in the following format: `1;English,en-US;German,de-DE`. + +> [!NOTE] +> The source and target languages are separated by a semicolon, and the language name and locale are comma-separated. + +3. Modify the **GetLanguages()** function as shown below. This function parses the first line of the text file to retrieve the language label (for example, 'English') and locale (for example, 'en-US'). Based on the locale, **Var:ProductName** assigns the glossary languages to the corresponding project language. After parsing the first line, the method creates two language objects and adds them to the results list that the method returns. # [Getting the Term Provider Languages](#tab/tabid-1) [!code-csharp[MyTerminologyProvider](code_samples/MyTerminologyProvider.cs#L106-L137)] *** -Note that you can add more than two languages. If Var:ProductName cannot assign the glossary languages automatically to the project languages, then you have to pick the correct glossary language manually from the dropdown list. +> [!TIP] +> You can add more than two languages. If **Var:ProductName** cannot automatically assign the glossary languages to the project languages, select the correct glossary language manually from the dropdown list. diff --git a/apiconcepts/terminology/settingup_the_visual_studio_project.md b/apiconcepts/terminology/settingup_the_visual_studio_project.md index 7919bd871e..a963233b5a 100644 --- a/apiconcepts/terminology/settingup_the_visual_studio_project.md +++ b/apiconcepts/terminology/settingup_the_visual_studio_project.md @@ -1,41 +1,36 @@ -Setting up the Visual Studio project -==================================== -To start setting up your batch task plug-in project, you need to generate a plug-in that can compile and that implements an empty batch task which can be seen and selected in Var:ProductName. For the moment, it will not contain any application logic, that is it will not actually perform a real task. +# Setting Up the Visual Studio Project +To set up your batch task plug-in project, generate a plug-in that compiles and implements an empty batch task that is visible and selectable in Var:ProductName. Initially, it will not include any application logic and will not perform a real task. -How to create the Visual Studio Project ----------------------------------- +## Creating the Visual Studio Project Assuming that you already installed the Var:ProductName SDK, open Var:VisualStudioEdition. You will see the following options when you create a new project: -With the above templates you can set up the skeleton of a Var:ProductName plug-in project. Select ** Terminology Provider (2021)**. +With these templates, you can set up the skeleton of a Var:ProductName plug-in project. Select **Terminology Provider (2021)**. -The Plug-in Skeleton -------------------------------------- -The plug-in template will add the required references to your project: +## Plug-in Skeleton +The plug-in template adds the required references to your project: -It will also add the following skeleton classes to your project: +It also adds the following skeleton classes to your project: -The Plug-in Declaration: ID, Name, Description --------------------------------- -Open the **MyTerminologyProviderFactory.cs** class. This class contains the plug-in declaration - the plug-in name and description that will be visible in Var:ProductName: +## Plug-in Declaration: ID, Name, Description +Open the **MyTerminologyProviderFactory.cs** class. This class contains the plug-in declaration, including the plug-in name and description visible in Var:ProductName: # [Creating the Term Provider](#tab/tabid-1) [!code-csharp[MyTerminologyProviderFactory](code_samples/MyTerminologyProviderFactory.cs#L10-L15)] *** -Give the terminology provider plug-in a new name, ID and description. Instead of doing it directly inside this class, enter the strings into the **PluginResources.resx** file: +Give the terminology provider plug-in a new name, ID, and description. Instead of defining these directly in this class, enter the strings into the **PluginResources.resx** file: Make sure the resource file access modifier is set to *public* and that you treat it as an *embedded* resource. -Open the **MyTerminologyProviderWinFormsUI.cs** class. This class controls how the plug-in manifests in the Var:ProductName UI. Change the **TypeName** and **TypeDescription** members as shown below. +Open the **MyTerminologyProviderWinFormsUI.cs** class. This class controls how the plug-in appears in the Var:ProductName UI. Change the **TypeName** and **TypeDescription** members as shown below. -How to build and load the plugin in Var:ProductName ---------------------------------------------- -Build the assembly. The project is automatically configured to build the plug-in file into the *Var:PluginPackedPath* folder. After you have built the plug-in, you should find the Terminology Provider1.sdlplugin file in the folder. Start Var:ProductName. As the plug-in is not yet officially signed by RWS, you will see the following message when starting the application: +## Building and Loading the Plug-in in Var:ProductName +Build the assembly. The project is automatically configured to build the plug-in file into the *Var:PluginPackedPath* folder. After building the plug-in, you should find the `Terminology Provider1.sdlplugin` file in that folder. Start Var:ProductName. As the plug-in is not yet officially signed by RWS, you will see the following message when starting the application: -For the moment, ignore this message and click **Yes** to make sure that Var:ProductName extracts the plug-in file. Once Var:ProductName is started, you should find the sub-folder *Terminology Provider1* under Var:PluginUnpackedPath . This sub-folder contains the unpacked plug-in assemblies. +For now, ignore this message and click **Yes** so that Var:ProductName extracts the plug-in file. Once Var:ProductName is started, you should find the sub-folder *Terminology Provider1* under Var:PluginUnpackedPath . This sub-folder contains the unpacked plug-in assemblies. > [!NOTE] > To officially sign the plugin, send the sdlplugin file to Var:AppSigningEmail. @@ -44,4 +39,4 @@ Open Var:ProductName and go to **File -> Options -> Language Pairs -> All Langua -You have now managed to make your terminology provider available in Var:ProductName. The plug-in does not perform any function yet. In the following pages we will provide functionality to the plug-in. +Your terminology provider is now available in Var:ProductName. The plug-in does not perform any function yet. In the following pages, you will add functionality to the plug-in. diff --git a/apiconcepts/terminology/what_our_sample_terminology_provider_should_do.md b/apiconcepts/terminology/what_our_sample_terminology_provider_should_do.md index e41feb4a6a..d5d9815ad7 100644 --- a/apiconcepts/terminology/what_our_sample_terminology_provider_should_do.md +++ b/apiconcepts/terminology/what_our_sample_terminology_provider_should_do.md @@ -1,9 +1,8 @@ -What our Sample Provider Should do -===== + # What Our Sample Provider Should Do -Learn how to develop a custom terminology provider by folowing the creation of a simplified sample project which uses the Terminology Provider API. + Learn how to develop a custom terminology provider by following the creation of a simplified sample project using the Terminology Provider API. -The example terminology provider will: + The example terminology provider includes the following features: * Use a semicolon-separated, two-column text file as a terminology resource. The lines in the glossary file have the following struture: line number (which corresponds to the entry number), the source term, the target term and a definition. For example, *2;photo printer;Fotodrucker;Peripheral device used create hardcopies of images*. * Select the terminology text file through a standard **Open File** dialog box. @@ -13,4 +12,5 @@ The example terminology provider will: * Add term pairs to the text file. * View the content of entries in an Internet Explorer control. -Note that our sample project only involves a highly simplified, 'Hello World'-style implementation to familiarize you with the basic concepts of terminology provider plug-ins. As terminology resource, we support only simple, two-column (source/target language) text files. The conceived search function is based on simple text searches with no stemming or fuzzy matching logic. +> [!NOTE] +> This sample project provides a simplified, 'Hello World'-style implementation to introduce the basic concepts of terminology provider plug-ins. The terminology resource supports only simple, two-column (source/target language) text files. The search function is limited to basic text searches without stemming or fuzzy matching logic.