XPages: How to use the localization options 

This article will show how to localize your XPages applications into multiple languages, using translated .properties files for each XPage, Custom Control or Resource File.

The general process is as follows

1. Configure the list of supported locales in the Application Properties (Section 1).
2. Export your Source language (English) .properties and send them to the translators (Section 2).
3. Then import your translated .properties files for the listed locales using the steps below (Section 3).
4. Or for testing purposes, you can automatically create language versions of the files, until your real translations are available (Section 4).
5. Section 5 provides details of the extracted values. Section 6 is things to note.

How it works

XPages uses .properties files for translated text.

• Property files are the standard Java translation mechanism, so it is a common format translators would be familiar with.
  A property file contains entries like "key1=Localized text".
  Translations of the same .properties file in different languages are grouped as a bundle. For example, you could have a bundle named "strings" which includes the files
  
  • string.properties
  • strings_fr.properties
  • strings_de.properties
  where "fr" is the locale code for French and "de" is German. The different files in a bundle use the same key for translations of the same text. The current locale is used to determine which property file to read, so you can access the bundle to find the text for a key without worrying about the locale of the text.
• The steps to use property files in Java(tm) are as follows (the XPages steps are below).
  
  • First extract all localizable text into a .properties file.
  • Then use keys to get text values from the bundle, at every location where you need to display localized text.
  • Finally provide translated copies of the .properties files so that the bundle supports multiple languages.
• The properties file format uses an encoding scheme for reserved or non-ascii characters, which is important for many languages. Such encoded text looks like:
  

  label1/@value=\u0627\u0644\u0639\u0631\u0628\u064a\u0629

• For more information about .properties files, search the internet for "ResourceBundle", or read the API documents for the java.util.Properties load method.

In XPages, the process for putting text in properties files is simpler than in Java(tm).

• Localizable text and labels are first entered normally in Domino Designer, the same as non-localized values.
• Then you enable localization to produce the .properties files to send for translation.
• A build process takes care of extracting the text into property files and using those keys when compiling the XPage.
  
  • Some text is not extracted automatically. Details of which text is extracted to .properties files are in Section 5 below. Follow the steps in the "JavaScript Internationalization" document to manually extract any other text.

All .properties files are "compiled in" to your XPages, including the translated files. Therefore, at run-time it does not load the .properties files nor look up the values for the keys. This does mean that when you make changes to the property files, you have to rebuild the XPages in Designer, and the XPages will be re-signed. On the other hand, the "compiled in" behavior is highly optimized, so that the application does not run slower when localized.

XPages will usually use the best match between the user's browser locale and the supported locales list, using the default locale if there is no match. If preferred, the Application may programmatically force a certain locale. For more on the locale choosing mechanism, see "Locale use in XPages".

Section 1: Add support for different locales to your Application

1. Open the Application Properties, XPages tab, by selecting your Application in the Application View in Domino Designer and selecting "File", "Application", "Properties". Switch to the XPages tab.
2. Check the check box under Localization Options. In 8.5, it was labeled "Create property files for text localization". In 8.5.1, it is labeled "Enable localization".
3. Click the Add button. Add languages you wish to translate into, and add the language used to create the Application.
   
   • In the supported language list you should select the main language, like "French", rather than country variants like "French (France)". However if you want two French translations, use a variant for one of them. Choose one of the languages to be the main translation, select French from the language list and use the French property files for the main language. Then add the other French language to the list too, like "French (Canadian)", and put the other translation's in the "French (Canadian)" property files. That way if you have a user who is "French (Belgium)" they will get the French strings, instead of the default language.
4. Select your Source language, the language used to create the XPages. In 8.5 this option was labeled the "Default language".
   
   • The Source language is the language the original XPages and Custom Controls were written in. Selecting a Source language means that the .properties files created for this language will be the main .properties files for the application, i.e. the .properties files created will be of the format XPageName.properties, rather than XPageName_en.properties. The content of those files will be automatically extracted from the XPages, rather than provided by translators.
5. In 8.5.1 or later, for the Default language option, the initial value of "Use source language" is usually correct.
   
   • This configures the language displayed when the user's browser is in an unsupported language, not in the supported languages list. It defaults to the source language, on the assumption that the application developer's language is probably the language of most users of the application, and the language of most documents in the application. Change this setting if developing an application for users who use another language. This option is new to 8.5.1, as in 8.5 the option labeled "Default language" was the language used to create the XPages.
6. Prevent modification of existing property files.
   
   • In 8.5, check the check box "Do not modify Existing Properties Files".
     In 8.5.1, uncheck the check box "Merge source file changes into property files".
     See Section 4 for more details about these options.
7. The options look like so
   

   • In 8.5	In 8.5.1

8. Save the Application Properties.
   
9. Select the "Project" menu, select Clean and then select "Clean all projects" in the dialog, then click OK.
   (Note: Project, Clean will re-sign all the XPages and Custom Controls)
   This will create property files for each of the XPages and Custom Controls in your Application.
   
10. Open the Navigator view to review the created property files. In the menu "Window", select "Show Eclipse Views", then "Other...". Select General, Navigator, click OK.
    The property files will be in the folders XPages, CustomControls, and possibly in Resources/Files if it was necessary to follow the JavaScript Internationalization instructions.
    

Section 2: Export property files for translation

If you are still doing initial investigation of localization, you should skip to Section 4 instead of following these instructions for sending the files to translators.

1. Right-click on the Application root in the Navigator view, select Export... Choose General, File System. Click Next.
   [See Section 1, step 10 for the Navigator view.]
2. Uncheck the check box beside the Application, then toggle the Application open, and select only the check boxes for the properties you want translated,
   
   • e.g. XPages, CustomControls and Resources/Files. Select Resources/Files only if you have created extra .properties files for JavaScript etc. See the document on "JavaScript Internationalization".
3. Click Filter Types, select the check box beside *.properties, click OK.
   
4. Click the "Browse" button, select a folder to export to (e.g. Desktop/toTranslate).
   
5. Select the radio option "Create directory structure for files". Click Finish
   
   • 
6. Send these files out for translation.
   Each language .property file should be of the form: xpage_fr.properties.
   

Section 3: Import property files back into the Application

1. Open the Application Properties by selecting your Application in the Application View in Domino Designer and selecting File, Application, Properties.
   
2. Select the XPages Tab. Make sure the application will not modify your translations after import. (This is important)
   In 8.5, check the check box for "Do not modify Existing Properties Files". In 8.5.1 or later, uncheck the check box "Merge source file changes into property files". Save and close.
   
3. Browse to the Application sub-folder in the folder exported to (e.g. Desktop/toTranslate/myApplication). Click OK.
   
4. Check the check box beside the Application name.
   
5. Click "Filter Types", select the check box beside *.properties, click OK.
   
6. Select the radio option "Create selected folders only".
   
7. Click "Finish". When it asks to Overwrite, click "Yes To All".
   
8. Select the "Project" menu, select Clean and then select "Clean all projects" in the dialog, then click OK.
   

If you look at the XPages or Custom Controls folders for your Application in the Navigator it should look like this:

When you open the Application through a Browser with the language set to one of the languages you added, the Application will appear with that language.

Section 4: Automatically create language .properties files

This option creates a version of the .properties files for each language, which will have the locale code before each piece of text. The Application designer can check before translation that all strings are available to be localized. If the Application designer is translating the files, they can be edited directly in Domino Designer.

1. Follow the steps in Section 1 to prepare your application for localization, then re-open the Application Properties, XPages tab.
   
2. Allow modification of the translated files.
   
   • If you have already translated your application, caution is advised at this stage. Create another backup copy of your translations, by following the export steps in Section 2.
   • In 8.5, uncheck the check box "Do not modify Existing Properties Files".
     
     • Please note, if you uncheck this check box, any translations you had previously created will be overwritten.
       The existing property files are deleted and new copies are made containing the language code and the untranslated text from the source XPage.
   • In 8.5.1, check the check box "Merge source file changes into property files".
     
     • Please note, if you check this check box, any translations you had previously created may be overwritten.
       This option is usually less destructive than the 8.5 option. It attempts to merge the changes to the XPages into the translated property files, so that if text is unchanged it will probably remain translated. Translated text that is now unused will be moved to comments at the top of the translated files. If moving existing applications from 8.5 to 8.5.1, it may match some translated text with the wrong untranslated source value, leading to inaccurate processing of the translated files. In that situation, you should import your backup copy of the translated property files and the corresponding old untranslated property files.
3. Save the Application Properties.
   
4. Select the Project menu and then Clean to rebuild the Application.
   

Now when you open the Application through a browser, with language set to one of the languages you added above, you will see the Application with the language code around each localized phrase. Each XPage and Custom Control in the Application will now have a property file for each language selected in the Application Properties.
e.g. Source language here is English, Browser language is English

e.g. Source language here is English, Browser language is Finnish

Editing property files in Domino Designer.

1. To see the property files, open the Navigator view (see Section 1, step 10).
2. Browse to the property file corresponding to your XPage. The files to be translated have a suffix with "_" and the language code.
   They will be in the XPages folder, the CustomControls folder, and possibly in the Resources/Files folder.
3. Double-click on the property file to open it in the editor.
4. Edit the values after the equals(=) symbols. The translations you provide do not need the "[fi| ]" prefix and suffix.
5. Save the changes to the editor. The corresponding XPage will be regenerated automatically; you do not need to do the Project - Clean step when editing an individual property file.

Section 5: Extracted values

Not all values in an XPage or Custom Control are extracted, only those that are expected to be a label or localizable text.
The following are extracted:

• In-line text.
  Text typed into the Design tab of the editor, appearing within and between controls, is extracted to the .properties files. However, it is usually better to replace such text with Label controls. The reason is that the key used for in-line text is tied closely to the location of that text in the file. So if you want to change the layout of an XPage after the .properties files are sent for translation, that could alter the key, and waste effort by the translators.
  
  For example, the text in a page might be extracted as:
  

  /xp\:view[1]/text()=Some text

  
  If you then decided to place the text in a panel, that would change the key of the extracted text to:
  

  /xp\:view[1]/xp\:panel[1]/text()=Some text

  
  Use of the Label control avoids this issue because the name of the control is used in the key, like so:
  

  label1/@value=Some text

  
  That means you can move label1 within the page and the key remains the same.
• Values of localizable properties.
  If you type text into the Label field of a Button, it will be extracted to the .properties files because of how the Button control is defined. If you look at the All Properties tab of the Button, you'll see that the value typed into the Label is available in a property named "value". [The properties in that tab store the information on how you have configured the control. For example, if you check the "Disabled" check box in the main Button panel, the "disabled" property will be set to "true".] The Button "value" property was defined as localizable, so your label is extracted to the .properties file. [Conversely the "true" value is not extracted to the .properties file because the "disabled" property was not defined as localizable.]
  If you are curious, you can tell which properties are defined as localizable by typing some text into any property in the All Properties tab, saving the XPage, and checking whether that text appears in the extracted .properties file. You can double-click on a .properties file in the Navigator view to see its contents.
  

If you are defining your own Custom Control, you may want the XPage that is using the control to pass in a localizable string.

• In the Property Definition tab of the Custom Control, select the property (like mainTitle), and in the Type combo box, select "Localizable String".
  When the property mainTitle is set to a value in the XPage that uses the Custom Control, that value will be extracted to the XPage .properties file.

Computed values are not extracted to .properties files. See the document on "JavaScript Internationalization" if you need to compute localized values.

Section 6: Things to note

1. It is always advisable to keep a backup of your translated .properties files.
2. If there is no equivalent property file for the language selected in a browser then the Default Language will be shown.
3. Once the language .properties files have been created in the Application, you can make changes to the language files from the Navigator view, by double-clicking on the files to open them in an editor.
4. When a Custom Control property of type "Localizable String" is set to a value in the XPage that uses the Custom Control, that value will be extracted to the XPage .properties file.
5. Computed values are not extracted to .properties files. See the document on "JavaScript Internationalization" if you need to compute localized values.
6. If you created an extra .properties file in Resources\Files (following the JavaScript Internationalization instructions), and automatically create the language .properties files, then language versions of the extra .properties file will not get created. This step must be done manually for .properties files not associated with an XPage or Custom Control.
7. You can disable localization for a localized application.
   
   • First ensure you have a backup of the translated text (see the export instructions in Section 2).
   • In 8.5, if you uncheck the "Create property files for text localization" option, and do a Project - Clean, all the .property files will be deleted.
   • In 8.5.1 and later, if you uncheck the "Enable localization" option, you'll get a dialog asking if you want to Delete the property files.
   • If you allow the files to remain, they will be ignored and not used in the XPages. Do a Project - Clean to rebuild all the XPages without localization.
8. In 8.5.1, if the Merge option is disabled and you change the text in some XPage, you will get a warning in the Problems view.
   The warning is like so:
   
   "XPage localization property files are out of date. For example, in /page1.properties the value is incorrect for the key label1/@value. You can correct this by re-enabling the Merge option in Application Properties (XPages tab, Localization Options)."
   That warning indicates that the property file contents do not match the XPages. In that situation, the contents of the property files will not be used for the out of date values.
   "[de| text ]" will be displayed in the browser, using the locale code and the text from the XPage. "[| text ]" is displayed when opening the page in the source language.
   To detect this situation, the values in the XPage source are compared to the text in the main property file. It also occurs if you delete values from the translated property files.