How to translate and use Apex text messages inside javascript code and other considerations about shortcuts

Always check out the original article at http://www.oraclequirks.com for latest comments, fixes and updates.

For a long time I thought that whenever I had to display a translatable message inside JavaScript the only way forward was to create an Apex shortcut containing plain text.
An Apex shortcut is just a snippet of text or code, identified by an uppercase name, that can be substituted in certain spots, a handful of region attributes and templates where shortcut substitutions are supported in the form of double quotes containing the name.
My gut feeling is that shortucts are still one of the most obscure Apex features for most developers, also because the documentation is not especially abundant in details about how to utilize them and where.

Shortcuts come in handy whenever a certain piece of static text or code needs to be repeated several times, thereby simplifying its maintenance by reducing the risk of introducing errors in case of changes over time.
Shortcuts are also eligible for translations through Apex standard translation mechanism, a three step process consisting in language mapping, text translation and application publication.

A typical example of such shortcut is the delete confirmation message that is displayed whenever you press the DELETE button in certain Apex applications.  This message comes from text stored as a shortcut named HTMLDB_CONFIRM_DELETE in the shared components of the application.
Another typical situation is when you create a master-detail navigation form using the Apex wizard: it will automatically create a shortcut called OK_TO_GET_NEXT_PREV_PK_VALUE containing the message "Are you sure you want to leave this page without saving?" of type "Text with JavaScript Escaped Single Quotes".

For some reason today I decided to explore a little further certain features of these shortcuts that never got much attention earlier and I found out that there is a better way of doing this or so I believe according to my personal taste.
First of all, Apex shortcuts come in different flavors:

1. HTML Text
2. HTML Text with Escaped Special Characters
3. Text with JavaScript Escaped Single Quotes (single quotes in 'text' are escaped as \'text\')
4. PL/SQL Function Body
5. Image
6. Message
7. Message with JavaScript Escaped Single Quotes (single quotes in 'text' are escaped as \'text\')

Some of these types like PL/SQL Function Body and Image are simply mentioned in the official documentation without further details.
Among the remaining ones, the last two were the most promising candidates for what I had in mind. Indeed it turned out to be quite easy to understand how the shortcut/message combination works:

• first you need to create a translatable text message in the various languages you want to support;
• then you need to create a shortcut whose name is equal to the name of the message;
• the shortcut attribute remains empty because Apex is taking the text from the message, not from this attribute.
• finally you need to specify the shortcut inside the relevant apex component, typically it will be in the JavaScript Function and Global Variables declaration section of the page header, something like this:

 var gConfirmMsg='"CONFIRMMSG"';

This enables you to easily retrieve the value of gConfirmMsg anywhere inside the JavaScript code run in your page, including of course dynamic actions.
Using a global variable to hold the translated message allows you to pass the text as a parameter or use it directly inside the function in case the code is stored in a stand-alone script. Standalone scripts can be cached by the browser so they are definitely the option to go for in order to minimize the footprint of any web page.

According to official documentation's bits and pieces collected from the manuals and the contextual help, shortcuts can be used inside the following components:

• The Region Source of regions defined as "HTML Text (with shortcuts)" (region attribute);
• Region Header (region attribute);
• Region Footer (region attribute);
• Region Templates attributes;
• HTML header (page attribute);
• JavaScript Function and Global Variable declaration attribute (page attribute);
• Execute when Page Loads attribute (page attribute);
• Help page (page attribute);
• Default Value (item attribute);
• Label (item attribute, see note below);
• Item pre-element text (item attribute, see note below)
• Item post-element text (item attribute, see note below)

Note: the last three attributes support the following substitution strings inside the shortcut (which means that Apex will first expand the shortcut and then the substitution strings before returning the final string):

• #CURRENT_FORM_ELEMENT#
• #CURRENT_ITEM_ID#
• #CURRENT_ITEM_NAME#

Inside shortcuts of type 1, 2 and 3 you can also reference application and page items using the syntax &ITEM.as well as #IMAGE_PREFIX#. If you need to reference then values like APP_USER, then use the syntax &APP_USER. not #APP_USER# (for types 6 and 7 it doesn't apply and in the remaining cases I hadn't a chance to verify).

As far as I know there are no other places where shortcuts are supported.