How to Localize Scripts

Applies to Adobe Application Scripts Downloaded from This Site

As a US resident, my scripts are written in English. Because of requests to support additional languages, I have begun to internationalize some of my scripts. Of my scripts that now provide user-configurable localization, I’ve chosen to accomplish the feature by pulling the interface text from an optional translation file, which is the same name as the script except the extension is "i18n" (numeronym for internationalization: i + 18 characters + n).

This decoupling of the interface text from the script allows users to create their own localization of any desired language, at any time, without changes to the script itself. To assist users who want to localize these scripts to enhance the usability, I will outline how it works.

The i18n file is formatted as JavaScript Object Notation (JSON). Because the format is structured plain text, it may be modified in any text editor. The only important point is that all syntax is crucial. Do not disturb any characters or punctuation except inside the second set of quotation marks as directed. If anything is wrong — missing or misplaced opening or closing brace, missing colon between key and value, separating comma missing — loading the i18n file will fail and the script defaults back to US English. If this occurs, check the i18n file for proper syntax.

The data is arranged in key/value pairs — the key, a colon, then the value associated with the key. Both key and value are wrapped in double quotation marks. If translation requires a literal double quotation mark in the value, it must be escaped by prefixing with a backslash (i.e. \"). Each key/value pair is separated by a comma. Note this comma does NOT go inside the closing quotation mark, nor does the comma between key and value, although either key or value may include these or other punctuation. Finally, the entire series of key/value pairs is wrapped in braces { }.

The first key is "Language" and its value is the name of the language. After that each key is English text, and the value is the translation of the English text. The precise value of the initial key "Language" is not crucial, as currently the value only serves to identify the file’s contents, but in the future it may be used to select from multiple languages, so it is recommended to use the locale’s native name for the language.

The default i18n file is all English, both the keys and the values. To translate, leave the first string of characters within quotes (the key) as English, and edit only the second string of characters (the value).

A simplified example:

{
 "Language": "English",
 "An error has occurred.": "An error has occurred.",
 "Cancel": "Cancel",
 "Progress": "Progress",
 "Save": "Save"
}

Translated to Spanish:

{
 "Language": "EspaƱol",
 "An error has occurred.": "Ha ocurrido un error.",
 "Cancel": "Cancelar",
 "Progress": "Progreso",
 "Save": "Guardar"
}

When translating, try to be concise. If a straight word-for-word translation works, that’s great. But if rephrasing in the target language might give a more concise result, that could be good also. I’m no language expert, so take liberties when it seems appropriate. All I know, when designing a user interface, I strive for the least words that best describe what is being expressed, considering the context. Try to do the same in your native language.

Once all values are translated, the file should be renamed to signify the language it contains. The default English i18n file has “en” in the file name, the ISO language code for English. Revise this to the appropriate code to make clear the language the file now represents. For a complete list of standard language codes, search the web for “ISO-639.” One of many sites is Wikipedia List of ISO 639-1 codes.

Next place the edited i18n file alongside the script file in the application scripts folder. For help installing scripts, and any associated i18n file, see How to Install and Use Scripts in Adobe Creative Cloud Applications.

Once the script and i18n files are in the scripts folder, from the application launch the script. If all goes well, the script interface will display the desired language. If for any reason loading the i18n file fails, the script defaults to US English (same if an i18n file is absent). If the application scripts folder contains more than one i18n file that shares the script’s name, the first discovered (alphabetically) will load. For example, if i18n files labeled en and es exist, English will load first instead of Spanish. Ensure only the i18n file for the desired language is present in the application scripts folder.

And please, send to me your edited i18n file — I will load it up and check that the translated text has room on the interface, as differing languages can have differing phrase/sentence length. Any problems I will make adjustments to the script as needed. And I’ll add the i18n file to the script’s language pack so the added language translation is available to other users. Contact me for details of where to send your edited i18n file, or for any other questions or concerns.

William Campbell