Skip to content

LG-53877 LG-53884 - review and update batch tasks #20

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
cornea-robert merged 1 commit into from
May 18, 2026
Merged

LG-53877 LG-53884 - review and update batch tasks #20

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 20 additions & 25 deletions apiconcepts/batchtasks/adding_a_settings_ui_to_our_batch_tasks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,7 @@
Adding a Settings UI to our Batch Task
===============================
Add a settings page to your batch task so that users can select the status that defines whether the content of a particular segment pair shall be exported to a text file.
# Adding a Settings UI to Our Batch Task
Add a settings page to your batch task so that users can select the status that determines whether the content of a segment pair is exported to a text file.

The User Control
-------------------------
## Add the User Control
In your Visual Studio project, go to the empty **MyCustomBatchTaskSettingsControl.cs** control and add the following UI elements:
<img style="display:block; " src="images/SettingsPage.jpg" />
Add the following list items to the dropdown list element (which we name **combo_Status**):
Expand All @@ -15,79 +13,76 @@ Add the following list items to the dropdown list element (which we name **combo
* Signed-off
* Sign-off rejected

The Class that Controls the Plug-in Settings
-----------------------------------
## Configure the Plug-in Settings Class
Open the **MyCustomBatchTaskSettings.cs** class, which has been automatically added to your Visual Studio project. This is the class that we use to programmatically access the settings configured by the elements on the user control UI.

This class needs to inherit the following class:

# [The Settings Class](#tab/tabid-1)
### [The Settings Class](#tab/tabid-1)
[!code-csharp[MyCustomBatchTaskSettings](code_samples/MyCustomBatchTaskSettings.cs#L6-L7)]
***

Here we declare the default setting value, which is the integer value '2' and corresponds to the confirmation level 'Translated':
# [The Default Setting Value](#tab/tabid-2)
### [The Default Setting Value](#tab/tabid-2)
[!code-csharp[MyCustomBatchTaskSettings](code_samples/MyCustomBatchTaskSettings.cs#L11-L12)]
***
The following member gets or to sets the value used for the plug-in settings. In this implementation there is only one integer value that defines the confirmation level:
# [Getting or Setting the Value](#tab/tabid-3)
The following member gets or sets the value used for the plug-in settings. In this implementation, there is only one integer value that defines the confirmation level:
### [Getting or Setting the Value](#tab/tabid-3)
[!code-csharp[MyCustomBatchTaskSettings](code_samples/MyCustomBatchTaskSettings.cs#L17-L22)]
***

Then we add the following member, which sets the confirmation property to the default value when the user clicks the corresponding button on the UI.
# [Configuring the Default Setting](#tab/tabid-4)
### [Configuring the Default Setting](#tab/tabid-4)
[!code-csharp[MyCustomBatchTaskSettings](code_samples/MyCustomBatchTaskSettings.cs#L26-L31)]
***

Finally, the following member is added to retrieve the default value for the confirmation level property of our implementation:
# [Getting the Default Value](#tab/tabid-5)
### [Getting the Default Value](#tab/tabid-5)
[!code-csharp[MyCustomBatchTaskSettings](code_samples/MyCustomBatchTaskSettings.cs#L35-L44)]
***

Adding Functionality to the User Control
-----------------------------------------
## Implement User Control Functionality
Open the code view of the user control **MyCustomBatchTaskSettingsControl.cs**. This control implements the following interfaces:
# [The User Settings Interfaces](#tab/tabid-6)
### [The User Settings Interfaces](#tab/tabid-6)
[!code-csharp[MyCustomBatchTaskSettingsControl](code_samples/MyCustomBatchTaskSettingsControl.cs#L8-L9)]
***

The following mandatory member needs to be implemented to set and get the settings properties from the **MyCustomBatchTaskSettings** class:
# [Getting and Setting the Properties](#tab/tabid-7)
### [Getting and Setting the Properties](#tab/tabid-7)
[!code-csharp[MyCustomBatchTaskSettingsControl](code_samples/MyCustomBatchTaskSettingsControl.cs#L13-L14)]
***

The following member initializes the user control:
# [User Control Initialisation](#tab/tabid-8)
### [User Control Initialisation](#tab/tabid-8)
[!code-csharp[MyCustomBatchTaskSettingsControl](code_samples/MyCustomBatchTaskSettingsControl.cs#L18-L22)]
***

The following member sets the settings on the UI control:
# [Setting the Settings](#tab/tabid-9)
### [Setting the Settings](#tab/tabid-9)
[!code-csharp[MyCustomBatchTaskSettingsControl](code_samples/MyCustomBatchTaskSettingsControl.cs#L26-L32)]
***

The following member updates the settings on the UI control:
# [Updating the Settings](#tab/tabid-10)
### [Updating the Settings](#tab/tabid-10)
[!code-csharp[MyCustomBatchTaskSettingsControl](code_samples/MyCustomBatchTaskSettingsControl.cs#L36-L39)]
***

The above member is called by the following function:
# [Updating the UI](#tab/tabid-11)
### [Updating the UI](#tab/tabid-11)
[!code-csharp[MyCustomBatchTaskSettingsControl](code_samples/MyCustomBatchTaskSettingsControl.cs#L43-L48)]
***

When the UI control is loaded, its control elements are populated with the corresponding values:
# [Loading the UI](#tab/tabid-12)
### [Loading the UI](#tab/tabid-12)
[!code-csharp[MyCustomBatchTaskSettingsControl](code_samples/MyCustomBatchTaskSettingsControl.cs#L53-L58)]
***

When the user clicks the **Restore Defaults** button, the UI controls are set to their default values:
# [Restoring the Defaults](#tab/tabid-13)
### [Restoring the Defaults](#tab/tabid-13)
[!code-csharp[MyCustomBatchTaskSettingsControl](code_samples/MyCustomBatchTaskSettingsControl.cs#L62-L68)]
***

The Settings UI Container
-------------------------------------
## Understand the Settings UI Container

Note the **MyCustomBatchTaskSettingsPage.cs** class, which has been added to the project by default. This is the class that references the settings UI and the class that controls the UI. Without the settings page class the plug-in would not be aware of the settings UI. It enables the settings UI to be shown when you reach the **Settings** page of the plug-in:
<img style="display:block; " src="images/SampleTaskSettings.jpg" />
Expand Down
55 changes: 32 additions & 23 deletions apiconcepts/batchtasks/overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,31 +1,40 @@
Batch Tasks Overview
====================
# Batch Tasks Overview

This section gives an overview of what batch tasks in Var:ProductName are and what they are used for.
This section provides an overview of batch tasks in Var:ProductName and their main use cases.

What are Batch Tasks?
----------------------
## What Are Batch Tasks?

Batch tasks are used to process one or many project files in Var:ProductName. There are several built-in batch tasks, for example, for analysing and pre-translating files. Batch tasks are most frequently applied to the bilingual SDLXliff files, but can also be used to process native file formats (for example, DOCX or PPTX). Batch tasks are typically used to:
* Alter the content of files (for example, the **Pre-translate Files** task inserts matches from a translation memory into the selected files).
* Read the content of files and compile a report (e.g. the **Analyze Files** task that determines the translation memory leverage for selected files).
* Extract content from the selected files to write them into another file format (for example, the **Export for External Review**) task that generated bilingual Microsoft Word tables from SDLXliff files.

The only standard batch task that works directly on the native files is the **Convert to Translatable Format** task, which converts native files (for example, DOCX) to SDLXliff.
Batch tasks process one or multiple project files in Var:ProductName. Several built-in tasks are available, such as analyzing and pre-translating files. Batch tasks are most commonly applied to bilingual SDLXliff files, but they can also process native file formats (for example, DOCX or PPTX).

Batch tasks are typically used to:
* Modify file content (for example, the **Pre-translate Files** task inserts translation memory matches into selected files).
* Read file content and compile a report (for example, the **Analyze Files** task determines translation memory leverage for selected files).
* Extract content and generate another file format (for example, the **Export for External Review** task generates bilingual Microsoft Word tables from SDLXliff files).

The only standard batch task that works directly on native files is the **Convert to Translatable Format** task, which converts native files (for example, DOCX) to SDLXliff.

## Running Batch Tasks

End users can run batch tasks by selecting them from a list in the Var:ProductName user interface.
<img style="display:block; " src="images/list_batch_tasks.png" />
Batch tasks are also typically executed when creating a project. In this case, batch tasks are applied to the project files in a sequence, for example:
<img style="display:block; " src="images/task_sequence.png" />
![List of Batch Tasks](images/list_batch_tasks.png)

Batch tasks are also commonly executed when creating a project. In this case, tasks are applied to project files in sequence.
![Task Sequence](images/task_sequence.png)

## Viewing Task Information

Batch tasks are shown in the Var:ProductName user interface with a name and description.
![Batch Task Information](images/analysis_general.png)

Batch tasks are then applied to one or multiple files.
![Batch Task Files](images/analysis_files.png)

## Configuring Settings

Batch tasks are shown the Var:ProductName user interface with a name and a description, for example:
<img style="display:block; " src="images/analysis_general.png" />
Batch tasks can include settings that you configure through a property page. For example, the analysis task includes a setting that determines whether cross-file repetitions are reported.
![Analysis Settings](images/analysis_settings.png)

Batch tasks are then applied to one or multiple files, e.g.:
<img style="display:block; " src="images/analysis_files.png" />
## Reviewing Reports

Batch tasks can have settings that you can configure through a property page. For the analysis task, for example, there is a setting that determines whether cross-file repetitions should be reported or not, for example:
<img style="display:block; " src="images/analysis_settings.png" />

Batch tasks can also generate a report that the user can view and print. For the analysis task, the report states the number of no matches, fuzzy matches, exact matches, repetitions, etc.
<img style="display:block; " src="images/analysis_report.png" />
Batch tasks can also generate reports that users can view and print. For the analysis task, the report includes values such as no matches, fuzzy matches, exact matches, and repetitions.
![Analysis Report](images/analysis_report.png)
50 changes: 23 additions & 27 deletions apiconcepts/batchtasks/processing_files_and_application_logic.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,76 +1,72 @@
# Processing Files and Application Logic

Implement the functionality that changes the status of document segments.
Implement this functionality to update the status of document segments.

How to trigger the batch task
---------------------------
Go back to the **MyCustomBatchTask.cs** class. This class is triggered when you decide to run the batch task. This class inherits from the following abstract class:
## Triggering the Batch Task
Go to the **MyCustomBatchTask.cs** class. This class is triggered when you run the batch task. It inherits from the following abstract class:

# [The Abstract Task Class](#tab/tabid-1)
[!code-csharp[MyCustomBatchTask](code_samples/MyCustomBatchTask.cs#L30-L31 "The Abstract Task Class")]
***

Declare a member that stores the plug-in settings, as well as a string variable that is used to construct the XML stream for the task report content:
Declare a member to store the plug-in settings, and a string variable used to construct the XML stream for the task report content:
# [The Task Settings](#tab/tabid-2)
[!code-csharp[MyCustomBatchTask](code_samples/MyCustomBatchTask.cs#L35-L39 "The Task Settings")]
****

Initialise the task settings object and start constructing the report XML string by adding the root element. The root element should contain the selected confirmation level value in an attribute:
Initialize the task settings object and start constructing the report XML string by adding the root element. The root element should include the selected confirmation level value as an attribute:
# [Report XML String](#tab/tabid-3)
[!code-csharp[MyCustomBatchTask](code_samples/MyCustomBatchTask.cs#L43-L50 "Report XML String")]
***
How to process the SDLXliff file
-----------------------------------
You can programmatically access the file that is currently processed through the following member. In a "Hello World"-type implementation you could output the name and path of the processed file.
## Processing the SDLXliff File
You can programmatically access the file currently being processed through the following member. In a "Hello World" implementation, you could output the name and path of the processed file.
# [Configuring the Converter](#tab/tabid-4)
[!code-csharp[MyCustomBatchTask](code_samples/MyCustomBatchTask.cs#L54-L71 "Configuring the Converter")]
***

As SDLXliff is an XML-compliant file type, you could process it using the standard XML API. However, we recommend that you use the Var:ProductName Bilingual API to process the file. This way, we add a new class to our project called **FileReader.cs**.
SDLXliff is an XML-compliant file type, so you could process it through the standard XML API. However, we recommend using the Var:ProductName Bilingual API. To do this, add a new class to your project called **FileReader.cs**.

The **FileReader.cs** class needs to reference the following libraries:
The **FileReader.cs** class must reference the following libraries:
```cs
using Sdl.Core.Globalization
using Sdl.FileTypeSupport.Framework.BilingualApi
```
It also needs to inherit from the following abstract class:
It must also inherit from the following abstract class:
# [Abstract class to Implement](#tab/tabid-5)
[!code-csharp[FileReader](code_samples/FileReader.cs#L15-L17 "Abstract class to Implement")]
***
Add the following members to store the task settings, the file name and path of the SDLXliff file to be processed, and the text file name and path that is used to output the exported segments:
Add the following members to store the task settings, the file name and path of the SDLXliff file to process, and the text file name and path used to output the exported segments:
# [The Required Variables](#tab/tabid-6)
[!code-csharp[FileReader](code_samples/FileReader.cs#L21-L26 "The Required Variables")]
***
How to output the segment content to a text file</title>
------------------------------------------------
With the following member we start by creating the text output file. This file is created in the same folder as the corresponding SDLXliff file and the *.txt extension is appended.
## Outputting Segment Content to a Text File
Use the following member to create the text output file. This file is created in the same folder as the corresponding SDLXliff file, with the *.txt extension appended.
# [Creating the Output File](#tab/tabid-7)
[!code-csharp[FileReader](code_samples/FileReader.cs#L40-L44 "Creating the Output File")]
***
In the next step, we loop through each paragraph unit of the SDLXliff file. We make sure to process only paragraph units that actually contain segments. When we encounter a paragraph unit that only contains structure tags (i.e. no localizable segments), we abort. When looping through the segment pairs, we write all segments with the selected confirmation status to the output text file:
# [Outputing the Segment Pairs](#tab/tabid-8)
Next, loop through each paragraph unit in the SDLXliff file. Process only paragraph units that contain segments. When a paragraph unit contains only structure tags (that is, no localizable segments), skip it. While looping through segment pairs, write all segments with the selected confirmation status to the output text file:
# [Outputting the Segment Pairs](#tab/tabid-8)
[!code-csharp[FileReader](code_samples/FileReader.cs#L48-L68 "Outputing the Segment Pairs")]
***
Once the file processing is done, we close the text output file.
Once file processing is complete, close the text output file.
# [File is Complete](#tab/tabid-9)
[!code-csharp[FileReader](code_samples/FileReader.cs#L72-L77 "File is Complete")]
***
The following member is required by the interface, although our implementation does not actually use it. The file complete member is called when processing a file is finished. However, as users could merge SDLXliff files, the following member must be present to determine what happens when the process has been completed for the entire merged file.
The following member is required by the interface, although this implementation does not use it directly. The file complete member is called when file processing finishes. Because users can merge SDLXliff files, this member must be present to determine what happens when processing is complete for the entire merged file.
# [Job is Complete](#tab/tabid-10)
[!code-csharp[FileReader](code_samples/FileReader.cs#L81-L88 "Job is Complete")]
***
How to complete the Report String
----------------------------------------
Go back to the **MyCustomBatchTask.cs** class. Here we do the following:
## Completing the Report String
Go back to the **MyCustomBatchTask.cs** class. Then do the following:

We continue constructing the XML string for the report by adding the name of the file currently processed, its target language and the date/time at which it was processed.
Continue constructing the XML string for the report by adding the name of the file currently processed, its target language, and the date and time it was processed.

We create a **FileReader** object to which we pass the current SDLXliff file name, as well as our settings object:
Create a **FileReader** object and pass the current SDLXliff file name and your settings object:
# [Configure converter](#tab/tabid-11)
[!code-csharp[MyCustomBatchTask](code_samples/MyCustomBatchTask.cs#L54-L71 "Configure converter")]
***
We complete the task by adding the closing XML report string with the closing root element. Then we generate the report using the **CreateReport** method implemented by the interface.
Complete the task by adding the closing XML report string with the closing root element. Then generate the report by using the **CreateReport** method implemented by the interface.
# [Complete task and report string](#tab/tabid-12)
[!code-csharp[MyCustomBatchTask](code_samples/MyCustomBatchTask.cs#L75-L85 "Complete task and report string")]
***
This method requires the report name, description and the XML string for the report content. You may also add an optional language direction parameter. If this parameter is missing, the report will not be listed under the specific target language, but rather above all available target languages of the corresponding project.
This method requires the report name, description, and the XML string for the report content. You may also add an optional language direction parameter. If this parameter is omitted, the report is not listed under a specific target language, but above all available target languages for the corresponding project.
Loading
Loading