The MorphX Development Environment and Tools

Label editor

The term label in AX 2012 refers to a localizable text resource. Text resources are used throughout the product as messages to the user, form control labels, column headers, Help text in the status bar, captions on forms, and text on web forms, to name just a few uses. Labels are localizable, meaning that they can be translated into most languages. Because the space requirement for displaying text resources typically depends on the language, you might fear that the actual user interface must be manually localized as well. However, with IntelliMorph technology, the user interface is dynamically rendered and honors any space requirements imposed by localization.

The technology behind the label system is simple. All text resources are kept in a Unicode-based label files that are named with three-letter identifiers. In AX 2012, the label files are managed in the AOT and distributed by using model files. Figure 2-12 shows how the Label Files node in the AOT looks with multiple label files and the en-us language identifier.

FIGURE 2-12 The Label Files node in the AOT.

The underlying source representation is a simple text file that follows this naming convention:

• Ax<Label file identifier><Locale>.ALD

The following are two examples, the first showing a U.S. English label file and the second a Danish label file:

• Axsysen-us.ALD
• Axtstda.ALD

Each text resource in the label file has a 32-bit integer label ID, label text, and an optional label description. The structure of the label file is simple:

• @<Label ID><Label text>
• [Label description]

Figure 2-13 shows an example of a label file.

FIGURE 2-13 Label file opened in Notepad showing a few labels from the en-us label file.

This simple structure allows for localization outside of AX 2012 with third-party tools. The AOT provides a set of operations for the label files, including an Export To Label file that can be used to extract a file for external translation.

You can create new label files by using the Label File Wizard, which you access directly from the Label Files node in the AOT, or from the Tools menu by pointing to Wizards > Label File Wizard. The wizard guides you through the steps of adding a new label file or a new language to an existing label file. After you run the wizard, the label file is ready to use. If you have an existing .ald file, you can also create the appropriate entry in the AOT by using Create From File on the context menu of the Label Files node in the AOT.

NOTE

You can use any combination of three letters when naming a label file, and you can use any label file from any layer. A common misunderstanding is that the label file identifier must match the layer in which it is used. AX 2012 includes a SYS layer and a label file named SYS; service packs contain a SYP layer and a label file named SYP. This naming standard was chosen because it is simple, easy to remember, and easy to understand. However, AX 2012 doesn’t impose any limitations on the label file name.

Consider the following tips for working with label files:

• When naming a label file, choose a three-letter ID that has a high chance of being unique, such as your company’s initials. Don’t choose the name of the layer, such as VAR or USR. Eventually, you’ll probably merge two separately developed features into the same installation, a task that will be more difficult if the label file names collide.
• When referencing existing labels, feel free to reference labels in the label files provided by Microsoft, but avoid making changes to labels in these label files because they are updated with each new version of Microsoft Dynamics AX.

Creating a label

You use the Label editor to create new labels. You can start the Label editor by using any of the following procedures:

• On the Tools menu, point to Label > Label Editor.
• On the X++ code editor toolbar, click the Lookup Label > Text button.
• On text properties in the property sheet, click the Lookup button.

You can use the Label editor (shown in Figure 2-14) to find existing labels. Reusing a label is sometimes preferable to creating a new one. You can create a new label by pressing Ctrl+N or by clicking New.

FIGURE 2-14 The Label editor.

In addition to finding and creating new labels, you can use the Label editor to find out where a label is used. The Label editor also logs any changes to each label.

Consider the following tips when creating and reusing labels:

• When reusing a label, make sure that the label means what you intend it to in all languages. Some words are homonyms (words that have many meanings), and they naturally translate into many different words in other languages. For example, the English word can is both a verb and a noun. Use the description column to note the intended meaning of the label.
• When creating a new label, ensure that you use complete sentences or other stand-alone words or phrases. Don’t construct complete sentences by concatenating labels with one or two words because the order of words in a sentence differs from one language to another.

Referencing labels from X++

In the MorphX design environment, labels are referenced in the format @<LabelFileIdentifier> <LabelID>. If you don’t want a label reference to be converted automatically to the label text, you can use the literalStr function. When a placeholder is needed to display the value of a variable, you can use the strFmt function and a string containing %n, where n is greater than or equal to 1. Placeholders can also be used within labels. The following code shows a few examples:

// prints: Time transactions
print "@SYS1";

// prints: @SYS1
print literalStr("@SYS1");

// prints: Microsoft Dynamics is a Microsoft brand
print strFmt("%1 is a %2 brand", "Microsoft Dynamics", "Microsoft");
pause;

The following are some best practices to consider when referencing labels from X++:

• Always create user interface text by using a label. When referencing labels from X++ code, use double quotation marks.
• Never create system text such as file names by using a label. When referencing system text from X++ code, use single quotation marks. You can place system text in macros to make it reusable.

Using single and double quotation marks to differentiate between system text and user interface text allows the Best Practices tool to find and report any hard-coded user interface text. The Best Practices tool is described in depth later in this chapter.