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:

find-and-replace-local-folder

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.

  1. Log on to the memoQ server computer through Remote Desktop.
  2. 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.

    find-and-replace-deptool-scriptingconfig

  3. 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.
  4. Under memoQ server, click Advanced. In the menu, click Configure custom code execution. The Configure custom code execution window opens.

    deptool-conf-customcode

  5. 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.

  6. Clear the Limit executable files to scripting and batch files only (no EXEs) check box. The Find and Replace tool is an .exe file.
  7. 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.

Before you can use the Find and Replace tool, you need to copy its files to a folder where memoQ server can use them.

  1. Log in to the memoQ server computer through Remote Desktop, and copy the files using File Explorer.

    Work on the server: All drives, folders, paths exist locally on the memoQ server computer. This description will work if the memoQ server is installed with default settings.

  2. At first, the Find and Replace tool is in the C:\Program Files\Kilgray\MemoQ Server\FindReplace Tool folder. Open this folder first: Open File Explorer. Copy and paste this folder in the address bar of File Explorer (This PC) window, then press Enter.

    find-and-replace-source-folder

  3. Select and copy both files you find in the FindReplace Tool folder.
  4. Then, still in File Explorer, open the C:\ProgramData\MemoQ Server\Scripting folder. Normally, this folder is hidden. To open it, type (don't paste!) the path from this topic in the address bar of the File Explorer window, then press Enter. (If you copy and paste the folder, you won't be able to copy the files.)
  5. In the Scripting folder, create another folder called FindAndReplace. Open the new folder.
  6. find-and-replace-folder-on-server
  7. Paste the files in the FindAndReplace folder.

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:

  1. conversions before importing the document (in the example: PreImport),
  2. conversions after exporting the document (in the example: PostExport), or
  3. 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.

find-and-replace-script-one-use-case

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.

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

find-and-replace-sample-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.

find-and-replace-script-one-use-case

find-and-replace-post-export

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:

find-and-replace-post-import

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

  1. Open the Resource Console.
  2. To create an online project template: Connect to the memoQ server where you set up the Find and Replace tool. In the Server URL box, type or choose the address of the server, and click the tick mark icon-select icon. If you plan to use a local project template, you can skip this step.
  3. Choose a built-in project template, preferably One TM per client template, and clone it. Right-click the template, and choose Clone. In the Clone project template into a new resource window, type a name for the new template, then click OK.
  4. Edit the template. Right-click the new template, and choose Edit. The Edit project template window opens.

    To learn more about editing templates: See the Edit project template topic.

  5. To set up the Find and Replace tool: In the Edit project template window, click Automated actions.

You need to put your custom program inside the template. But the Find and Replace tool lives outside it: It's in a folder on your computer - or on the memoQ server computer.

How will the tool get into a template now?

There is a trick for that. You need to create a little batch file that calls on the Find and Replace tool. If the tool is on a memoQ server, the batch file looks like this:

"C:\ProgramData\MemoQ Server\Scripting\FindAndReplace\FindAndReplace.exe" %1 %2 %3 %4 %5 %6 %7 %8 %9

If the tool is on your computer , the batch file looks like this:

"C:\Program Files (x86)\Kilgray\FindReplace Tool\FindAndReplace.exe" %1 %2 %3 %4 %5 %6 %7 %8 %9

To create the file to include, select and copy the above line. Open Notepad, and paste this line. Save the document to your own Documents folder, and name it StartScript.bat.

On a memoQ server computer, if the Find and Replace tool was set up in the FindAndReplace folder within the Scripting folder, this line will work on your system. Otherwise, you may need to change the path in the line.

In the Edit project template window, under Automated actions, you will add this file as the script for the automated actions.

To learn more: Read the other sections in this topic.

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.

  1. Open the online project template for editing. The Edit project template window opens.
  2. In the Edit project template window, choose Automated actions. In the Automated actions pane, click the Script before import tab.
  3. 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.
  4. Under Script name, type a friendly name for this action.
  5. Next to the Select the files needed to run your code box, click Add files. An Open window appears.
  6. 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.
  7. 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}

  8. 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:

    find-and-replace-settings-aa

  9. Under Script and file types, click Add as new item.
  10. Don't forget to set up the reverse script on the Script after export tab. To learn how, read the next section.

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 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 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.

  1. Open the online project template for editing. The Edit project template window opens.
  2. In the Edit project template window, choose Automated actions. In the Automated actions pane, click the Script after export tab.
  3. 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.
  4. Under Script name, type a friendly name for this action.
  5. Next to the Select the files needed to run your code box, click Add files. An Open window appears.
  6. 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.
  7. 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}

  8. 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:

    find-and-replace-settings-aa-postexp

  9. Under Script and file types, click Add as new item.
  10. Make further changes to the project template as you see fit. When you finish, click OK in the Edit project template window.

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.

  1. Open the online project template for editing. The Edit project template window opens.
  2. In the Edit project template window, choose Automated actions. In the Automated actions pane, click the Project automation tab.
  3. 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.
  4. Next to the Actions added to the selected trigger box, click the Add icon_addaction icon. The Select actions you want to add to the trigger window opens.
  5. 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.
  6. Next to the Select the files needed to run your code box, click Add files. An Open window appears.
  7. 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.
  8. 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}

  9. Check the Export documents as MQXLIFF for script to process and the Update documents in project from script's output check boxes.
  10. 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:

    find-and-replace-settings-aa-postimp

  11. Click OK.
  12. 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.