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:

• The English language and the language into which the scripts are to be translated.
• The purposes of various JAWS files, as determined by their file extensions (e.g., jss, jsd, jgf, etc.).
• The basic syntax of JAWS file types that might require some translation, notably jsm and jsd files but in some cases also jfd ffiles (for frame documentation) and/or jdf files (JAWS dictionaries).
• The ini file format, which is used by jgf files.

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
• JAWS output translation
• Application text translation
• Keeping Up With Script Updates

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:

• Do not translate any text appearing on a line beginning with a semicolon (;). These are comments intended only for readers of the file, not for end users of JAWS or JAWS scripts.
• Except where otherwise clearly indicated, do not translate material on a line whose contents are enclosed in square brackets ([]). These are section names in an ini-style data file.
• Except where otherwise clearly indicated, do not translate material to the left of equal (=) signs, as these are names of constants, ini keys, etc. that must remain unchanged for the scripts to compile or function properly.
• Similarly, do not translate the material on a line beginning with an at sign (@), as these lines name constants as well.
• In jsd files, do not translate key words prefixed with a colon (:), such as :Script, :Function, and :Description.
• In jsd files, do not translate function or script names or parameter or return types such as "string" and "int." It is usually best to avoid translating anything in a jsd file except for text on lines beginning with ":Synopsis" and ":Description" in a section for a script, and to avoid translating anything at all in a section for a function.

What to translate:

• Material between a line starting with an at sign (@) and ending with a pair of them. These are multi-line constant values that often appear in jsm files.
• Items in quotes ("") after an equal sign (=). These are constant values. In ini files, quotes will not appear; but material after the equal signs should still be translated.
• In jsd files, the text (other than the key words themselves) on ":Synopsis" and ":Description" lines. It is more important to translate synopses and descriptions for scripts than for functions.

JAWS output translation

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

• Translating the "msg" constants in all jsm files into appropriate text for the new language,
• Translating the descriptive text for scripts in jsd files similarly, if you want Keyboard Help to be translated, and
• Translating strings in any other file types as required, such as jdf or jgf files.

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

el paraguas %1

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:

• :Synopsis or :Description lines for functions (as opposed to scripts).
• :Param or :Returns lines.

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:

• You provide the diff utility with either two file names or two folder names. In both cases, the first should indicate the older scripts and the second should indicate the newer scripts. Example:

  diff old/myapp.jsm new/myapp.jsm

• For command-line-based differs at least, it is possible to redirect output into a file with the greater-than (>) symbol:

  diff old new > diff.txt
  notepad diff.txt

  (That example provides two folder names, which in most differs will result in a list of changes in all files in both folders.)
• For each file compared, diff utilities usually indicate changes by producing one or more blocks of information, indicating first the line numbers of the old and new files that are described by the block, then the actual material on both old and new versions of those lines.
• A diff utility produces any of several output formats. Two examples:

  Old-style diff

  Lines beginning with a less-than sign (<) are lines from the old file, and lines beginning with a greater-than sign (>) are lines from the new file. These appear separated by a line of dashes (---). This format does not provide context, meaning that the only lines you see are the ones that have been changed or that appear in a block of changes.

  New or "unified" diff

  Lines beginning with a minus sign or dash (-) are lines from the old file, and lines beginning with a plus sign (+) are lines from the new file. Lines beginning with a space are identical in both files. This format shows a ffew lines of context above and below the lines that changed.