Salesforce: Spring '11

Localizing with the Force.com IDE

Last updated: April 10, 2011

Copyright 2000-2011 salesforce.com, inc. All rights reserved. Salesforce.com is a registered trademark of salesforce.com, inc., as are other

names and marks. Other marks appearing herein may be trademarks of their respective owners.

Table of Contents

Table of Contents
Localizing with the Force.com IDE......................................................................................................1
Introduction..............................................................................................................................................................................1 Creating a Force.com Project....................................................................................................................................................1 About package.xml....................................................................................................................................................................4 Where Are My Translated Components?..................................................................................................................................5 Translating Custom Fields for Standard Objects......................................................................................................................7 Translating Custom Objects......................................................................................................................................................8 Languages..................................................................................................................................................................................9

Table of Contents

ii

LOCALIZING WITH THE FORCE.COM IDE

Introduction
The Translation Workbench in Salesforce allows you to translate all your customizations so that users can work in the language that they choose. The Translation Workbench can manage translated values for any language that Salesforce supports. For the list of supported languages, see Languages on page 9. If you have a large amount of customizations and you support users in many languages, the point-and-click interface of the Translation Workbench can be time consuming for managing all these translations. The Force.com IDE can offer great time savings by allowing you to work with your translations in XML files and use a simple interface to load the translations into Salesforce easily. The Force.com IDE is a plug-in for the Eclipse IDE that provides special help for developing and deploying customizations, including translations of customized content, in Salesforce.

Installing the Force.com IDE

For details about installing and getting started with the Force.com IDE, see wiki.developerforce.com/index.php/Force.com_IDE.

Prerequisites
Before you can use the Force.com IDE to manage translations, you must ensure that the following criteria are satisfied: Translation Workbench is enabled for the user associated with your Force.com IDE project. For more information about enabling the Translation Workbench, see Setting Up the Translation Workbench in the Salesforce online help. The languages for the translations that you are managing are active. For more information, see Adding and Editing Translated Languages and Translators in the Salesforce online help. You have login credentials for a Developer Edition or sandbox organization to test your localizations. Note: The Force.com IDE is a free resource provided by salesforce.com to support its users and partners, but is not considered part of our Services for purposes of the salesforce.com Master Subscription Agreement.

Creating a Force.com Project

To create a Force.com project, use the New Force.com Project wizard. 1. To open the wizard, select File New Force.com Project. Note: If you do not see the menu item for File New Force.com Project, you are not using the Force.com perspective. You can still create a Force.com project without using the Force.com perspective by selecting File New Other Force.com Force.com Project; however, you should use the Force.com perspective because it includes other views and features that aid development. To activate the Force.com perspective, select Window Open Perspective Other Force.com Perspective. 2. On the first page of the wizard, enter the connection settings for your organization, as listed in the table below:

Localizing with the Force.com IDE

Creating a Force.com Project

Field
Project Name

Description Required. A project is associated with one organization. Although you can enter any name here, we recommend you append the username you use to log into the organization associated with this project (home organization). For example, if you logged into an organization with the username mary_jones@mycompany.com, we recommend using myProject_mary_jones@mycompany.com for the project name. Because you are likely to create multiple projects on multiple organizations, it is important to be able to clearly identify the project with the organization it represents. Project names must be unique. You can create more than one project that connects to the same organization, but they cannot have the same project name.

Username

Required. The username you use to log into the home organization, the organization associated with this project. The username associated with this connection must have Modify All Data permissions on the associated profile. Typically, this is only enabled for System Administrator users. Required. The password for the specified username. The security token is appended to your password as an added security measure. If you are using a security token, enter the value here. For more information, see the Salesforce online help topic Setting Login Restrictions. Choose the appropriate environment for your connection: Production/Developer Edition - Choose this option if you are connecting to a production or Developer Edition organization. Sandbox - Choose this option if you are connecting to a sandbox organization. Sandbox organizations have an URL that starts with test. Pre-Release - Choose this option if you are connecting to a prerelease server. Other (Advanced) - Choose this option if you want to connect to a specific instance. This option is only available if you have chosen Other (Advanced), in the Environment field above.The Hostname field allows you to specify or enter a specific server instance. Choose this option if you want to keep the endpoint unchanged for this project. This option is for specialized

Password Security Token

Environment

Hostname

Do not change endpoint

Localizing with the Force.com IDE

Creating a Force.com Project

Field

Description cases, so unless you know that you need this, leave the checkbox cleared.

Timeout (sec)

If you experience timeouts before all the items in your project can download, you can reset the timeout from a minimum of 3 seconds to a maximum of 600 seconds. This is not usually necessary unless your project requires an long-running server communication. For example, if you had a long-running test, more than 50 components, or very large or complex components, you might consider adjusting this value. If you reach the maximum limit, you will be prompted to continue or abort. If you connect through a proxy, use Eclipse's proxy settings. In Eclipse, click Window Preferences General Network Connections.

Proxy Settings

3. When you have entered all the connection information, click Next. 4. On the second page of the wizard, click the Selected metadata components option and click Choose. 5. Select the objects - custom, objecttranslations, and translations options and click OK.

Figure 1: Selected Components 6. Click Finish to retrieve the specified components. Note: The project contents selections you make in the New Force.com Project wizard are used to create the package.xml file, which controls which components from the server are downloaded into your project. The easiest way to add or remove components from a Force.com project is to open the Project Properties and go to Force.com Project Contents, but in special cases you may want to edit this file by hand. If you manually edit package.xml, right click on your project name and click Force.com Refresh from Server to retrieve an updated set of components.

Localizing with the Force.com IDE

About package.xml

About package.xml
The package.xml file, also known as the project manifest, is a control file that determines the set of metadata components to retrieve or deploy in a project. In practice, it is much easier to use the Project Properties dialog to add or remove components from a projectwhich modifies package.xml for youbut it is also possible to edit package.xml by hand. The following XML elements may be defined in src/package.xml: Name
<fullName>

Description Optional. The name of a server-side package associated with the project. If the <fullName> field is present, all components in the package will be downloaded into the project, and new components created from the IDE will be added to that package. This element contains one or more <members> tags and one <name> tag, and is used to list the metadata components of a certain type to retrieve or deploy. The full name of a component. There is one <members> element defined for each component in the directory. You can replace the value in this member with the wildcard character * (asterisk) instead of listing each member separately. This is a child element of <types>. Contains the type of the component, for example CustomObject or Profile. There is one name defined for each component type in the directory. This is a child element of <types>. The Metadata API version number of the files being retrieved or deployed. When deploying, all the files must conform to the same version of the Metadata API.

<types>

<members>

<name>

<version>

The following sample package.xml manifest file works with all custom object translation and custom fields for the Account object, as well as custom applications, custom labels, Web links defined in home page components, custom tabs, report types, and s-controls.
<?xml version="1.0" encoding="UTF-8"?> <Package xmlns="http://soap.sforce.com/2006/04/metadata"> <types> <members>Account</members> <members>*</members> <name>CustomObject</name> </types> <types> <members>*</members> <members>Account-en_US</members> <members>Account-fr</members> <name>CustomObjectTranslation</name> </types> <types> <members>*</members> <name>CustomApplication</name> </types> <types> <members>*</members> <name>CustomLabels</name> </types>

Localizing with the Force.com IDE

Where Are My Translated Components?

<types> <members>*</members> <name>CustomPageWebLink</name> </types> <types> <members>*</members> <name>CustomTab</name> </types> <types> <members>*</members> <name>ReportType</name> </types> <types> <members>*</members> <name>Scontrol</name> </types> <types> <members>*</members> <name>Translations</name> </types> <version>21.0</version> </Package>

In the CustomObjectTranslation type above, the objectName-localeCode syntax in the <members> field where objectName is the name of the object, such as Account, and localeCode is the name of the locale code, such as en_US or fr. Note: The wildcard (*) symbol identifies all components for the <members> metadata type. The wildcard symbol does not work for standard objects, such as Account. The objectName-localeCode syntax is used in the <members> field, where objectName is the name of the object, such as Account, and localeCode is the name of the locale code, such as en_US or fr.

Where Are My Translated Components?

Like most integrated development environments, the Force.com IDE organizes application resources into containers called projects. Unlike traditional software development projects where source code is compiled to create runnable applications, the resources in a Force.com project live within a Salesforce organization and are copied into the local project for editing. The src folder contains all of the metadata components in your project. Metadata components are organized into different sub-folders depending on their type. The following image shows a Package Explorer view of the src folder for a project.

Localizing with the Force.com IDE

Where Are My Translated Components?

Figure 2: Translation Folders The following table lists the folders of interest for translations. Folder
objects

Contents Custom objects Standard objects Note: Standard objects cannot be retrieved with the wildcard (*) symbol, but must be explicitly named in package.xml. Only custom fields and standard picklist fields for standard objects are retrieved.

objectTranslations translations

Custom object translations This folder contains translations for the following components: Custom applications Custom labels Web links defined in home page components Custom tabs Report types S-controls Note: When you retrieve translations in your organization, the files returned in the .translations folder only include translations for the other metadata types referenced in package.xml.

Localizing with the Force.com IDE

Translating Custom Fields for Standard Objects

Translating Custom Fields for Standard Objects

This section demonstrates how to translate custom fields for a standard object, such as Account. The example demonstrates translation to French, so French must be an active language in your organization. The same process is used to translate into any of your active supported languages. The following steps involve usage of Salesforce and the Force.com IDE to illustrate how to translate a custom field. When you become more familiar with the Force.com IDE, you will be able to translate custom fields solely using the Force.com IDE. 1. In Salesforce, create a new custom field for the Account object by navigating to Your Name Setup Customize Account Fields and clicking New in the Account Custom Fields & Relationships section. 2. In the Force.com IDE, ensure that the package.xml manifest file matches the following sample manifest file.
<?xml version="1.0" encoding="UTF-8"?> <Package xmlns="http://soap.sforce.com/2006/04/metadata"> <types> <members>Account</members> <name>CustomObject</name> </types> <types> <members>Account-en_US</members> <members>Account-fr</members> <name>CustomObjectTranslation</name> </types> <version>21.0</version> </Package>

3. Right click on your project name and click Force.com Refresh from Server. Note that the Account custom field definitions for English (United States) are retrieved into the src/objectTranslations/Account-en_US.objectTranslation file and that the French definitions are in src/objectTranslations/Account-fr.objectTranslation. The two files are initially identical since you have not provided any French definitions yet. 4. Fill in the French translations in the <label> element for each field in src/objectTranslations/Account-fr.objectTranslation. The following sample shows an example of a translated value for the Active__c custom field. The NumberofLocations__c value has not been translated yet and it contains a placeholder comment in the <label> element.
<?xml version="1.0" encoding="UTF-8"?> <CustomObjectTranslation xmlns="http://soap.sforce.com/2006/04/metadata"> <fields> <label>Actif</label> <name>Active__c</name> </fields> <fields> <label><!-- Number of Locations --></label> <name>NumberofLocations__c</name> </fields> </CustomObjectTranslation>

5. Click File Save to save and deploy the changes to Salesforce. Tip: You can see the changes in Salesforce by right clicking on your project name and clicking Force.com Show in Salesforce Web.

Localizing with the Force.com IDE

Translating Custom Objects

Translating Custom Objects

This section demonstrates how to translate custom objects. The example demonstrates translation to French, so French must be an active language in your organization. The same process is used to translate into any of your active supported languages. 1. Identify a custom object to be translated. In Salesforce, create a new custom object or identify an existing custom object by clicking Your Name Setup Create Objects. In this sample, we use a Mileage custom object. 2. In the Force.com IDE, ensure that the package.xml manifest file matches the following sample manifest file:
<?xml version="1.0" encoding="UTF-8"?> <Package xmlns="http://soap.sforce.com/2006/04/metadata"> <types> <members>*</members> <name>CustomObject</name> </types> <types> <members>*</members> <members>Mileage__c-en_US</members> <members>Mileage__c-fr</members> <name>CustomObjectTranslation</name> </types> <version>21.0</version> </Package>

3. Right click on your project name and click Force.com Refresh from Server. Note that the Mileage custom object definitions for English (United States) are retrieved into the src/objectTranslations/Mileage__c-en_US.objectTranslation file and that the French definitions are in src/objectTranslations/Mileage__c-fr.objectTranslation. 4. Fill in the French translations by replacing any placeholder comments with your translations. Placeholder comments appear as <!-- ... --> within elements. The following sample shows an example of a translation for the Mileage custom object. Some of the <caseValues> elements, such as <value>le kilomtrage</value> for <article>Indefinite</article>, have already been translated; other placeholders, such as the plural value for <article>Indefinite</article>, still have to be translated. To find out which elements are required for each language, see Required Elements for Custom Objects on page 9.
<?xml version="1.0" encoding="UTF-8"?> <CustomObjectTranslation xmlns="http://soap.sforce.com/2006/04/metadata"> <caseValues> <article>None</article> <value>kilomtrage</value> </caseValues> <caseValues> <article>Indefinite</article> <value>un kilomtrage</value> </caseValues> <caseValues> <article>Definite</article> <value>le kilomtrage</value> </caseValues> <caseValues> <article>None</article> <plural>true</plural> <value><!-- Mileage --></value> </caseValues> <caseValues> <article>Indefinite</article> <plural>true</plural>

Localizing with the Force.com IDE

Languages

<value><!-- Mileage --></value> </caseValues> <caseValues> <article>Definite</article> <plural>true</plural> <value><!-- Mileage --></value> </caseValues> <fields> <label><!-- Date --></label> <name>Date__c</name> </fields> <fields> <label><!-- Miles --></label> <name>Miles__c</name> </fields> <gender><!-- Feminine --></gender> <nameFieldLabel><!-- Mileage Name --></nameFieldLabel> <startsWith><!-- Consonant --></startsWith> </CustomObjectTranslation>

5. Click File Save to save the changes to Salesforce.

Required Elements for Custom Objects

Different languages have a variety of grammatical rules for dealing with nouns, such as custom object names. For example, in some languages such as French, the noun must have a gender, so the <gender> element in CustomObjectTranslation is required for French. This is important for localization as the list of required elements differs for each language. To see the required elements for each of the languages that Salesforce supports: 1. Click Your Name Setup Customize Tab Names and Labels Rename Tabs and Labels. 2. Choose a translation language in the Select Language picklist. 3. Click Edit for your custom object in the Custom Tabs related list.

Languages
Salesforce.com offers three different levels of language support for its features, online help, and application development tools. Languages are identified by a two-character language code (such as en) or a five-character locale code (such as en_AU). Note: Setting a default locale is different than setting a default language.

You can change the language of all of Salesforce's features to one of the following fully-supported languages in the administration pages of Salesforce: Danish: da German: de English: en_US Spanish: es Finnish: fi French: fr Italian: it

Localizing with the Force.com IDE

Languages

Japanese: ja Korean: ko Dutch: nl_NL Portuguese (Brazil): pt_BR Russian: ru Swedish: sv Thai: th Chinese (Simplified): zh_CN Chinese (Traditional): zh_TW

You can change the labels of your end user features to one of the following languages, in addition to the fully supported languages in the Salesforce online help. Contact your salesforce.com representative to enable end user-only languages. Note: If you want to change the labels of your end user features to Hebrew or Arabic, ask your salesforce.com representative to specifically enable these languages. Arabic: ar Bulgarian: bg Czech: cs English (UK): en_GB Greek: el Spanish (Mexico): es_MX Hebrew: iw Hungarian: hu Indonesian: in Norwegian: no Polish: pl Romanian: ro Turkish: tr Ukrainian: uk Vietnamese: vi

If you develop applications using Salesforce's application development tools, you can translate the labels of all of your custom fields and most custom objects into all of Salesforce's fully supported languages in the Salesforce online help, end user-only languages in the Salesforce online help, and platform-only languages. Note: If your custom application uses a small number of Salesforce's standard tabs and fields, and you want to translate them into a platform-only language, you can do so by renaming tab and field labels. For more information, see Renaming Tab and Field Labels in the Salesforce online help. Contact your salesforce.com representative to enable platform-only languages. Bosnian: bs Croatian: hr English (Australia): en_AU English (Canada): en_CA English (India): en_IN English (Malaysia): en_MY

10

Localizing with the Force.com IDE

Languages

English (Philippines): en_PH French (Canada): fr_CA Georgian: ka Macedonian: mk Moldovan: ro_MD Serbian (Latin): sh Slovak: sk Serbian (Cyrillic): sr Slovenian: sl

11