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.

For an older and perhaps gentler introduction to the process of JAWS script translation, including a better treatment of .jsm files, see also my 2012 document on the subject, "Translating JAWS Scripts Into Another Language."

History of document:

November 4, 2020

Added the reference to the 2012 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
• The XML Message File
  • XML Message File Format
  • Language Blocks
  • XML Message File Update Procedure
  • When The Target Language Is Not Supported By JAWS
  • Final Tips
• Handling Installers
• My Philosophy of Translation
• Contacting Me

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:

• Determine what JAWS language, or languages, your audience will be using.
• Make a language block with your messages translated from English into your target language as usual, but assign it a valid JAWS language code that your users will use.
• If you need the translated messages to apply in more than one JAWS language, duplicate your language block and assign language codes to each duplicate for each supported JAWS language.
• Per usual, install the XML file(s) into each relevant JAWS user folder by language.

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:

• Translate the strings in the "enu" section of each XML file into Estonian directly, in place, instead of leaving the English language block unmodified. This will cause Estonian messages to work for English JAWS users.
• Duplicate the "enu" block and assign the duplicate a language code of "rus." This will make the Estonian messages apply when JAWS is operating in Russian.
• Use this XML file in the scripts you install into the settings/enu and settings/rus JAWS user folders.

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:

• If both sets include a file whose name ends in "_jcpdict_lang.xml," chances are that most of the contents of both files will be the same.
• The main XML message file for each script set is often divided into segments by code module. Some code modules are common to multiple projects; so if you recognize one, compare its message strings to those in another project to see if you've already translated most of them.

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

• Difficulty of coordinating with all translators for all languages for each project. This could hold up my script update releases.
• Desire not to take responsibility for the actual content of translations into languages I am not myself able to read. (I have a bit of experience with surprise phrasings among translations and choose to disclaim ownership of how each translator may choose to phrase messages.)
• The installers' current inability to select different files for installation by language. The XML files could be combined into one file each for all languages, but this is not true of other file types such as jsd and qsm.

My Philosophy of Translation

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

• I write as much as I can, as fast as I can, in the way I can, which is in English; and to do this, I minimize things that slow me down if there is a way to do that without hurting people.
• I provide translators with sufficient tools for translation, with the goal of letting them translate and release independently on their own schedules. As they are typically motivated by user needs in their respective communities, this causes efficient multi-lingual delivery.
• I field questions in English and let translators field questions from their own clientele in their respective languages. The translators then refer to me if necessary, in English. This causes communication to fall naturally along lines through people capable of handling it.

Contacting Me

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