Script Translation Procedure
Doug Lee

This document explains how translation of my scripts can be accomplished. This includes a detailed description of how to handle XML message files now used by many of my public scripting projects.

History of document:

May 31, 2020
Added the When The Target Language Is Not Supported By JAWS section.
April 21, 2020
Added some final tips on translating XML files.
April 19, 2020
Initial publication.

Table of Contents

The General Translation Process

My scripts use Nullsoft Installer System (NSIS) installers for installation. By design, besides working as script installers, these can be unpacked with 7Zip or a compatible utility, so that translators can choose whether to install the scripts or simply extract the script files for translation directly.

Most if not all files can be translated independently without requiring script recompilation. jsm files were an exception, but these files are being replaced with xml files as of April 18, 2020.

The following list is a quick guide on what to translate and how, based on file extension:

jdf
JAWS dictionary files. How or whether to translate lines in this file type very much depends on the purposes of the file and its entries. As a rule though, the first segment of each line is something that JAWS is meant to change, before speaking, into what appears in the second segment. It is likely that the first segment will be matched against application text and would need to be copied from the application, whereas the second segment is simply spoken and can be translated without further reference.
jsd
Translate material after the :Synopsis and :Description lines for each script. This material becomes keyboard help text for users. It is not necessary to translate anything for functions, as this material is not accessible to users except in the JAWS Script Manager. Likely much to the relief of translators, the distributed jsd files will usually only contain material that end users can view, such as via JAWS' Keyboard Help mode.
jsm
Translating these requires recompilation of scripts, for which reason they are being replaced in my scripts with xml files. If you encounter a jsm file in one of my script sets that does not include jss files, seek an updated script set before translating.
htm
This is the user guide loaded when a user types JAWSKey+F1 twice in quick succession. This would be translated like any other HTML file.
qsm
Messages in these files become text in the JAWS Quick Settings dialog. These files are in the XML format, and the specific file structure for these files is defined by JAWS.. Translate what appears in quotes after "Text=" and what appears between "<HelpMsg>" and "</HelpMsg>."
File names ending in "_lang.xml"
These files replace the corresponding jsm files previously used. These files start with instructions on how to add translations. In brief: Copy the English language block and place the new copy below the original, change the new block's language code from "enu" to the JAWS three-letter code for the language you will be writing, then translate as usual for jsm message constants. See also the next section of this document.

The following file types need no translation as a rule: jcf, jsb, jss, jkm, qs.

The following file types may need translation if ever present in one of my script sets but typically do not appear: jbs, jfd, jgf.

As of the use of XML files in place of jsm files, there is no need for translators to send files to, or obtain files from me in order to produce a translation. No script recompilation is required.

For most script sets, switching back into the scripted application after making translation updates is sufficient to activate the updated translations. This also works for XML message files. If the scripts run from default.jsb or via the myExtensions feature, however, a JAWS restart or a script reset will be necessary.

The XML Message File

Starting April 18, 2020, my scripts that used jsm files began using XML files instead. These files actually end in _lang.xml; so for example, the message file for myScripts.jsb would be called myScripts_lang.xml instead of myScripts.jsm. This document will refer to these files as "message files" or "XML message files" from now on.

XML Message File Format

The structure of an XML message file, at a high level, is very similar to that of the original jsm file: a sequence of message constants with names, usually with comments above each to explain what it is and how to translate it.

Comment lines that began with a semicolon (;) in a jsm file are surrounded in XML by comment indicators:

; This was a jsm comment.
<!-- This is an XML comment. -->

A full example of an original jsm message entry and how it looks in the XML message file format:

jsm:

; Insert+q script information. %1 is the revision number.
@msgScriptName
Revision %1 Microsoft Teams
@@

XML message file:

<!-- Insert+q script information. %1 is the revision number. -->
<message name="msgScriptName">
Revision %1 Microsoft Teams
</message>

In the XML format, the messages are contained within a "language" block that specifies the language of the messages in that block. The language block, or blocks, are contained within a "languages" container. The only line outside this container is the first line of the file, which specifies that is a UTF-8 encoded XML file.

Language Blocks

An XML file may contain any number of language blocks, each with language-specific translations for each named message. For reasons that will shortly be explained, I recommend keeping two language blocks in every XML message file, in this order:

  1. The original English block that came with the scripts. This block will have the language code "enu."
  2. The translation of all messages from that block into your preferred language, with its three-letter JAWS code.

Why not collect all translations into one XML message file? It is currently harmless to keep more language blocks in an XML message file. However, because of the way JAWS separates script files into folders by language, this practice is currently not required for correct operation; rather, the XML message file for a particular language must reside in that language's user script folder and contain at least a block for that language.

So why keep the English translation in every XML message file? Two reasons:

  1. If a message is missing from the language block associated with the active JAWS language and the English (enu) block is present in the file, the corresponding English message will be used. If this message cannot be found, usually because the English block is not present, there will be no message to use. It is likely preferable for JAWS to say something rather than nothing at all, so I recommend leaving the English block in place in all XML message files.
  2. When the scripts are updated and the XML file changes, leaving the English block at the top of your copy permits much easier comparison, such as with a "diff" utility, between your latest translation and the updated English messages. This is also the reason I recommend placing translations below, rather than above the English block.

XML Message File Update Procedure

This is the recommended procedure for updating an XML message file:

  1. Obtain the XML message file along with other script files.
  2. If you have not translated this file before, make a copy of the English language block, place it below the English block, and change the language code for the new block to be the three-letter code for your chosen language. Then in your new block, replace the English messages with your translations, leaving the original English block above this unchanged. Make sure that both your block and the original block start with a <language code="..."> line (where "..." is a three-letter language code) and end with a </language> line.
  3. If you have translated this file before, compare the new copy against your copy. Note lines in the English block that have changed, and make corresponding changes in your language block below the English one.
  4. Test your modifications against the scripted application.
  5. Distribute your script translation once it is working as intended.

When The Target Language Is Not Supported By JAWS

JAWS scripts look up messages in XML files based on the JAWS language in effect, on the assumption that the JAWS user will be using the same JAWS language and application language. This works well when JAWS supports the user's preferred language, but JAWS does not support all languages that an application may support.

If you need to support an application language that is not supported by JAWS, the following method should work:

For example, if you are translating a set of scripts into Estonian but JAWS does not support Estonian, and you determine that your Estonian JAWS users will be using JAWS in English and Russian:

Note: Lest this approach seem peculiar, recall that it very much mirrors the approach that was required when jsm files were used. In the example, Estonian jsm files and compiled scripts would have been required in both the enu and rus JAWS user folders.

Final Tips

Anyone who translates several of my script sets wil begin to discover some common elements among them. It will likely be possible to speed translation of a new script set by the following means if you have another set already done:

Handling Installers

From time to time, I am asked various installer-related questions. I list them here as best I can.

Is the installer source available?
Yes and no. The specific source for each script installer is not available, but the source for the BX installer is. Unpack that installer with 7Zip or a compatible utility to get at it. That installer handles more complex issues than most of my script installers must, including "script chaining" for default-level scripts.
Can I write a multi-language installer and make it work for all translations?
I have so far chosen not to try this, for several reasons. These include

My Philosophy of Translation

My operating philosophy for script translations, installers, and all, summarized:

Contacting Me

Refer to my Contact and Support Information page for details on ways to contact me.