Creating a Label file

Most projects have some kind of user interface, and therefore we need to display text to the user other than the field names. The best practice method to do this is to use a label file. The label file contains a language specific dictionary of label IDs and the translation.

Standard elements tend to have the legacy label IDs of an @ symbol, followed by a three-digit label ID and a number. This format worked well for the past 15 years, but the prefix was potentially limiting, especially to aid ISVs. Labels are no longer restricted to three digits, which helps Microsoft attain one of its goals of making ISV add-ons easier to write, maintain and adopt.

The choice of how many and which packages need a label file depends on the solution design.

It isn't a terrible idea for an end user customer solution to have one package just for labels that are re-used by each package. This does mean that we run the risk of using a label out of context. You may choose to use a standard label for Name on personal record, only for the label to be changed by the original developer to something specific to the original context, for example, Product name.

We tend to create a label file for each package as this ensures that the package can correct and change labels without worrying about regression in other Models.

Getting ready

To get started, open Visual Studio, and the project in question, in my case I will continue with the ConWHSGeneralExtensions project.

How to do it...

To create the label file, follow these steps:

1. Right-click on the project and select Add | New item... or use the keyboard shortcut, Ctrl + Shift + A.
2. Choose Labels and Resources from the Operations Artifacts list.
3. From the list on the left, select Label File.
4. In the Name field, enter a short, but unique label name, in my case ConWHS. I want it to be as short as possible, but be completely sure it will be globally unique, regardless of any future add-on we may choose to install.
5. Press Add.
6. In the Label file wizard, leave Label file ID as default.

It seems that we can specify a different name in this step, but the previous only called this wizard with a suggested file name. The Label file ID field contains both the ID and the file name that will be created.

7. Press Next.
8. In the language selection, move the languages from the left-hand list into the right-hand list using the buttons. Only leave languages selected that you will maintain. This involves creating a label in each language file.

This also applies to language with subtle differences, such as English and Spanish. Even though the label will often be the same, we still need to manually maintain each language file. Currently this also means we have to be careful to ensure we give them the correct ID.

9. Press Next.
10. Check that the Summary page is correct, and press Finish.

How it works...

The creation is straightforward. The process creates a text file on the disk that contains a tab-separated list of label IDs and translations.

When a label is selected against a control, it will be given a label file ID that ensures it is unique. In our example, the label file ID was ConWHS. As we create a label, it will be given the IDs in the sequence @ConWHS:ConWHS1, @ConWHS:ConWHS2, and so on.

In our example, the label IDs given to the control will be @ConWHS:ConWHS1. This seems needlessly long. Since, we can actually specify the label ID manually, we can choose to enter a shorter ID per label, generating a label such as @ConWHS:L001, or enter a memorable name as an ID, where the ID would then become @ConWHS:ItemNotExists.

There's more...

Currently, the maintenance of labels can be time consuming, in that, we do not have a translation list per label ID as we did in Dynamics AX 2012, but a separate file per language. This is targeted for improvement, and may change by release. The concept, however, will remain the same.

When writing labels for variants of the same or similar languages, we can copy and paste the labels between files. Expand the label file to the lowest node to the file with a .txt extension, and right click on it to select Open With.... Choose Notepad from the list.

Each label will have two lines, one for the label, and the other for the comment, as shown in the following extract from an en-gb label file:

ConWHS1=Vehicle type 
 ;ConWHS 
ConWHS2=The type of vehicle 
 ;ConWHS 
VehTransComplete=Complete inspection 
 ;ConWHS 
VehTransCompleteHT=Complete, and finalise the vehicle inspection 
 ;ConWHS 

You can than translate to the desired language and paste it into the target label file, again by opening the txt file in Notepad. You must do this from within Visual Studio, otherwise the file may not be checked out from source control. Be careful, as it will not validate that there aren't duplicates or file formatting errors.

If you intend to write add-ons, you should always maintain the en-us language file. You will get compilation warnings that the label ID does not exist, if you do not. If you are to release the software to a region with a variant of a language (en-au, en-gb, en-ie, en-us, and so on), please use the correct translation, as not only will it make your add-on more professional and global, but some terms have completely different meanings. For example, stock means inventory in en-gb, but means financial share holdings in en-us.