Note that these menu items will be grayed out (as here) unless
you have EncConverters v 2.2 installed on your system. This utility is
available as part of FieldWorks 3.1 or it can be downloaded from this website: http://scripts.sil.org/EncCnvtrs
+class=MsoHyperlink>http://scripts.sil.org/EncCnvtrs
diff --git a/redist/Help/Azure_OpenAI_Translate_Plug-in_About_box.htm b/redist/Help/Azure_OpenAI_Translate_Plug-in_About_box.htm
new file mode 100644
index 00000000..ccaa1288
--- /dev/null
+++ b/redist/Help/Azure_OpenAI_Translate_Plug-in_About_box.htm
@@ -0,0 +1,2094 @@
+
+
+
+
+
+
+
+Azure Open AI Translate
+
+
+
+
+
+
+
+
+
+
+
+
+
+Azure Open AI Transducer
+
+This
+converter allows you to use Azure Open AI Service™ to do text processing within EncConverter-enabled
+applications. Azure Open AI is a cloud-based Artificial Intelligence
+service based on (currently) Chat GPT 3.5 and 4 and several other model as
+well. It can be used to perform language translation and other language-related
+operations between a growing number of languages (see this website for specific languages supported). Note that
+it requires a live internet connection to function.
+
+The
+Azure Open AI Transducer uses an Azure Open AI Resource to do the
+translation, which is available from Microsoft’s Azure portal, and unlike other Translators
+supported by the EncConverters core (i.e. Google, Bing & DeepL), the Azure
+Open AI Resource requires you to get your own Azure resource in order to use
+it.
+
+See
+this website for more information on getting your own Azure
+Open AI Resource.
+
+Setup Tab
+
+Here is the configuration setup tab for the Azure Open
+AI EncConverter:
+
+![]()
+
+Figure 1:
+Azure Open AI Translate Setup 1, 2, 3, 4, 5, 6,
+7
+
+
+
+1)
+This text box is for entering the Source
+language of the input text for the translation operation.
+
+2) This
+text box is for entering the Target language the input text should be
+translated into.
+
+3) This combo box/text box is for choosing one
+of the pre-existing additions or entering your own addition to be added to the System
+Prompt to customize what is sent to the Azure Open AI service.
+
+In the example shown
+above, the addition tells the AI language model to translate from Hindi to
+English and request the result be “in a ‘free translation’
+style aimed at high school students.”
+
+The underlying language
+model is quite good at understanding English and can adjust its translation for
+most requests (e.g. even sending the results back in rhyme or in ‘Yoda
+speak’ (OSV))
+
+Click on the drop-down
+arrow to the right of the box to see any pre-loaded or previously used
+additions.
+
+By default, the System
+Prompt used is:
+
+You will be given 1 or more
+lines of text in <SourceLanguage> which you are to translate into
+<TargetLanguage> <additions> and return only the translated lines.
+
+This prompt was picked
+to allow the converter to work well with the Paratext Back Translation plug-in,
+which often has multiple lines (i.e. verses) of text to be processed and as the
+language model often returns additional information about the input line to be
+translated, by default, it is instructed to return only the translated text.
+
+You can override this
+formatted System Prompt to get any arbitrary results you want by using the
+prefix: “UseSystemPrompt: ”
+
+For example, to see if
+it meets the needs of your application, you could start with the simple System
+Prompt:
+
+UseSystemPrompt: Translate
+Hindi into English.
+
+Then, the System Prompt
+sent to the language model would simply be:
+
+Translate Hindi into English.
+
+Note that if you begin
+this field with the string, “UseSystemPrompt: ”, then the Source
+and Target language boxes will be ignored.
+
+Finally, you should
+note that the Azure Open AI Resource has Content Filtering
+and it may refuse to translate some text if it runs afoul of any of these four
+areas: Hate, Sexual, Self-harm, Violence.
+
+4)
+This box shows the System Prompt that will be sent to
+the Azure Open AI service.
+
+
+
+Note that unlike the
+other Translators supported by EncConverters, the Azure Open AI (currently)
+does not have a free pricing tier, and so you’ll need to sign up for your
+own resource to use it, although for most human-guided translation work, the volume
+involved is small enough that it’s not very costly.
+
+See this
+webpage for how to get your own Azure Open AI resource to use for this
+transducer.
+
+6) If you want the
+converter to be permanently added to the System Repository, then you must click
+the Save in System Repository button
+(see below).
+
+7)
+You can click on the Test Area tab to test the
+converter with some sample data.
+
+
+
+You may not see script errors until you use the converter to
+convert some data. So, for this converter type, it is important to test it
+before trying it with real data.
+
+You can also test various System Prompts in the Azure Open AI
+Studio mentioned below to find the specific one you want to use.
+
+
+
+Entering your own Azure Open AI Resource Information
+
+Once you acquire your own Azure Open AI resource on the
+Azure portal, you can enter the
+information to use it in the dialog that appears by clicking the button on the
+Setup dialog (5) above:
+
+
+
+![]()
+
+Figure 2:
+Entering Azure Open AI Configuration Data
+
+
+
+The information you need for this dialog (by the number in
+red) is available from this page/blade of the Azure portal:
+
+The value to use in the Enter
+Azure Open AI Key’ box (1) above comes from the KEY1 field in Figure 3 below and the value to
+use for the Enter Language API Endpoint
+box (3) above comes from the Language API
+(endpoint) field in Figure 3 below.
+
+![]()
+
+Figure 3:
+Azure Portal Settings for the Azure Open AI Resource
+
+
+
+The value to use in the Deployment
+Name field (2) in Figure 2 above comes from the deployment you create on
+the Deployments blade of the Azure Open AI Studio tool as shown here:
+
+![]()
+
+Figure 4:
+Azure Portal Settings in the Azure OpenAI Studio
+
+
+
+The Azure Open AI Studio
+tool can be opened from Model deployments
+blade just below the Keys and Endpoint
+blade in Figure 3 above.
+
+Using Environment
+Variables to Store Azure Open AI Credentials
+
+When the translator is used in different client
+applications (e.g. Paratext, Word, or the Clipboard
+EncConverter), the settings (including the key mentioned above) are
+stored (encrypted) in the application settings file of the specific application
+using it. So you may be asked to enter the key,
+deployment name, and endpoint in each application that you want to
+use it in. Alternately, you can set these values as three environment variables
+(EncConverters_AzureOpenAiKey, EncConverters_AzureOpenAiDeploymentName, EncConverters_AzureOpenAiEndpoint), and they
+will be available to all applications:
+
+![]()
+
+Figure 5:
+Environment Variables for Azure OpenAI Settings
+
+
+
+
+
+Saving the
+converter in the System Repository:
+
+By default, if you click the Apply or OK
+buttons, the configured converter will be returned to the client application as
+a temporary converter for temporary use. Once the client application (e.g. FieldWorks or Word) is
+closed or releases the converter, it will no longer be available. If you want
+the converter to be permanently available to client applications, then you must
+explicitly add it to the System Repository using
+the Save in System Repository button.
+
+When you click this button, the following dialog box will
+be displayed to query for a friendly name by
+which the converter will be known in client applications:
+
+
+
+![]()
+
+
+
+The Advanced Tab can be used to enter further,
+optional information about this converter, which is also put into the System Repository and can be used by various client
+applications. Click on this tab to display the following dialog box:
+
+![]()
+
+
+
+Though these values are not necessary for the operation of
+the converter, they can be helpful to various client applications. For example,
+the Clipboard EncConverter can be configured to
+filter the list of displayed converters based on the Encoding Name
+and/or the Transduction Type configured here.
+
+
+
+
+
+
diff --git a/redist/Help/Azure_OpenAI_Translate_Plug-in_About_box_files/colorschememapping.xml b/redist/Help/Azure_OpenAI_Translate_Plug-in_About_box_files/colorschememapping.xml
new file mode 100644
index 00000000..6a0069cd
--- /dev/null
+++ b/redist/Help/Azure_OpenAI_Translate_Plug-in_About_box_files/colorschememapping.xml
@@ -0,0 +1,2 @@
+
+
+
\ No newline at end of file
diff --git a/redist/Help/Azure_OpenAI_Translate_Plug-in_About_box_files/header.htm b/redist/Help/Azure_OpenAI_Translate_Plug-in_About_box_files/header.htm
new file mode 100644
index 00000000..865573c5
--- /dev/null
+++ b/redist/Help/Azure_OpenAI_Translate_Plug-in_About_box_files/header.htm
@@ -0,0 +1,61 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/redist/Help/Azure_OpenAI_Translate_Plug-in_About_box_files/image002.jpg b/redist/Help/Azure_OpenAI_Translate_Plug-in_About_box_files/image002.jpg
new file mode 100644
index 00000000..1cffc87c
Binary files /dev/null and b/redist/Help/Azure_OpenAI_Translate_Plug-in_About_box_files/image002.jpg differ
diff --git a/redist/Help/Azure_OpenAI_Translate_Plug-in_About_box_files/image004.jpg b/redist/Help/Azure_OpenAI_Translate_Plug-in_About_box_files/image004.jpg
new file mode 100644
index 00000000..043fdca1
Binary files /dev/null and b/redist/Help/Azure_OpenAI_Translate_Plug-in_About_box_files/image004.jpg differ
diff --git a/redist/Help/Azure_OpenAI_Translate_Plug-in_About_box_files/image006.jpg b/redist/Help/Azure_OpenAI_Translate_Plug-in_About_box_files/image006.jpg
new file mode 100644
index 00000000..8bd6a87d
Binary files /dev/null and b/redist/Help/Azure_OpenAI_Translate_Plug-in_About_box_files/image006.jpg differ
diff --git a/redist/Help/Azure_OpenAI_Translate_Plug-in_About_box_files/image007.jpg b/redist/Help/Azure_OpenAI_Translate_Plug-in_About_box_files/image007.jpg
new file mode 100644
index 00000000..35044a68
Binary files /dev/null and b/redist/Help/Azure_OpenAI_Translate_Plug-in_About_box_files/image007.jpg differ
diff --git a/redist/Help/Azure_OpenAI_Translate_Plug-in_About_box_files/image008.jpg b/redist/Help/Azure_OpenAI_Translate_Plug-in_About_box_files/image008.jpg
new file mode 100644
index 00000000..b518a1d4
Binary files /dev/null and b/redist/Help/Azure_OpenAI_Translate_Plug-in_About_box_files/image008.jpg differ
diff --git a/redist/Help/Azure_OpenAI_Translate_Plug-in_About_box_files/image012.jpg b/redist/Help/Azure_OpenAI_Translate_Plug-in_About_box_files/image012.jpg
new file mode 100644
index 00000000..2bc4a3f0
Binary files /dev/null and b/redist/Help/Azure_OpenAI_Translate_Plug-in_About_box_files/image012.jpg differ
diff --git a/redist/Help/Azure_OpenAI_Translate_Plug-in_About_box_files/image017.jpg b/redist/Help/Azure_OpenAI_Translate_Plug-in_About_box_files/image017.jpg
new file mode 100644
index 00000000..9ec2d0e1
Binary files /dev/null and b/redist/Help/Azure_OpenAI_Translate_Plug-in_About_box_files/image017.jpg differ
diff --git a/redist/Help/Azure_OpenAI_Translate_Plug-in_About_box_files/item0015.xml b/redist/Help/Azure_OpenAI_Translate_Plug-in_About_box_files/item0015.xml
new file mode 100644
index 00000000..df14848b
--- /dev/null
+++ b/redist/Help/Azure_OpenAI_Translate_Plug-in_About_box_files/item0015.xml
@@ -0,0 +1 @@
+Setup TabNLLB Translator
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+No Language Left
+Behind (NLLB) Translator
+
+This
+converter allows you to use the Meta
+No Language Left Behind (NLLB)™ Translator to perform text processing within
+EncConverter-enabled applications. The NLLB Translator is currently a
+local translation service, but is expected to be online as well with the larger
+data models by the end of 2024. It can be used to perform language translation
+between a growing number of languages (see here for specific supported languages).
+
+The
+NLLB Translator, which is available to EncConverter-enabled applications,
+currently requires a number of complex additional steps to use beyond simply
+installing the EncConverter. You may need to update Powershell™ on your computer, and then download and install Docker™ (e.g. Docker Desktop for Windows), and run some commands in Powershell to build the Docker container, which
+downloads the NLLB model and other prerequisites (~2.5 GB) and creates an
+interface to the model. Finally, you need to run the Docker container to allow
+the NLLB Translator EncConverter to access the model. Instructions for these
+prerequisites are discussed below. It is suggested that you restart your
+computer before doing these steps in order to free up as much memory as
+possible.
+
+Click to Open this page in a Browser window
+
+Virtualization
+Check
+
+To download and use Docker, your computer must support
+virtualization. To check if your computer supports virtualization, press the Ctrl
++ Shift + Esc keys to open the Task
+Manager dialog. On the Performance
+tab, look for Virtualization line in the
+CPU section to see if it’s Enabled:
+
+![]()
+
+Figure 1: Virtualization Check
+
+If it’s not enabled, you may be able to enable it in
+your BIOS settings (if your computer supports it). But if it doesn’t
+support virtualization, then you won’t be able to use this
+Translator/EncConverter.
+
+Update Powershell
+
+Most Windows™ computers already have Powershell installed on
+them, and by default, you can open Powershell and run this command to update it
+to the latest version:
+
+winget install --id Microsoft.Powershell --source winget
+
+If this doesn’t work, then you can install the
+latest version of Powershell by following the instructions on this page.
+
+Install Docker
+
+Download a Windows (or other OS) installer for Docker from
+here
+and install it.
+
+You can keep whatever default settings the installer shows
+you (esp. one recommending using ‘WSL 2 instead of Hyper-V’, if you
+have the latter installed), as shown here:
+
+![]()
+
+Figure 2: Docker Installer
+
+After the installation is complete, restart your computer.
+Then open Docker for Desktop and accept
+the agreement to complete the installation using the recommended settings
+(requires administrator password).
+
+Once this is complete, it will ask you to either sign up
+or sign in or you can just Continue without signing in.
+
+Once this is complete, you can bring up the NLLB
+Translator Setup dialog to complete the configuration.
+
+Setup
+Tab
+
+To bring up the Setup dialog for the NLLB Translator, you can run, for example, the Clipboard EncConverter installed as part of SILConverters. Then right-click on its small icon in the system tray
+and choose the Edit or Delete Converters
+menu item:
+
+![]()
+
+Figure 3: Clipboard EncConverter
+
+In the resulting dialog, click the Add New button and then choose the NLLB Translator from the list and click the Add button:
+
+![]()
+
+Figure 4: Select and Add New Converter type
+
+
+
+This will bring up the Setup dialog for the NLLB
+Translator EncConverter:
+
+![]()
+
+Figure 5:
+NLLB Translator Setup Dialog
+
+
+
+The numbers in the above
+image correspond to these settings:
+
+
+
+![]()
+
+Figure
+6: Folder Browse Dialog
+
+
+
+
+
+3)
+This combo box is for selecting the Source language of
+the input text for the translation operation. Until you have the
+NLLB Model running, these list boxes will be empty.
+
+4) This
+combo box is for selecting the Target language to translate into.
+
+5)
+If you want the converter to
+be permanently added to the System Repository, then click the Save in System Repository button (see
+below).
+
+6)
+Once
+the NLLB Model is running, you can click on the Test Area tab to test the
+converter with some sample data.
+
+Model
+Configuration Dialog
+
+Click the Configure NLLB
+Model button (by number (3)
+above in the Setup dialog) to bring up the NLLB Model Configuration dialog:
+
+![]()
+
+Figure 7:
+Model Configuration Dialog
+
+
+
+The numbers in the above image correspond to these settings:
+
+1) This listbox shows the (currently) 3 models that you can
+choose from. If your computer has only 16 GB of Ram, you will want to use the
+smallest model (facebook/nllb-200-distilled-600M). If you have 32 GB of Ram, the 1.3GB model should also
+work. The larger the model, the more time it will take to do translation, but
+also the more likely it is to produce a better translation.
+
+2) This edit box is to enter an API Key which would then be
+required to access the NLLB Model for translation. If you only plan to use your
+model from your personal computer or from another computer on your local
+network, you can just keep the default value or remove the key altogether. But
+if you plan to host and access the model from the internet, then this allows
+you to specify a custom API key to restrict access.
+
+3) This edit box is to enter the endpoint through which the
+model can be accessed from your computer. If you only plan to use your model
+from your own computer, you can just keep the default value (http://localhost:8000). If you want to share a
+model with multiple computers on your local network, see the ‘Sharing
+a model with other computers on a local network’ section below.
+
+It’s also possible to use a
+different port to access the model (i.e. in place of the value 8000 above). If
+you plan to host multiple NLLB models at the same time, you will have to use a
+different port for each one to access them simultaneously. The port number can
+be whatever you want, but again, you might need to adjust the firewall to allow
+inbound traffic for whatever port you choose.
+
+4) Finally,
+once you’ve chosen the parameters you want, click the Create Docker Project button to continue. The
+Setup dialog will then install the necessary files, configured with the
+settings you choose, into the folder you entered on the Setup Dialog (see (1)
+in the Setup Tab
+section above).
+
+After the files are created, you will see this msg indicating the
+next step is to build the Docker container (you can leave this box up while you
+do the next steps):
+
+![]()
+
+Build
+Docker Container
+
+The remaining steps will be run in a Powershell window.
+Suppose the Model Configuration files were installed to the D:\repos\NNLB folder. In your
+Powershell window, change to that folder with the command:
+
+cd D:\repos\NLLB
+
+The exact commands you will execute depends on which model
+you choose in the previous step. To see the exact commands you want to execute,
+type out the README.md file using this command:
+
+type README.md
+
+and then make sure that Docker
+for Desktop is running and execute the first command listed in the
+README.md file (note the space and period (.) at the end). For example, if you
+choose the facebook/nllb-200-distilled-600M
+model, your command will look like this (your command may differ depending on
+which model you choose):
+
+docker build -t
+nllb-600m .
+
+This step can take a long time, because it must download
+the NLLB model and several other prerequisites (>2.5 GB for the smallest
+600M model).
+
+Note: there is a Powershell script named buildDocker.ps1
+that is also created in the Docker Project Folder that you could run in
+Powershell to accomplish this and the next step. But if your computer is
+initialized to block unknown Powershell scripts, the script won’t execute
+and you’ll have to enter them manually as shown above.
+
+Run
+Docker Container
+
+The final step to prepare the NLLB model is to execute the
+following command in Powershell after the docker build step completes (your
+command may differ depending on which model and port you choose):
+
+docker run -p 8000:8000
+nllb-600m
+
+Once this command is finished, your powershell should look
+something like this:
+
+![]()
+
+Figure 8: Powershell after NLLB Model is built and running
+
+If the process didn’t have enough memory to
+complete, there will be an error showing a problem with the
+‘import_model.py’ script execution. You can restart your computer
+and try it again and/or use a smaller model.
+
+To see if everything is working properly, you can open the
+url, localhost:8000, (or whatever
+endpoint you choose when configuring the Model) in a web browser, and you
+should see the following web page:
+
+![]()
+
+Figure 9: NLLB webpage (at localhost:8000)
+
+NOTE: If you created an API Key in the Model Configuration Dialog above, then you would
+need to add that key (along with the prefix, “SIL-NLLB-Auth-Key ”, note the following space) to the Authorization header in your browser to see
+this web page. For example, most browsers support the extension, ModHeader, which allows you to enter key value
+pairs in the Request Header like this:
+
+![]()
+
+Figure 10: ModHeader Chrome extension to
+add API key to Authorization header
+
+
+
+The exact value to add to the header can be found in the
+settings.py file located in the Docker Project Folder, but will be something
+like:
+
+SIL-NLLB-Auth-Key
+your-api-key-here
+
+After you are done testing this page, you may want to
+reopen the ModHeader extensions (click on
+the Extensions icon ![]()
to the right of the address bar in the
+browser) and uncheck the box next where it says Authorization in Figure 10
+above, so it isn’t used for all your internet traffic.
+
+Once this is complete, then you are ready to connect the
+NLLB Translator EncConverter to this service. Return to step (4)
+of the Model Configuration
+Dialog
+section above and click OK to connect to the model endpoint and query for
+languages in the Setup dialog.
+
+Sharing
+a model with other computers on a local network
+
+If you have multiple computers that want to share a model,
+you can host it from one computer and share the endpoint with other computers
+on your local network by configuring the latter to use the IP address of the
+hosting machine as the endpoint rather than http://localhost:8000.
+
+
+On the computer that is hosting the model, during the Model Configuration
+Dialog
+step above, you would use http://localhost:8000,
+for example, as the endpoint and build the model using the instructions in the Build Docker Container
+and Run Docker Container
+sections above.
+
+And from the other computers on your local network, during
+the Model Configuration
+Dialog
+step above, you would use the IP address of the machine with the model as the
+endpoint (e.g. http://192.168.62.154:8000).
+And then there’s no need to build the model on that computer (i.e. for
+the non-hosting machines, ignore the instructions in the Build Docker Container
+and Run Docker Container
+sections above).
+
+Also note that if you share a model with other computers,
+you may need to make a change to the firewall on the computer that is hosting
+the model to allow access to port 8000 (or whichever port you choose) from the
+network. See this
+page for hints on how to do this.
+
+Saving the
+converter in the System Repository:
+
+By default, if you click the Apply or OK
+buttons, the configured converter will be returned to the client application as
+a temporary converter for temporary use. Once the client application (e.g. FieldWorks or Word) is
+closed or releases the converter, it will no longer be available. If you want
+the converter to be permanently available to client applications, then you must
+explicitly add it to the System Repository using
+the Save in System Repository button.
+
+When you click this button, the following dialog box will
+be displayed to query for a friendly name by
+which the converter will be known in client applications:
+
+![]()
+
+
+
+The Advanced Tab can be used to enter further,
+optional information about this converter, which is also put into the System Repository and can be used by various client
+applications. Click on this tab to display the following dialog box:
+
+![]()
+
+
+
+Though these values are not necessary for the operation of
+the converter, they can be helpful to various client applications. For example,
+the Clipboard EncConverter can be configured to
+filter the list of displayed converters based on the Encoding Name
+and/or the Transduction Type configured here.
+
+
+
+
+
+
Azure Open AI Transducer
+
+This +converter allows you to use Azure Open AI Service™ to do text processing within EncConverter-enabled +applications. Azure Open AI is a cloud-based Artificial Intelligence +service based on (currently) Chat GPT 3.5 and 4 and several other model as +well. It can be used to perform language translation and other language-related +operations between a growing number of languages (see this website for specific languages supported). Note that +it requires a live internet connection to function.
+ +The +Azure Open AI Transducer uses an Azure Open AI Resource to do the +translation, which is available from Microsoft’s Azure portal, and unlike other Translators +supported by the EncConverters core (i.e. Google, Bing & DeepL), the Azure +Open AI Resource requires you to get your own Azure resource in order to use +it.
+ +See +this website for more information on getting your own Azure +Open AI Resource.
+ +Setup Tab
+
+Here is the configuration setup tab for the Azure Open +AI EncConverter:
+ +Figure 1: +Azure Open AI Translate Setup 1, 2, 3, 4, 5, 6, +7
+ +1) +This text box is for entering the Source +language of the input text for the translation operation.
+ +2) This +text box is for entering the Target language the input text should be +translated into.
+ +3) This combo box/text box is for choosing one +of the pre-existing additions or entering your own addition to be added to the System +Prompt to customize what is sent to the Azure Open AI service.
+ +In the example shown +above, the addition tells the AI language model to translate from Hindi to +English and request the result be “in a ‘free translation’ +style aimed at high school students.”
+ +The underlying language +model is quite good at understanding English and can adjust its translation for +most requests (e.g. even sending the results back in rhyme or in ‘Yoda +speak’ (OSV))
+ +Click on the drop-down +arrow to the right of the box to see any pre-loaded or previously used +additions.
+ +By default, the System +Prompt used is:
+ +You will be given 1 or more +lines of text in <SourceLanguage> which you are to translate into +<TargetLanguage> <additions> and return only the translated lines.
+ +This prompt was picked +to allow the converter to work well with the Paratext Back Translation plug-in, +which often has multiple lines (i.e. verses) of text to be processed and as the +language model often returns additional information about the input line to be +translated, by default, it is instructed to return only the translated text.
+ +You can override this +formatted System Prompt to get any arbitrary results you want by using the +prefix: “UseSystemPrompt: ”
+ +For example, to see if +it meets the needs of your application, you could start with the simple System +Prompt:
+ +UseSystemPrompt: Translate +Hindi into English.
+ +Then, the System Prompt +sent to the language model would simply be:
+ +Translate Hindi into English.
+ +Note that if you begin +this field with the string, “UseSystemPrompt: ”, then the Source +and Target language boxes will be ignored.
+ +Finally, you should +note that the Azure Open AI Resource has Content Filtering +and it may refuse to translate some text if it runs afoul of any of these four +areas: Hate, Sexual, Self-harm, Violence.
+ +4) +This box shows the System Prompt that will be sent to +the Azure Open AI service.
+ + + +Note that unlike the +other Translators supported by EncConverters, the Azure Open AI (currently) +does not have a free pricing tier, and so you’ll need to sign up for your +own resource to use it, although for most human-guided translation work, the volume +involved is small enough that it’s not very costly.
+ +See this +webpage for how to get your own Azure Open AI resource to use for this +transducer.
+ +6) If you want the +converter to be permanently added to the System Repository, then you must click +the Save in System Repository button +(see below).
+ +7) +You can click on the Test Area tab to test the +converter with some sample data.
+ +You may not see script errors until you use the converter to +convert some data. So, for this converter type, it is important to test it +before trying it with real data.
+ +You can also test various System Prompts in the Azure Open AI +Studio mentioned below to find the specific one you want to use.
+ +Entering your own Azure Open AI Resource Information
+
+Once you acquire your own Azure Open AI resource on the +Azure portal, you can enter the +information to use it in the dialog that appears by clicking the button on the +Setup dialog (5) above:
+ +Figure 2: +Entering Azure Open AI Configuration Data
+ +The information you need for this dialog (by the number in +red) is available from this page/blade of the Azure portal:
+ +The value to use in the Enter +Azure Open AI Key’ box (1) above comes from the KEY1 field in Figure 3 below and the value to +use for the Enter Language API Endpoint +box (3) above comes from the Language API +(endpoint) field in Figure 3 below.
+ +Figure 3: +Azure Portal Settings for the Azure Open AI Resource
+ +The value to use in the Deployment +Name field (2) in Figure 2 above comes from the deployment you create on +the Deployments blade of the Azure Open AI Studio tool as shown here:
+ +Figure 4: +Azure Portal Settings in the Azure OpenAI Studio
+ +The Azure Open AI Studio +tool can be opened from Model deployments +blade just below the Keys and Endpoint +blade in Figure 3 above.
+ +Using Environment
+Variables to Store Azure Open AI Credentials
+
+When the translator is used in different client +applications (e.g. Paratext, Word, or the Clipboard +EncConverter), the settings (including the key mentioned above) are +stored (encrypted) in the application settings file of the specific application +using it. So you may be asked to enter the key, +deployment name, and endpoint in each application that you want to +use it in. Alternately, you can set these values as three environment variables +(EncConverters_AzureOpenAiKey, EncConverters_AzureOpenAiDeploymentName, EncConverters_AzureOpenAiEndpoint), and they +will be available to all applications:
+ +Figure 5: +Environment Variables for Azure OpenAI Settings
+ +Saving the
+converter in the System Repository:
+
+By default, if you click the Apply or OK +buttons, the configured converter will be returned to the client application as +a temporary converter for temporary use. Once the client application (e.g. FieldWorks or Word) is +closed or releases the converter, it will no longer be available. If you want +the converter to be permanently available to client applications, then you must +explicitly add it to the System Repository using +the Save in System Repository button.
+ +When you click this button, the following dialog box will +be displayed to query for a friendly name by +which the converter will be known in client applications:
+ +The Advanced Tab can be used to enter further, +optional information about this converter, which is also put into the System Repository and can be used by various client +applications. Click on this tab to display the following dialog box:
+ +Though these values are not necessary for the operation of +the converter, they can be helpful to various client applications. For example, +the Clipboard EncConverter can be configured to +filter the list of displayed converters based on the Encoding Name +and/or the Transduction Type configured here.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
No Language Left
+Behind (NLLB) Translator
+
+This +converter allows you to use the Meta +No Language Left Behind (NLLB)™ Translator to perform text processing within +EncConverter-enabled applications. The NLLB Translator is currently a +local translation service, but is expected to be online as well with the larger +data models by the end of 2024. It can be used to perform language translation +between a growing number of languages (see here for specific supported languages).
+ +The +NLLB Translator, which is available to EncConverter-enabled applications, +currently requires a number of complex additional steps to use beyond simply +installing the EncConverter. You may need to update Powershell™ on your computer, and then download and install Docker™ (e.g. Docker Desktop for Windows), and run some commands in Powershell to build the Docker container, which +downloads the NLLB model and other prerequisites (~2.5 GB) and creates an +interface to the model. Finally, you need to run the Docker container to allow +the NLLB Translator EncConverter to access the model. Instructions for these +prerequisites are discussed below. It is suggested that you restart your +computer before doing these steps in order to free up as much memory as +possible.
+ +Click to Open this page in a Browser window
+ +Virtualization
+Check
+
+To download and use Docker, your computer must support +virtualization. To check if your computer supports virtualization, press the Ctrl ++ Shift + Esc keys to open the Task +Manager dialog. On the Performance +tab, look for Virtualization line in the +CPU section to see if it’s Enabled:
+ +Figure 1: Virtualization Check
If it’s not enabled, you may be able to enable it in +your BIOS settings (if your computer supports it). But if it doesn’t +support virtualization, then you won’t be able to use this +Translator/EncConverter.
+ +Update Powershell
+
+Most Windows™ computers already have Powershell installed on +them, and by default, you can open Powershell and run this command to update it +to the latest version:
+ +winget install --id Microsoft.Powershell --source winget
+ +If this doesn’t work, then you can install the +latest version of Powershell by following the instructions on this page.
+ +Install Docker
+
+Download a Windows (or other OS) installer for Docker from +here +and install it.
+ +You can keep whatever default settings the installer shows +you (esp. one recommending using ‘WSL 2 instead of Hyper-V’, if you +have the latter installed), as shown here:
+ +Figure 2: Docker Installer
After the installation is complete, restart your computer. +Then open Docker for Desktop and accept +the agreement to complete the installation using the recommended settings +(requires administrator password).
+ +Once this is complete, it will ask you to either sign up +or sign in or you can just Continue without signing in.
+ +Once this is complete, you can bring up the NLLB +Translator Setup dialog to complete the configuration.
+ +Setup
+Tab
+
+To bring up the Setup dialog for the NLLB Translator, you can run, for example, the Clipboard EncConverter installed as part of SILConverters. Then right-click on its small icon in the system tray +and choose the Edit or Delete Converters +menu item:
+ +Figure 3: Clipboard EncConverter
+ +In the resulting dialog, click the Add New button and then choose the NLLB Translator from the list and click the Add button:
+ +Figure 4: Select and Add New Converter type
+ +This will bring up the Setup dialog for the NLLB +Translator EncConverter:
+ +Figure 5: +NLLB Translator Setup Dialog
+ +The numbers in the above +image correspond to these settings:
+ + + +Figure +6: Folder Browse Dialog
+ +3) +This combo box is for selecting the Source language of +the input text for the translation operation. Until you have the +NLLB Model running, these list boxes will be empty.
+ +4) This +combo box is for selecting the Target language to translate into.
+ +5) +If you want the converter to +be permanently added to the System Repository, then click the Save in System Repository button (see +below).
+ +6) +Once +the NLLB Model is running, you can click on the Test Area tab to test the +converter with some sample data.
+ +Model
+Configuration Dialog
+
+Click the Configure NLLB +Model button (by number (3) +above in the Setup dialog) to bring up the NLLB Model Configuration dialog:
+ +Figure 7: +Model Configuration Dialog
+ +The numbers in the above image correspond to these settings:
+ +1) This listbox shows the (currently) 3 models that you can +choose from. If your computer has only 16 GB of Ram, you will want to use the +smallest model (facebook/nllb-200-distilled-600M). If you have 32 GB of Ram, the 1.3GB model should also +work. The larger the model, the more time it will take to do translation, but +also the more likely it is to produce a better translation.
+ +2) This edit box is to enter an API Key which would then be +required to access the NLLB Model for translation. If you only plan to use your +model from your personal computer or from another computer on your local +network, you can just keep the default value or remove the key altogether. But +if you plan to host and access the model from the internet, then this allows +you to specify a custom API key to restrict access.
+ +3) This edit box is to enter the endpoint through which the +model can be accessed from your computer. If you only plan to use your model +from your own computer, you can just keep the default value (http://localhost:8000). If you want to share a +model with multiple computers on your local network, see the ‘Sharing +a model with other computers on a local network’ section below.
+ +It’s also possible to use a +different port to access the model (i.e. in place of the value 8000 above). If +you plan to host multiple NLLB models at the same time, you will have to use a +different port for each one to access them simultaneously. The port number can +be whatever you want, but again, you might need to adjust the firewall to allow +inbound traffic for whatever port you choose.
+ +4) Finally, +once you’ve chosen the parameters you want, click the Create Docker Project button to continue. The +Setup dialog will then install the necessary files, configured with the +settings you choose, into the folder you entered on the Setup Dialog (see (1) +in the Setup Tab +section above).
+ +After the files are created, you will see this msg indicating the +next step is to build the Docker container (you can leave this box up while you +do the next steps):
+ +Build
+Docker Container
+
+The remaining steps will be run in a Powershell window. +Suppose the Model Configuration files were installed to the D:\repos\NNLB folder. In your +Powershell window, change to that folder with the command:
+ +cd D:\repos\NLLB
The exact commands you will execute depends on which model +you choose in the previous step. To see the exact commands you want to execute, +type out the README.md file using this command:
+ +type README.md
and then make sure that Docker +for Desktop is running and execute the first command listed in the +README.md file (note the space and period (.) at the end). For example, if you +choose the facebook/nllb-200-distilled-600M +model, your command will look like this (your command may differ depending on +which model you choose):
+ +docker build -t
+nllb-600m .
This step can take a long time, because it must download +the NLLB model and several other prerequisites (>2.5 GB for the smallest +600M model).
+ +Note: there is a Powershell script named buildDocker.ps1 +that is also created in the Docker Project Folder that you could run in +Powershell to accomplish this and the next step. But if your computer is +initialized to block unknown Powershell scripts, the script won’t execute +and you’ll have to enter them manually as shown above.
+ +Run
+Docker Container
+
+The final step to prepare the NLLB model is to execute the +following command in Powershell after the docker build step completes (your +command may differ depending on which model and port you choose):
+ +docker run -p 8000:8000
+nllb-600m
Once this command is finished, your powershell should look +something like this:
+ +Figure 8: Powershell after NLLB Model is built and running
+ +If the process didn’t have enough memory to +complete, there will be an error showing a problem with the +‘import_model.py’ script execution. You can restart your computer +and try it again and/or use a smaller model.
+ +To see if everything is working properly, you can open the +url, localhost:8000, (or whatever +endpoint you choose when configuring the Model) in a web browser, and you +should see the following web page:
+ +Figure 9: NLLB webpage (at localhost:8000)
+ +NOTE: If you created an API Key in the Model Configuration Dialog above, then you would +need to add that key (along with the prefix, “SIL-NLLB-Auth-Key ”, note the following space) to the Authorization header in your browser to see +this web page. For example, most browsers support the extension, ModHeader, which allows you to enter key value +pairs in the Request Header like this:
+ +Figure 10: ModHeader Chrome extension to +add API key to Authorization header
+ +The exact value to add to the header can be found in the +settings.py file located in the Docker Project Folder, but will be something +like:
+ +SIL-NLLB-Auth-Key
+your-api-key-here
After you are done testing this page, you may want to
+reopen the ModHeader extensions (click on
+the Extensions icon to the right of the address bar in the
+browser) and uncheck the box next where it says Authorization in Figure 10
+above, so it isn’t used for all your internet traffic.
Once this is complete, then you are ready to connect the +NLLB Translator EncConverter to this service. Return to step (4) +of the Model Configuration +Dialog +section above and click OK to connect to the model endpoint and query for +languages in the Setup dialog.
+ +Sharing
+a model with other computers on a local network
+
+If you have multiple computers that want to share a model, +you can host it from one computer and share the endpoint with other computers +on your local network by configuring the latter to use the IP address of the +hosting machine as the endpoint rather than http://localhost:8000. +
+ +On the computer that is hosting the model, during the Model Configuration +Dialog +step above, you would use http://localhost:8000, +for example, as the endpoint and build the model using the instructions in the Build Docker Container +and Run Docker Container +sections above.
+ +And from the other computers on your local network, during +the Model Configuration +Dialog +step above, you would use the IP address of the machine with the model as the +endpoint (e.g. http://192.168.62.154:8000). +And then there’s no need to build the model on that computer (i.e. for +the non-hosting machines, ignore the instructions in the Build Docker Container +and Run Docker Container +sections above).
+ +Also note that if you share a model with other computers, +you may need to make a change to the firewall on the computer that is hosting +the model to allow access to port 8000 (or whichever port you choose) from the +network. See this +page for hints on how to do this.
+ +Saving the
+converter in the System Repository:
+
+By default, if you click the Apply or OK +buttons, the configured converter will be returned to the client application as +a temporary converter for temporary use. Once the client application (e.g. FieldWorks or Word) is +closed or releases the converter, it will no longer be available. If you want +the converter to be permanently available to client applications, then you must +explicitly add it to the System Repository using +the Save in System Repository button.
+ +When you click this button, the following dialog box will +be displayed to query for a friendly name by +which the converter will be known in client applications:
+ +The Advanced Tab can be used to enter further, +optional information about this converter, which is also put into the System Repository and can be used by various client +applications. Click on this tab to display the following dialog box:
+ +Though these values are not necessary for the operation of +the converter, they can be helpful to various client applications. For example, +the Clipboard EncConverter can be configured to +filter the list of displayed converters based on the Encoding Name +and/or the Transduction Type configured here.
+ +