Localizing Project.net into Another Language
Project.net is designed to be re-branded to fit a user's installation; the product's name, logo, URLs, and the tools available to users are a few of the customizable options. If you are interested in customizing or branding Project.net, please refer to Customizing Project.net.
Project.net also supports localization, a method of changing text and images to a local language. The process of localization enables a Project.net administrator to customize the appearance of Project.net by translating the language of the menu items, buttons, images, and text. If an end user chooses that language in his or her user profile then Project.net will use that translation. The default installation of Project.net uses English text and images.
This document explains how to create a local language package and change Project.net’s user interface into a local language. It will also cover how to submit a translation for consideration as an alternative language pack so others can use it with their copies of Project.net.
 Branding vs. Localization
The benefit of a highly-configurable application such as Project.net is that you can customize it to function in the manner that is most efficient for you and your organization. Such customization streamlines operations, allowing you to focus on your projects, not your project management software.
There are two main types of customization: branding and localization. Branding is making the application unique to your organization. Two examples of branding are adding your company’s logo to every page, or using company-specific terms for the tools in Project.net. Branding can include a unique URL for the login page such as http://yourcompanysname.project.net, or setting the various email addresses used by the system, like administrator, support, and feedback. Branding is covered here: Customizing Project.net.
Localization, on the other hand, involves customizing the display language of Project.net. Changing the text to French is an example of localization. Unlike branding, which is specific to your organization, a language translation is universal and easily shared among other Project.net users and their installations.
 Built-In Supported Languages
Project.net lists the following languages: English, French, German, Italian, Japanese, and Spanish. The default installation now includes the English language package, and will include the others as people contribute language packages for those languages. If you would like to experience a Project.net server with alternate languages see the section on the Project.net Localization Server.
 Adding a New Language
If you need to create a language package for a language other than the ones listed above, please contact firstname.lastname@example.org for assistance. It is possible to add additional languages to this list for an existing installation.
 What Can Be Localized
Many aspects of Project.net can be localized, such as logos, text, menus, icons, and the content of notification email.
 Tokens and Configurations
In order to start the localization process, you must first understand what a token is and what it does. Tokens are settings that control most of the visible text and images in Project.net. Each token is responsible for the configuration of one object. These tokens are stored in named configuration sets. For example, if you want your company’s name and logo to appear on the Project.net login page, you would change the values of two specific tokens, one for the company name and one for the logo.
All of the current tokens in Project.net are in English. In order to translate the application into other languages, alternate tokens values must be created for each object. For example, there is a token for the “Documents” menu item. In order to localize Project.net into Italian there needs to be an alternate value for that token which specifies “Documenti”, the Italian equivalent of “Documents”. Project.net checks a user’s language setting to decide whether to use a token’s alternate value.
Project.net stores its tokens in sets called configurations; when a configuration is active, Project.net will use values from the tokens in that configuration. Note that Project.net can have more than one active configuration - which configuration is selected for a user is determined by the URL or IP address he or she used to access the Project.net server. For example, users accessing the server through projects.mycompany.com may see the results of the default configuration, while those using custom-projects.mycompany.com could see a site customized by an alternate configuration. Any token not set in a configuration will get its value from the default configuration.
Language packs shipped with Project.net will add alternate token values for the default configuration. If you plan to submit your translation as a language pack it is easiest to create it as an alternate language for the default configuration. If you do not expect to submit a language pack you can set up your language using either the default configuration or your own non-default one. The disadvantage of using the default configuration is that it will be overwritten whenever you upgrade to a newer version of Project.net, requiring you to reload your language package. This does not apply to language packs that have been submitted and included in the Project.net distribution.
 Overview of the Localization Process
There are two ways to get a language-specific version of a token into Project.net: edit the token value directly from within Project.net or extract the tokens to an external file, perform the translation there, and then reload them into the system. These methods are referred to as translate in-place and translate externally respectively.
You can use the translate in-place method whether you are working with the default configuration or your own non-default one. However, translate externally is only available if you are creating a language pack for the default configuration. Translating in-place is recommended when you have a few changes or corrections to make; most likely you will want to translate externally for your initial translation due to the size of the message file.
The localization process consists of four main steps, which will be discussed in more detail later in this document. The steps to localize Project.net are:
- Determine what text and images to translate within the application
- Text within Project.net, such as menu items
- Text outside of Project.net, such as email notifications
- Any language-specific images within Project.net
- Translate in-place or externally
- Verify translation
- Submit translation for consideration as an alternative language pack
 What to Localize
The first step of the localization process is to determine which aspects of the application can be configured through the use of tokens. You can download Image:LocalizationTokens-v913.zip, which contains the text tokens and their English values. This dual listing allows you to easily search for the token you wish to translate, for example, if you search for "Member Login" you will see its token is prm.project.login.login_header_text-1.
 The Project.net Localization Server
A better option is to use the Project.net localization server, which is a Project.net server where each token has its own name as its value. Go to the login page at http://localization.project.net and select Token Values from the Language menu in the top right corner. Notice, that what formerly said "Member Login" now says prm.project.login.login_header_text-1, the name of its token. By using this option you can look at any text in the user interface and tell which token contains that text. Notice, too, that you also have the choice of other languages, like German, Italian and Spanish, in addition to English and Token Values.
You will need create a user account on the localization server before you can login. Start with the Register to create a new account link on the login page. Make sure that you:
- use a valid email address because the server will email a verification code to you, and
- select System Default License Key when asked to enter a license.
Once you receive the verification code and verify your account you will be able to login to the localization server. Again, you can choose the desired language from the drop-down menu on the login page.
 Localizing Text
The localization process is slightly different depending on whether the token you are localizing is a token for text or an image.
 Translating Token Values In-Place
You can use translate in-place whether you are working with the default configuration or your own non-default one. Translating in-place is recommended when you have a few changes or corrections to make or if your translations will be stored in a non-default configuration. A non-default configuration is preserved when Project.net is upgraded to a newer version; however, translations stored in non-default configurations cannot be submitted for consideration as a language pack.
To translate in-place:
- Login to your Project.net server as a user with application administrator privileges.
- Go to the Application Administration module and choose [Configurations].
- From the list of configurations, choose the configuration that will hold your translation, either the default configuration or your production configuration. Note, if you do not know what a configuration is or which one to select read the first part of this document.
- Modify the properties of the chosen configuration and add your language, for example Spanish, to the list of Supported Languages.
Now select [Tokens] and go to the Edit Tokens page. From this page:
- Choose your language (in this example Spanish) from the language drop-down menu under “Brand Settings.” This will let you see the localized token values for this language in this configuration. For example, if a user selects Spanish as the language in his or her personal profile, that user will see the Spanish token values you have specified. Likewise, anyone logging in with English as his or her language preference will see the English token values.
- Search for the token you selected from the list (e.g. login.login_header_text-1). Notice that the column with the configuration value is marked with (es), which signifies that you are altering the Spanish value of the token. The languages have the following codes:
- English (en)
- French (fr)
- German (de)
- Italian (it)
- Japanese (ja)
- Spanish (es)
- Enter the localized text into the last column and click [Submit Changes].
Continue to localize the remaining tokens in the manner described above, being sure to remain logged in as an application administrator. After you have translated a few of your tokens you should verify them by following the steps in section “Verifying Your Translation”.
 Translating Token Values Outside of Project.net
An alternative to editing token values directly from within Project.net is to extract the tokens to an external file, perform the translation there, and then reload them into the system. Project.net provides a tool for doing just this. Remember, this process only applies to the default configuration.
- Use the token extraction tool to export the existing defined tokens to an Excel spreadsheet file (or use the current Image:LocalizationTokens-v913.zip file). These tokens will come from the default configuration. If this is your first export the file will only contain the English (en) values for the tokens. If you have translated any tokens in-place or have previously imported a non-English language this file will contain those values as well. The examples in these instructions assume English is the only existing language.
- Open the Excel file. Inside you will see columns for token name, value, language code, and if the token is tagged as translatable. Note, at this time the isTranslatable tag is for your information only.
- Search for the token you wish to translate. First, change its “Language” tag to the appropriate value. If you need to create a language package for a language other than the ones listed, please contact email@example.com for assistance. It is possible to add additional languages to this list for an existing installation.
- In the “Token Value” column translate the English text into your local language. Project.net supports all UTF-8 character sets. Do not forget to change the token's “Language” tag. When you are finished, save the Excel file.
- Follow the instructions for the token extraction tool to import the translated tokens back into the default configuration. If this is the first import, the translated tokens will be added to the database, if some already exist they will be updated from the file.
- Restart the Apache Tomcat server.
To see your translated values continue below:
- Login to your Project.net server as a user with application administrator privileges.
- Go to the Application Administration module and choose [Configurations].
- From the list of configurations, choose the default configuration.
- Modify the properties of the default configuration and add your language, for example Spanish, to the list of Supported Languages. Save your results.
- Next, select [Tokens] and go to the Edit Tokens page.
- Choose your language (in this example Spanish) from the language drop-down menu under “Brand Settings.” This will let you see the localized token values for the default configuration. Note, the English default values will be there as well. If a user selects Spanish as the language in his or her personal profile that user will see the Spanish token values you have specified. Likewise, anyone logging in with English as his or her language preference will see the English token values.
- Search for one of the tokens you imported from the Excel file (e.g. login.login_header_text-1). Notice that the column with the configuration value is marked with (es), which signifies that you are viewing the Spanish value of the token.
- Again, you can use these last few steps if you only need to make changes to a few tokens.
 Important Information about Project.net Updates and Translations
If you saved your translation in the default configuration you will need to preserve a copy before upgrading your Project.net server and then restore the copy after the upgrade. During an upgrade the default configuration is overwritten, which will erase your translation. You must save an external copy and restore it after the upgrade. You can do this with the token extraction tool. This does not apply to language packs that have been submitted and included in the Project.net distribution.
 Localizing Language-Specific Images
You can replace most of the images used in Project.net through a combination of tokens and the use of a Apache Tomcat Virtual Directory. Alternate or customized images are placed in a virtual directory and their language-specific tokens changed to refer to this directory. At runtime, Project.net will use the images in the virtual directory rather than its default image directory. Unless you plan to modify the Project.net source JSP pages, the replacement images must be the same size as the originals.
Common images replaced in Project.net are:
Choose a file system location to hold your replacement images (ex. C:\pnet\lang\<language code>\, /opt/pnet/lang/<language code>, etc). It is suggested that you create a sub-directory for each Project.net language.
Determine which image you want to replace and its size. From within a browser, right-click on the image and select “Properties” from the pop-up menu. From the properties dialog, look at the “Address (URL):” entry and note the name of the image, which appears at the end of the URL. Also record the size of the image, listed in the “Dimension” field. For example, the Project.net logo on the login page is named “pnet_logo2.gif” and is 165 pixels wide by 90 pixels tall. Create a replacement image the same type and size as the original. Save it to the directory you created.
 Adding Static Resources via a Tomcat Context Resource
Since you are using the Tomcat application server you can substitute static resources, such as a custom image, through a Tomcat context. The use of a context enables you to substitute customized images for Project.net's images without touching the Project.net EAR file. To do this, complete the following steps, which assume the alternate image is named mycompanyLogo.gif and is stored in a directory named /opt/pnet/lang/<language code>/. Substitute the directory and filename as appropriate for your system.
- Within APACHE_HOME/conf/Catalina/localhost/ create the following file named “conf-data.xml” (The value for docBase is the path to the base directory that will hold the alternate image.)
<Context path="/conf-data" docBase="/opt/pnet/lang" debug="1" reloadable="true" crossContext="true"> </Context>
- Restart Tomcat.
- Login to Project.net as an Application Administrator.
- From within the Application Administration interface, chose “Manage / Configurations.”
- Click on the name of configuration containing the translations (default or non-default) from the list of configurations.
- Choose “Tokens” from the menu on the left.
- Search for the token named “prm.project.login.pnet_logo2.”
- Change its value to “/es/spanishCompanyLogo.gif.” This path name is relative to the directory listed as “docBase” in conf-data.xml.
- Apply the settings.
- Logout of Project.net. You will see your logo in the upper left of the login page.
Troubleshooting: If your translations are contained in a non-default configuration and you still see the Project.net logo, it is likely that the default configuration is being selected over your alternate one. If so, right-click on the logo and select “Properties” from the pop-up menu; from the properties dialog look at the “Address (URL):” entry. If it does not have the image file you defined in the prm.project.login.pnet_logo2 token then your configuration is not being selected. This is often caused because of a missing or incorrect hostname in the configuration’s “Supported Hostnames” field.
If the logo is missing (i.e. an icon with a red X is displayed instead) look at the image properties to see what image should be displayed. Check for typos in the name. If the name and path is correct, double-check conf-data.xml. Do not forget to restart Tomcat after changing this file.
 Localizing Email Notifications
The contents of email messages are contained in tokens, the same as text display in the user interface. Please be aware that when Project.net sends email, it does not know the desired language of the recipients and, therefore, may not send localized messages to all recipients.
 Verifying Your Translation
Once you have reloaded the localized tokens back into Project.net, test your new configuration to ensure that the new tokens are correct. It is recommended that you login to the server using a user account that has the desired language set in its profile (in this case Spanish). The user should see the text you localized displayed in the user interface.
You want to make sure that all aspects of Project.net are labeled correctly in the language you localized. Images should not be cropped or of poor quality. Once you start testing your localization you might find additional tokens that need be translated. Repeat the steps above until you are satisfied that the localization is complete and accurate. To change a few tokens, translating in-place is the recommended method.
 Submitting your Language Pack
When completed, your localized text, images, and email templates can be submitted for consideration as one of the alternate languages included as part of the Project.net installation. If your localization is accepted, Project.net will bundle your translation with the Project.net software distribution as an “Alternative Language Pack.” This means that other members of the Project.net community will be able to benefit from the increased usability and functionality that comes with using the application in their preferred language.
When you are satisfied with your translation, send an email to firstname.lastname@example.org for information regarding packaging your work and delivering it to the development team, where it will undergo review. It will also be sent to Project.net community members for further verification. Once a translation has been accepted as an alternative language pack, it will become part of the Project.net distribution.
 Where to Get More Help
If you have any further questions about the localization process, please email email@example.com or post your question to the Project.net community at http://www.forums.project.net.