> ## Localizing Text

> When you insert label and text elements in a report, you typically type the text that you want to display. Use literal or static text if a report will always be viewed in one language or locale. If, however, a report will be translated into multiple languages, use resource keys rather than static text. The resource keys are translated, or localized, in resource files.

> If you are not familiar with resource keys or resource files, think of resource keys as variables, and resource files as text files in which the variables are set to their values. If a report needs to appear in four languages, you create four resource files to define text values for each language. When a report runs, BIRT uses the machine’s current locale, the resource keys, and the resource files to find the appropriate text value to display. Figure 21‑1 shows the functions of resource files and resource keys in a localized report.

> Figure 21 1 | Resource keys in resource files, the report design, and the report

> You can specify resource keys for the following items:

> n | Static text in label, text, and chart elements. For example, you can localize report titles, column headings, chart titles, and other static labels.

> n | Text values that come from a data set field. Data values of date or number type do not need to be localized. BIRT automatically displays numbers and dates according to the locale to which the report user’s machine is configured.

> n | Report parameters.

> #### How to assign a resource file to a report

> 1 | In the layout editor, select the report by clicking in an empty area on the report page.

> 2 | In Property Editor, choose Resources. Property Editor displays the Resources page, as shown in Figure 21‑2.

> Figure 21 2 | Property Editor displaying the Resources page

> 3 | Choose Add, next to the Resource File field.

> 4 | On Browse Resource Files, indicate which resource file to use by completing one of the following tasks:

> n | To use a resource file that currently exists in the resource folder, select the resource file displayed under Resource Folder.

> n | To create a new resource file using BIRT Report Designer, select Resource Folder. In New File Name, type a name for the new resource file, such as CustomerReportResources.properties, as shown in Figure 21‑3. You must type the .properties file‑name extension.

> Figure 21 3 | Browse Resource Files showing a new resource file

> 5 | Choose OK.

> The name of the resource file appears in Resource File on the Resources page of Property Editor. The report uses the selected resource file. You can, at any time, specify a different resource file to use. You can also specify no resource file by deleting the file name from the Resource File field on the Resources page.

> #### How to assign an existing resource key to a label or text element

> 1 | In the layout editor, select the label or text element that you want to localize.

> 2 | In Property Editor, choose Localization, as shown in Figure 21‑4.

> Figure 21 4 | Property Editor displaying the Localization page

> 3 | Choose the ellipsis (...) button that is next to the Text key field. This button is enabled only if you have already assigned a resource file to the report. Select Key displays the current list of keys and values that are defined in the resource file that the report uses, as shown in Figure 21‑5.

> Figure 21 5 | Select Key

> 4 | Select the key to assign to the label or text element, then choose OK. In the layout editor, the label or text element displays the value that corresponds to the key.

> #### How to preview a report in a different locale

> 1 | Choose Window->Preferences. Figure 21‑6 shows Preferences as it appears in BIRT Report Designer. If you are using BIRT RCP Report Designer, Preferences displays only report design options and not the Eclipse options.

> Figure 21 6 | General preferences in BIRT Report Designer

> 2 | On the left side of the dialog, expand Report Design, then choose Preview. The preview properties appear, as shown in Figure 21‑7.

> Figure 21 7 | Preview preferences in BIRT Report Designer

> 3 | Under Choose your locale, select a locale in which to preview your reports, then choose OK. The locale that you select applies only to previewed reports. It does not change the locale that your machine uses, nor does it change the localized text that appears in the report design.

> 4 | Preview the report. The localized text appears in the language for the locale that you selected.

> 5 | To preview your report in another language, repeat the previous steps to select a new locale.

(c) Copyright Actuate Corporation 2008