Edit template: Find and Replace script

Complex text documents may need to be changed a bit before they can be imported in a memoQ project. This change or conversion is called pre-processing, and it is run before the document is imported.

When a document is pre-processed before import, it needs to be changed back after it is exported. So, if you run pre-processing before importing a document, you need to run post-processing after exporting it.

Most of the time, all you need to do is run a couple of find-and-replace actions on the document. Sometimes you need to use regular expressions for that. You can experiment with these and fine-tune the changes in a developers' text editor such as Notepad++ or UltraEdit.

To do all this, use the Find and Replace script, which is included with memoQ 8.1 and later versions. The Find and Replace script allows you to run a series of find-and-replace actions on documents. You don't need to do any programming. You need to list your find-and-replace actions in a configuration file, using regular expressions. That cuts down on the need for learning - you don't need to learn C# or PowerShell or Python, "only" regular expressions.

Text (plain-text) documents only: The Find and Replace script works with human-readable documents: plain-text documents, tabular text documents (such as CSV), tagged documents (such as XML or HTML), or source-code documents (JSON, .properties, etc.)

This topic describes the following:

How to set up the Find and Replace script on memoQ or on memoQ server
How to write up the find-and-replace operations
How to use the Find and Replace script in a project template - for three use cases: pre-processing (before importing), post-processing (after exporting), and during a project (after importing, for example)

Prepare memoQ: Set up the Find and Replace script on your computer

On your computer, the Find and Replace script is installed in the C:\Program Files (x86)\Kilgray\FindReplace Tool folder.

The folder contains the FindAndReplace.exe program, as well as an .xml file that contains the find-and-replace rules:

On your own computer, the Find and Replace script is ready for use if memoQ 8.1 or later is installed. Take note of the folder path because you will need to use it later.

You may need administrator access: To make changes to this folder (for example, to edit the find-and-replace rules), you may need to enter the user name and the password of an administrator user. If you do not have sufficient access, the User Account Control service in Windows will warn you.

Prepare memoQ server: Set up the Find and Replace script on the server computer

Administrator access required: To do this, you need to access the memoQ server computer through Remote Desktop, and you need to be an administrator. If you do not have administrator's privileges over the memoQ server computer, contact the systems operator of your organization, and point them to this topic.

On the memoQ server, configure custom code execution

Log on to the memoQ server computer through Remote Desktop.
Run the Deployment tool: Press the Start key, type deployment (the first few letter will be enough). In the results list, click memoQ Server Deployment Administration. The memoQ Server Deployment Administration window opens.
If you can't find the tool, or it doesn't say memoQ server is installed: Install memoQ server. For instructions, read the Installing memoQ Server guide, available from the memoq.com website.
Under memoQ server, click Advanced. In the menu, click Configure custom code execution. The Configure custom code execution window opens.
Under User account for custom code execution, click Virtual service account. When memoQ server runs your programs, it will act like a user on the server. When you choose the Virtual service account, memoQ server will run programs in the name of a user called the memoQ custom code execution service.
Does your script need to reach out to the network? The virtual service account will receive all necessary privileges on the memoQ server computer - but it will not be able to log on to other computers in the network. If your scripts need to reach out to other computers, use a custom account for that. Ask your IT department or your IT administrator for a domain account that the service can use. When you have the details (user name, password, domain name), click This account, and enter the name and the password you received in the Account name and Password boxes.
Clear the Limit executable files to scripting and batch files only (no EXEs) check box. The Find and Replace tool is an .exe file.
Click Next. The next screen will show if anything is missing. If it's all green tick marks, click Finish. The deployment tool configures the service for custom code execution. The service account will receive all necessary privileges and permissions.

Set up document conversions: Write up your find-and-replace actions in the configuration file(s)

The Find and Replace tool needs a configuration file to know what to find and how to replace the text it finds.

The configuration file must be in the same folder with the tool itself. So, to set up the actual find-and-replace actions, you need to copy a configuration file to the server computer, or you need to edit the configuration file right there.

The configuration file is not hard-coded. You can pick a configuration file when you call the Find and Replace tool. However, no matter what configuration file you pick, it must be in the folder on the server computer.

You can use a separate configuration file for each document format you need to work with. Or, you can use one single configuration file, and write a separate section for each format and each conversion.

When you set up the automated action in the project template, you need to call on the Find and Replace tool - and then you must choose a configuration file and a section inside the configuration file.

A Find and Replace configuration file is an XML file, which lists find-and-replace actions for one document format. It has several sections, or use cases (usecase elements). Each section or use case is about one of the following actions:

conversions before importing the document (in the example: PreImport),
conversions after exporting the document (in the example: PostExport), or
conversions of documents while they travel through memoQ: after importing, or pre-translating, or completing the document (in the example: PostImport).

You can name these use cases anything you like. For example, you can have an .xml file that has import-export conversions for JSON, as well as import-export conversions for .po files. In this case, the sections for each use case could be called JSON-PreImport, JSON-PostExport, PO-PreImport, PO-PostExport.

If you convert on import, you must convert back on export: If you run PreImport conversions, you will need to run the opposite conversions after export (PostExport).

How can you run find-and-replace on documents that are already inside a project? When you set up a custom action after document import, memoQ server will export the document in a plain (uncompressed) memoQ XLIFF file, run it through the script you specify, and import the modified XLIFF file back into the project - all in the background.

You don't have to write up the configuration file from scratch. The Find and Replace Tool or FindReplace Tool folder contains a sample configuration file. To set up your own conversions, simply make a copy of the example_config.xml file. Replace the conversions in the file with yours.

The Find and Replace tool supports two types of find-replace actions: you can replace plain text - or you can replace text using regular expressions and placeholders.

For each use case, you can write up several find-and-replace rules. Each rule is written in a searchItem element. The type of the searchItem element ("text" or "regex") defines whether you replace plain text or use regular expressions.

In each searchItem element, there is a searchExpression and a replaceExpression element. The searchExpression element must contain exactly one plain-text search term or regular expression. The replaceExpression element must contain exactly one plain-text passage or a replacement rule using placeholders from the regular expression in the searchExpression.

Here is an example

Let's say you need to translate this XML document:

This document has two problems you can solve using the Find and Replace tool:

First, memoQ must be able to start a new segment when it finds a \n character. These characters must be turned into markup that memoQ can recognize. You can't just tag them after the document is imported (using a cascading filter that runs a regex tagger) because the segmentation rules will not pick up the \n characters. However, you may replace each the \n sequence with a <break/> tag before the document is imported. If you do this, you will also need to replace <break/> tags again with \n sequences after exporting the file. The XML filter configuration must define the <break/> tag as a structural tag, so that memoQ will always start a new segment when it sees <break/>. These conversions are set up in the PreImport and the PostExport use cases in the find-and-replace configuration file.

Second, there are segments that contain numbers only. You need to lock these before translators receive the documents. To do this, you can run a midscript - a custom automated action that is run while the document lives inside the project -, immediately after the document is imported. When you run a midscript, memoQ server exports the document in an uncompressed memoQ XLIFF file, runs your script, and then updates the document in the project from the modified memoQ XLIFF file.

To make changes to document after importing, you must always work in a memoQ XLIFF file, and write your search terms or regular expressions with this format in mind.

You can see a sample in the PostImport use case of the sample configuration file:

Set up the project template to use the Find and Replace tool

Add a FindAndReplace action that runs before a document is imported

To run Find and Replace on documents of a certain type, make sure you have the .xml file that contains the find-and-replace actions. The .xml file must be on the memoQ server computer, in the same folder as the Find and Replace tool.

To run find-and-replace actions before importing a document, the .xml file must contain a PreImport section.

To set up an .xml file with the find-and-replace actions: Read the last expanding section under Prepare the memoQ server: Set up the Find and Replace script, earlier in this topic.

Open the online project template for editing. The Edit project template window opens.
In the Edit project template window, choose Automated actions. In the Automated actions pane, click the Script before import tab.
Under Wildcard expression matching the full path, type *.extension where the extension is the ending of the name of the documents that you want to process before importing.
Under Script name, type a friendly name for this action.
Next to the Select the files needed to run your code box, click Add files. An Open window appears.
Find and select the StartScript.bat file you saved earlier. (To learn how, read the previous section.) The StartScript.bat file will appear in the Select the files needed to run your code box.
Under Command line arguments, type or paste the following:
in a local template:
/m PreImport "C:\Program Files (x86)\MemoQ\FindReplace Tool\findandreplace-config.xml" {InputFilePath} {OutputFilePath}
in an online template:
/m PreImport "C:\ProgramData\MemoQ Server\Scripting\FindAndReplace\documenttype-config.xml" {InputFilePath} {OutputFilePath}
Before you save the settings, replace the name "documenttype-config.xml" with the name of the .xml file that contains the find-and-replace actions. You may also need to replace PreImport with a different section name, if the find-and-replace rules were written in a different section. Your settings will look like this:
Under Script and file types, click Add as new item.
Don't forget to set up the reverse script on the Script after export tab. To learn how, read the next section.

Add the reverse FindAndReplace action that runs after the document is exported

If you transform a document before importing it, you also need to transform the exported file, so that you get the exported document in the format your client expects. After exporting a file, you need to run find-and-replace actions that are exactly the opposite of the actions you run before importing the document.

To run find-and-replace actions after exporting a document, the .xml file must contain a PostExport section.

To set up an .xml file with the find-and-replace actions: Read the last expanding section under Prepare the memoQ server: Set up the Find and Replace script, earlier in this topic.

Open the online project template for editing. The Edit project template window opens.
In the Edit project template window, choose Automated actions. In the Automated actions pane, click the Script after export tab.
Under Wildcard expression matching the full path, type *.extension where the extension is the ending of the name of the source documents that you want to process before importing.
Under Script name, type a friendly name for this action.
Next to the Select the files needed to run your code box, click Add files. An Open window appears.
Find and select the StartScript.bat file you saved earlier. (To learn how, read the previous section.) The StartScript.bat file will appear in the Select the files needed to run your code box.
Under Command line arguments, type or paste the following:
in a local template:
/m PostExport "C:\Program Files (x86)\MemoQ\FindReplace Tool\findandreplace-config.xml" {InputFilePath} {OutputFilePath}
in an online template:
/m PostExport "C:\ProgramData\MemoQ Server\Scripting\FindAndReplace\documenttype-config.xml" {InputFilePath} {OutputFilePath}
Before you save the settings, replace the name "documenttype-config.xml" with the name of the .xml file that contains the find-and-replace actions. You may also need to replace PostExport with a different section name, if the find-and-replace rules were written in a different section. Your settings will look like this:
Under Script and file types, click Add as new item.
Make further changes to the project template as you see fit. When you finish, click OK in the Edit project template window.

Add a custom "midscript" that runs after the document is imported or pre-translated

Sometimes you need to make changes to a document while it travels through the memoQ project. You can set up automated actions that run after importing a document (or anytime in the project). The programs you run in the middle of the projects are also called midscripts.

When you run a custom action on a document in a memoQ project, the following happens:

memoQ server exports the document in an uncompressed memoQ XLIFF (.mqxliff) file.

The memoQ custom code service runs your script through the .mqxliff file as if it were plain text. Your script must save a valid .mqxliff file.

memoQ server updates the document from the .mqxliff file that was saved by your script.

You can use the Find and Replace tool as a midscript that transforms documents in the middle of the project.

To run Find and Replace on these documents, make sure you have the .xml file that contains the find-and-replace actions. The .xml file must be on the memoQ server computer, in the same folder as the Find and Replace tool.

To run find-and-replace actions in the middle of the project, the .xml file must contain a PostImport section.

To set up an .xml file with the find-and-replace actions: Read the last expanding section under Prepare the memoQ server: Set up the Find and Replace script, earlier in this topic.

Open the online project template for editing. The Edit project template window opens.
In the Edit project template window, choose Automated actions. In the Automated actions pane, click the Project automation tab.
Under Available triggers, click After document import. You can choose another point in the project - for example, if you want to run the script after the document is pre-translated.
Next to the Actions added to the selected trigger box, click the Add icon. The Select actions you want to add to the trigger window opens.
In the Select actions you want to add to the trigger window, click Execute custom code. Click Add. The Specify custom code details window opens.
Next to the Select the files needed to run your code box, click Add files. An Open window appears.
Find and select the StartScript.bat file you saved earlier. (To learn how, read the previous section.) The StartScript.bat file will appear in the Select the files needed to run your code box.
Under Command line arguments, type or paste the following:
in a local template:
/m PostImport "C:\Program Files (x86)\MemoQ\FindReplace Tool\findandreplace-config.xml" {InputFilePath} {OutputFilePath}
in an online template:
/m PostImport "C:\ProgramData\MemoQ Server\Scripting\FindAndReplace\documenttype-config.xml" {InputFilePath} {OutputFilePath}
Check the Export documents as MQXLIFF for script to process and the Update documents in project from script's output check boxes.
Before you save the settings, replace the name "documenttype-config.xml" with the name of the .xml file that contains the find-and-replace actions. You may also need to replace PostImport with a different section name, if the find-and-replace rules were written in a different section. Your settings will look like this:
Click OK.
Make further changes to the project template as you see fit. When you finish, click OK in the Edit project template window, too.

When you finish

To test the Find and Replace script: Create an online project from the template you have just set up, and import a document that should be processed. If the document imports successfully, check out the project and open the document for editing to see if the transformations were correct.

Or, if you are using a local project template: Create a local project from the template you have just set up, and import a document that should be processed. If the document imports successfully, open the document for editing to see if the transformations were correct.

To change the find-and-replace actions: Edit the .xml file you use with the project template. (If you are working with an online template, log on to the memoQ server computer through Remote Desktop.) Add or change find-and-replace actions as you see fit. You do not need to change the project template. What's more, you can open an existing project that uses this template, and import new files. Even then, memoQ or memoQ server will use the updated find-and-replace actions.

To learn more about find-and-replace actions: Read the Set up conversions section, earlier in this topic.