Language I/O

The Language I/O Help desktop application for Salesforce.com pulls Salesforce Article content from the knowledge repository, marshals that content into localization packages and imports translated Article content back into Salesforce. This documentation will cover end-user operation of the Language I/O application. This application is meant to be used by qualified Language I/O personnel or by qualified personnel with our partner localization companies. Users are often project managers or localization process managers. These tools are not used by the Salesforce clients themselves.

Installation and launch

The Language I/O Help application is a Java application and can be run on recent versions of Windows and Mac operating systems. The URL of the launch page will be provided by your Language I/O representative. Your launch page should look similar to the page shown below. (Version numbers may be different).

The username and password will be provided to you by your Language I/O representative. These credentials authenticate you into the Language I/O server so you can download the Language I/O application.

If the credentials you entered are not valid, you will see an error message and you’ll need to try again or check with your Language I/O representative for correct credentials.

If the credentials are accepted, the page will refresh with a Launch button, as shown in the image below. Click on the Launch button to download the Language I/O Help application. Note that you have only a short amount of time during which that Launch button will remain active. If you wait too long, your session will expire and when you hit the launch button, you will see a 404 error.

This will download a jnlp file. Browse to where it was downloaded and double click it to launch.

A successful launch will result in the display of a login box as displayed below. You must login a second time (with the same credentials you used to download the application) for security reasons.

If your credentials are accepted this second time, the Language I/O HELP application will launch as shown below.

If your credential are for a client other than the one specified in your configuration file an message box will display, which will allow you to choose the correct configuration file.

Choose No to exit the program and Yes to continue to select the correct configuration file.

If the correct configuration file can't be found, click the Cancel button to have one created.

Pulling Article Content from Salesforce for Translation

To pull Article content from Salesforce for translation, your first step will be to enter several additional values on the tab labeled “Pull.” Clicking on the pull tab will take you back to the same view that you saw when you logged in (see image above).

Note: All configuration values on all tabs are saved automatically. When you restart the application, the values will be set to whatever the fields contained during your last session.

Configuring the Pull Tab

Proper configuration of the Pull tab enables you to pull the English content associated with any non-English draft articles that have been flagged for translation. The content will be pulled from the Salesforce knowledge repository and stored directly on your computer.

Queue Name

The queue name is the name of the Salesforce queue that will be queried for draft translation articles. Language I/O will display the names of all queues accessible to Language I/O and you’ll need to select the correct queue from the Queue Name drop-down list. The translation request email that you receive should include the name of the queue that you’ll need to select from this list.

When a user requests a translation of an article inside of Salesforce, a new draft translation article is created and Salesforce can be configured to have these drafts assigned to a queue instead of to a person. Language I/O will look for all articles that are awaiting translation inside of the named queue. In the example below, the Salesforce user has requested that the article “Account Storage” be translated into both Chinese and Spanish, and assigned the translation request to the queue entitled “Translations.”

When a translation into Chinese and Spanish is requested of an English article, Salesforce creates a Chinese and Spanish draft version of that article and assigns them to the Translations queue. Language I/O receives the translation request and pulls down the original English content. During the pull process, Language I/O stores the ID of the Spanish and Simplified Chinese drafts so Language I/O knows where to push the translations when they are ready. In order to pull the English content from Salesforce, you’ll need to configure the Article Type in the “Advanced Tab”. After we are finished we will come back to the pull tab to finish our configuration and then pull the content.

Earliest Date to Pull

In most cases, this field should be left alone, as Language I/O will automatically update it. Only change the value if you are very familiar with the date logic described in this section AND the status of all articles in the queue.

How Language I/O Decides Which Articles to Pull from the Queue

There are several date values that are pulled into the process that evaluate whether an article sitting in the specified queue should be pulled for translation. Before describing the evaluation process, it is important to understand the goal of this date logic.

We DON’T want Language I/O to pull an article that already contains a valid translation pushed in by Language I/O but has not yet been published for whatever reason thus it is still sitting in the queue.

We DO want Language I/O to pull an article for translation if:

It doesn’t yet contain any translation and requires its first translation

The article has been translated before but the original English has been modified since the last translation that we uploaded, thus it requires re-translation

The Three Date Values Language I/O Evaluates

apiUploadDate: This is the date value of a custom article field in Salesforce that is populated only by Language I/O whenever Language I/O pushes translated content into that article.

lastModifiedDate: This is a date value associated with an article and set by the Salesforce system whenever the article is modified in any way. When a Salesforce user alters the article within Salesforce or Language I/O updates a translation, this value is reset. When Language I/O is used to push a translation into a Salesforce article, the apiUploadDate is always set to be a few minutes earlier than the lastModifiedDate assigned by Salesforce.

earliestQueryDate: This is the Earliest Date to Pull value set by Language I/O whenever it pulls content for translation. The user can also override this value.

The Date Logic

Here is how Language I/O determines whether to pull an article for translation.

1. If the article has been modified within Salesforce since Language I/O last exported the article for translation, we continue the evaluation process. However, if Language I/O has already pulled the article for translation since the last time the content was modified by the system, we do NOT pull it again for translation and Language I/O does not continue onto the next steps. Using the date terms we learned previously, here is another way to understand this logic statement. If the date on which the article was last modified in any way (lastModifiedDate) is later than the earliestQueryDate (Earliest Date to Pull set in Language I/O which in most cases is the last time Language I/O pulled the article for translation but can also be overridden by the user), we continue to evaluate the article to determine whether it should be pulled for translation. However, if the date on which the article was last modified (lastModifiedDate) is earlier than the earliestQueryDate, we do not even consider pulling it for translation.

If in step 1 the system determined that the article should continue to be evaluated for translation, Language I/O checks to see if the article was ever previously translated. If it has NEVER been translated, it is now pulled for translation. Using the above date definitions, if the article doesn’t contain an apiUploadDate field or the value is null, this means for some reason we don’t have that field OR we have never imported a translation into that article and we go ahead and add it to the list of articles to be exported for translation.

If in step 1 the system determined that the article should continue to be evaluated for translation but in step 2 Language I/O determined that the article has been translated at least once before, Language I/O checks to see whether the article has been modified in any way since the last time it was translated. If it has been modified since the last time it was translated, this article is pulled for re-translation. Using the date definitions, Language I/O looks to see whether the apiUploadDate comes before the lastModifiedDate. This means the article was once translated by us, however it has since been modified so it is added to the list of articles to be pulled for translation.

Lastly, if in Step 2 we determine that it has already been translated once before and in step 3 we determine that it has NOT been modified within Salesforce since the last translation, the article is NOT pulled for translation.

Rules Path

The value in the Rules Path field points the application at a directory that contains one or more rules files. A Language I/O rules file defines several regular-expression-style rules that Language I/O uses to dynamically re-write links embedded in Articles so that translated articles link to other translated resources instead of to the original English resources.

These files will be provided to you by your Language I/O representative and are created by Language I/O engineers during the product setup process for each client. The value of having these rules in files that live outside the application is that engineers can update these files without having to change any code or otherwise alter a user’s configuration. They are unique to each Salesforce client. Push the button next to the Rules Path text field to navigate to the directory in which one or more rules files are stored. All rules files must end with the “.rules” extension. Once pointed at the directory containing the rules files, the application will pull in all rules defined in all of the rules files that live in that directory.

Package Path

This Package Path text field tells the application where to store and package the content that is being pulled down from your Salesforce repository. It accepts only directory values. Click on the button next to the text field to navigate to the directory where you wish to store the content or to create a new directory.

Package Name

The Package Name field is where you enter the base name for the localization packages that the application will create when it pulls the localizable content down from the Salesforce repository. The application will append this name with the name of the locale when it names each locale-specific directory. If you enter a package name of test123, the French localization directory will be named test123_French.

UTF-8 Checkbox (not actively used)

If selected, Language I/O will append the following HTML tag to the top of all HTML files that it exports for translation. This tag is helpful if the linguists who will be translating the content will manually import the Language I/O article files into a tool such as Trados because this tag tells Trados the character encoding of the HTML files, which will always be UTF-8. The tag is stripped out of the file before it is imported back into Salesforce.

Configuring the Advanced Tab

Before we can start to pull content for translation, you’ll need to select the correct Salesforce Article Type and the related translatable fields for that Article type. To do so, click on the “Advanced” tab. Your application should now look similar to the image below. The Root URL, Username and Password fields will all be populated for you and you shouldn’t need to change them.

Note: All configuration values on all tabs are saved automatically. When you restart the application, the values will be reset to whatever the fields contained during your last session.

Article Types

Salesforce Article Types are all custom with client-defined fields. Click the “New” button to add a new Article Type. In the drop down, select the Article Type to translate. Click the “Submit” button and a panel for the Article Type will be added below. The “New” button can be clicked again until there are no Article Types remaining.

Article Types that do not require translation need not be added. Each panel representing an Article Type can be minimized/maximized by clicking its name. For instance, clicking “Answer” below would maximize the panel. Clicking “FAQ” would minimize that panel.

Article Fields

The next step is to add to the Fields table any elements for this Article Type that require translation. Elements that do not require translation need not be added. Click the “Add Element” button to add an element and then select the element that requires translation from the drop-down menu. Click the button again to add additional elements. Likewise, elements can be deleted by selecting the field in the list of fields and clicking the “Delete Row” button

Pulling & Packaging Content

Once you have completed the configuration on the Pull tab (and have content in your Salesforce queue that is flagged for translation) you are ready to pull and package content. This process queries the selected Salesforce queue, pulls all Articles from Salesforce slated for translation and packages the content into one folder for each language identified within the queued articles. In our example, the two draft articles awaiting translation in the Translations Queue are shown below:

In this example, two language-specific directories (or “localization packages”) will be created: one for Spanish and one for Simplified Chinese.

Optionally Processing the Content with Rules files on the Pull

If there is a file path in the Rules Path on the Pull tab, the articles will be processed with the rules on the pull. This will result in files that are different across the localized folders.

However, it is now possible to pull the content without applying the rules files, which results in files that are identical across the localized folders. This enables us to send one file for translation into multiple languages.

Execute the Pull Process

There are two ways you can start the content pull process. The first option is to click on the Pull button. In the screen shot below, this is the button with the blue arrow pointing up, the first button on the left. You can also launch the Pull process by navigating to Run>Pull in the menu.

Cancel the Pull Process

Once you have started the pull process you can cancel it by selecting either the Cancel button (the red button with the white x) or by selecting Run>Cancel Pull from the menu. It will complete its current task before the process ends so don’t expect it to cancel immediately. If there are not many articles in the queue, the process will likely complete before it is able to cancel.

Pull Status

While the process is running, you will see its status in the status panel as shown in the image below. You can hide the configuration panel to better focus on the status by clicking on the small up arrow at the top left of the status area. You can also scroll inside the status panel by moving the scroll bars and the screen resizes to better view all the status messages. Finally, you can clear the status panel by right-clicking inside the status panel and selecting Clear or by clicking the clear icon in the toolbar which is the button furthest to the right with the green and red arrows.

Localization Package Structure and Handling

It is important to tell your linguists that the localization packages created by Language I/O should not be combined, taken apart or - aside from translating the html files - altered in any way. The directory structure that is pulled should go to the linguist exactly as it is and once translated, be pushed back into Salesforce with its original structure, file names and files in-tact.

Each package contains two types of files: HTML files and a single XML file. Each HTML file (which will have an .html extension) should be translated. The contents of a single localization package look as shown below. In the below case, the name of the locale-specific directory (or localization package) is test123_Spanish.

Notice that Language I/O creates one .html file for each standard article field and for each element of a Salesforce Article that is pulled for translation.

The XML file always has an .xml extension and is titled manifest.xml. The manifest file includes all the information that Language I/O needs to push the files in that particular directory back into Language I/O. This file is created and updated by Language I/O and should not be edited.

Pushing Translated Article Content into Salesforce

From the push tab, you will configure the application to push translated content from your local machine into your Salesforce repository

Configuring the Push Tab

Queue Name

The name of the queue the pushed articles should end up in. This can be helpful if you want to put the completed articles into their own queue.

Translations Path

The Translations Path field should hold the path to the parent directory where the application will look for language specific subdirectories containing the translated files. If during the Pull process you created localization packages named 11_15_2011_French and 11_15_2011_Spanish, you would send those two directories to the linguists for translation. When they are returned by the linguists, you would save each of these directories under a common parent directory such as: C:\translated_files.

C:\10_30_2012\test123_Chinese (China)

C:\10_30_2012\test123_Spanish

You would then select the button next to the Translations Path field to navigate to and select C:\10_30_2012. The application will iterate through each subdirectory inside C:\10_30_2012 looking for the manifest file and the referenced, translated .html files.

Rules Path

This path is for the rules applied on the push, if the field is left blank, the articles will be pushed without any processing. If no rules were applied on the pull then it is possible to put the translations into the local specific directories and do the link localization on the push.

Publish after Push

If this checkbox is selected, Language I/O will not only push the translated content into the draft article objects sitting in the queue, it will also publish each article after the translation is pushed in. Only check this box if you are sure that the Salesforce client wants the articles published. If you are not sure, it is best to leave the box unchecked as you can always publish the articles in the queue from inside Salesforce.

Localizing URL Name fields

When the URL Name fields are translated, sometimes they end up with characters that are not allowed by Salesforce. To removed them, place a UTF-8 encoded file in your home directory with the extension url_replace. Inside this file, put each character that needs to be removed. Examples include periods, colons, semi-colons and single quotes.

Pushing Translated Content

Once you have pulled content from Salesforce into its Language I/O specific packages, translated those packages and configured the Push tab, you are ready to push the translated Articles into Salesforce.

The Translation Push Process

You can push the translated content in one of two ways. You can click on the Push button in the tool bar. This button is the second over from the right in the image to the left (the button with the green arrow pointing down). You can also navigate to Run>Push in the menu

Canceling the Push Process

Once you have started the push process you can cancel it by selecting either the Cancel button (the red button with the white x) or by selecting Run>Cancel Push from the menu.

Push Status

While the process is running, you will see its status in the status panel as shown in the image below. You can hide the configuration panel to better focus on the status by clicking on the small up arrow at the top left of the status area. You can also scroll inside the status panel by moving the scroll bars and the screen resizes to better view all of the status messages. Finally, you can clear the status panel by right-clicking inside the status panel and selecting Clear or by clicking the clear icon in the toolbar which is the button furthest to the right with the green and red arrows.

Logging

The status messages that display in the status panel of the application should be reviewed during the process execution to ensure that no errors were thrown. Each status message begins with a date/time stamp followed by a Language I/O code such as INFO, WARN, ERROR or FATAL. These messages are intended to let you know what the application is doing at that point in time. If the Language I/O code is INFO, all is well. However, when you start to see WARN, ERROR, or FATAL showing up in those status messages something is wrong.

Types of Status Messages

In this section, we’ll discuss the different levels of error messages and what they could mean.

WARN

A WARN message is usually something from which you can recover. For example, let’s say you manually enter the path to the translated files but there is a typo in the path. You will see a WARN message pop up telling you that a valid directory is required. At that point, you enter a valid directory into the configuration field and you start again.

ERROR

An ERROR message is a bit more serious, but it usually results in the failure of one piece of your operation, not the entire operation. For example, when you are pushing translated content back into Salesforce, sometimes the linguist’s translation of the Article summary exceeds the maximum characters allowed by Salesforce. In this case, an error will be thrown telling you that that particular Article failed to update and why. The rest of the Articles, however, should be updated without any problem. Once the process completes, you must go back and fix that Article, create a new package and re-upload that Article only.

FATAL

A FATAL message is the worst kind and means that the entire push or pull operation has failed and will need to be fixed and restarted. Fatal errors can be caused, for example, by incorrect connection information entered into the Advanced tab, a corrupted manifest file or by a package that has missing .html files.

Log Files

While it’s important to scan through the status that is being output in the status panel during and after a process, the application also saves your log messages to your local computer. Maybe you’re seeing error messages that you don’t understand and need to send them to someone who will understand them. Whatever the case, a file or files with a base name of SF_Log.log will be created each time you run the tool. The directory in which it is stored varies by OS but on a Mac it will use the user’s home ($HOME) directory, which is named after your user. On a Windows machine, it is written to your Desktop. These files will eventually be overwritten so be sure to save them elsewhere on your computer if you think you’ll need to refer to them later.