Translating JAWS Scripts Into Another Language
Last Revised March, 2012

This document describes how to localize English scripts for use in another language. Translators and readers of this document should be familiar with the following:

Translating scripts into another language should not require any changes to code files (jss, jsh), since the strings requiring localization are moved out into files intended for translation (jsm, jsd).

The first section below describes in some detail, for those new to the process, how to determine what does and does not require translation. Script translation will involve two kinds of translation, described in the following two sections. Keeping up with script updates is covered in the final section.

Table of Contents

What To and Not To Translate

What does or does not need translation in any particular file is of course determined in part by the type of the file. The following guidelines, likely familiar to seasoned JAWS file translators but not to others, apply to all standard JAWS file types:

What not to translate:

What to translate:

JAWS output translation

This is translation of what JAWS will say to the user. This requires

Translating "msg" constants should be fairly self-explanatory. Where necessary, the jsm file should include comments above a constant explaining how and/or where it is used, to provide necessary context for the translation.

Placeholders like %1 are sometimes used to allow variable portions of a phrase to be placed appropriately in different languages. For example, if the string

the %1 umbrela
is meant to convey an umbrela's color, "%1" may become "red" when the string is used. The Spanish version of this string would be
el paraguas %1
because the proper placement of a Spanish adjective like "rojo" (the Spanish word for "red") is after, not before, the noun to which it applies.

Translating a jsd file involves careful translation of only those parts of the file that are descriptive text that can be spoken to the user. Relevant descriptive text appears on ":Synopsis" and ":Description" lines that are right below a ":Script" line. (Do not translate the colon-prefixed key words at the beginnings of lines, such as ":synopsis.") For various reasons, translation of the following parts of a jsd file is not recommended in most cases:

Mostly this is because those parts will not speak to users unless the users are trying to write scripts for themselves, and the scripting language itself is based on English.

In some cases, other files, such as graphic label (jgf) files or JAWS dictionary (jdf) files may require translation. In a graphics file, translate text to the right of equal (=) signs. Dictionary files may be trickier because the first part of each entry is dependent on the application to which the dictionary applies. See the next section.

After the jsm and jsd files are translated, whatever script code functions properly in the target language should speak in that language. However, another type of translation is often required to achieve correct script functionality in another language.

Application text translation

This is translation of text that is contained in the application and that the scripts need to check for. Translating this text is not merely a translation into appropriate text in the target language. Rather, the new text must precisely match what the application itself will show or provide for the string being translated. Strings of this type will appear in jsm files as constants or messages and will usually begin with "sc."

As an example of why this type of translation is necessary, consider a hypothetical screen containing many fields, one of which is a "Home Phone" field. The "Home Phone" field contains a button which, when pressed, brings up a list of area codes and their countries. This button is not natively accessible though, so a hypothetical script is written to make F4 pop up the area code and country list, but only if pressed on the "Home Phone" field. In another language of the application, "Home Phone" will be written in that language. In order for the F4 script to work, it must know exactly what the application will use for the name of the "Home Phone" field in the target language. Translating "Home Phone" arbitrarily will not work, because the script code will look for the actual screen text shown by the application.

To translate strings of this type, first find where they appear in the application, then use the exact text from the screen as the translation. This technique will often help with the first parts of dictionary (jdf) file line translations as well.

Keeping Up With Script Updates

As the scripts change to keep up with application updates, add features, etc., conforming changes in translated scripts will sometimes be required. The general approach to this type of maintenance is

  1. Keep copies of the English and localized versions of the last set of scripts you translated.
  2. When a new script version comes out, download it and compare the files requiring translation in the English version you saved with the same files in the new scripts.
  3. Where there are changes between two versions of a file, make conforming changes in the localized version of the same file.
  4. Save the updated localized scripts for the comparison when the next script update comes out.

A common way to simplify step 2 above is to use a "diff" utility; that is, a program whose purpose is to list changes between two versions of a file or set of files. A number of diff utilities are available, including WinDiff and the diff that comes as part of the Cygwin package. It is beyond the scope of this document to provide support or training in the use of any particular diff utility, but the following general principals should apply to most or all of them: