Using Language I/O Help for Oracle Service Cloud Desktop Application

Overview

The Language I/O Help desktop application pulls Answer content from the Oracle Service Cloud (OSvC) repository, marshals that content into localization packages and imports translated OSvC Answer content back into OSvC. This documentation will cover use of the Language I/O Help application for OSvC. The categories of functionality are divided as follows.

• Installing and launching the Language I/O HELP desktop application
• Pulling answer content from OSvC for translation
• Pushing translated content back into OSvC
• Reading Language I/O Help Log Files
• Reading Language I/O Help Manifest Files

Installation and launch

The Language I/O Help desktop application is a Java application and can be run on recent versions of Windows and Mac operating systems. It is installed and launched from a web page via Java Web Start at https://www.golinguist.com/linguistnow/oracle_login.jsp The URL should be accessed in Safari or Firefox. Internet Explorer doesn’t work with the server restrictions on port 80 and Google Chrome doesn’t support the latest version of Java.

Your launch page should look similar to the page shown below. (Version numbers may be different.)

• Once you submit your OSvC username and password, the page will refresh with a Launch button and explanatory text. Click on the Launch button and your credentials will be used to download the Language I/O application to your computer.

• You will be asked to accept a certificate from Language I/O. Before accepting, check the box that agrees to always accept certificates from this source, then accept.
• If you are launching the Language I/O Help desktop application for the first time, or if a new version is available, there will be a download before the desktop application displays.
• Once the client launches, another login window will display. Here you must re-enter the same credentials. For security reasons we are unable to pass the credentials from the web page into the Java application.

• If the credentials you entered are not valid, you will see a message asking you to re-enter your credentials. If the credentials are accepted by OSvC, the Language I/O Help desktop application will launch as shown in the next image. Note that the text that displays at the very top of the window will vary depending upon the version of OSvC that Language I/O is connected to.

Pulling Answer Content from OSvC

To pull answer content from OSvC for translation, your first step will be to enter a number of configuration values. The top, tabbed panel within the application is dedicated to configuring the content Push and Pull processes. For that reason you’ll see both a Push tab and a Pull tab. Depending upon your application configuration, you might also an Advanced tab.

The advanced tab allows users to edit their OSvC connection settings. This Advanced tab will be pre-populated with default connection parameters including the username and password you entered into the launch page. Only edit these fields if you understand the OSvC connection parameters well. In most cases these values will be edited by Language I/O technicians configuring your installation during the setup phase.

All 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.

Pull Configuration

The Pull tab contains a number of configuration fields that must be completed in order to pull Answer content from your OSvC repository to your local computer.

Answer IDs

In the Answer IDs text field, enter the OSvC Answer IDs you want to pull from your OSvC repository to your local machine. Each ID must be separated by a comma and no spaces. If you wanted to pull answers 7282 and 7283 you would enter them into the Answer ID field as show below. This is one of two options for specifying the answers you want to pull. In the next field (Answer ID File) you can point the application to a plain text file that contains all of the answer ids (one per line) that you wish to pull down. The file option is a better option for pulling many answers at once. If you are only pulling a few answers, the direct entry field is recommended.

Big Comment File

The big comment file is for commenting out large sections of content to hide it from the linguists. The file needs to  have one regular expression per line and that entire regular expression will be commented out in the files.

In this example, any content covered by the <h1>.*?</h1> such as <h1>Hi</h1> would be converted to <!--<h1>Hi</h1>--> so that it doesn't get translated. 

Answer ID File

If you are pulling many answers at the same time it’s more efficient to point the application to a file containing all of the answer IDs. The file should be a plain text file created in a programmer’s text editor (such as Notepad++ or TextEdit) and should contain no additional formatting. Do not use MS Word, Pages or other word processing tools that apply special formatting. One ID should be entered per row. In other words, each ID should be separated by a carriage return as shown in the example below. Navigate to your file by clicking on the button next to the Answer ID File text field. Browse to its location and select the file. The extension of the file must be “.txt.”

Rules Path

***Applying the rules on the pull (not the push) will result in files that are different across languages***

The value in the Rules Path field points the application at a directory that contains one or more files containing regular expression rules. The application uses these regular expressions to perform locale-sensitive parsing of Answer content. These files will be provided to you by your Language I/O account manager and are created during the product installation and setup process. They are specific to your installation. 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 either 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

Rules are used by the application to perform locale-sensitive parsing of the English HTML before the HTML content is placed into localization packages. It is recommended that you do not edit these files unless you are familiar with regular expressions and HTML syntax. Let’s look at a rules file:

Each rules file has five, tab-delimited columns. Each of these columns is used when the application is parsing HTML content.

• The first column contains a OSvC language ID. In the above example, the application sees 9 and understands that this rule applies only to French answers because 9 is the OSvC ID for the French locale.
• The second column, which contains <[aA]\b[^>]+> in the above example is a regular expression that tells the application to search for all anchor tags embedded in the HTML content of the answer.
• The third column is the exceptions column. If a detected anchor tag contains the exception pattern within the tag, that tag is left alone. If it contains the value ‘0’ (without single quotes), no exceptions exist for this pattern.
• The fourth column is a regular expression that is used to find the portion of the anchor tag that the application should rewrite.
• The final column contains no regular expression syntax, only the replacement text for portion of the anchor tag that we want to rewrite. So using the first rule as the example, if we are creating the French localization package (9) and within the Answer text we find an anchor tag that contains http:\\www.surveymonkey.com inside the href attribute of the anchor tag, and it does NOT contain ‘/ s/’ in the href portion, we will replace the http:\\surveymonkey.com portion of the tag with http:\\aide.surveymonkey.com. In this particular example, this replacement process ensures that the answer links to French web pages within the SurveyMonkey website.
• For more information about the regular expression syntax supported within Language I/O Help rules files, look at the java.util.regex documentation.

Package Path

This Package Path text field tells the application where to store and package the content that is being pulled down from your OSvC repository and stored on your local computer. 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 content down from the OSvC repository for localization. The Application will append this name with the name of the locale. So if you enter a base name of RN_DEMO, the French localization package will be named RN_Demo_French.

Translations

The Translations list allows you to select all the locales for which you want the application to create localization packages. The list contains all locales currently supported by your OSvC repository. You can select one or many locales and for each locale selected, a locale-specific localization package will be created when you pull down the English content that requires translation. In the below example, we have selected to create localization packages for French, German, Italian, Portuguese (Brazil) and Spanish, but not Japanese.

 

 

New Sibling Status & New Sibling Access Level

When Language I/O pulls English Answers out of OSvC for translation, it simultaneously validates that there is a place to put translated Answers when they are ready. Within OSvC, that “place” for the translated version of an Answer is called a Sibling Answer. A French translation of an English Answer is always associated with the original English Answer via a Sibling relationship.

If Language I/O has already pushed a translation for a given English Answer into OSvC, this means a Sibling Answer already exists and Language I/O simply records the ID of that Answer so it knows where to push the new translation when it is ready. If an English Answer has never been translated before, a Sibling doesn’t yet exist. In this case, when Language I/O pulls the English Answer content for translation, it simultaneously creates a place-holder (empty), Sibling Answer and records the ID so it has a place to push the translation when it is ready. That placeholder Sibling Answer, like every Answer within OSvC, has to have both a Status and an Access Level when it is created. These values dictate whether the Answer is publicly viewable, or not, and what types of users can access it.

The two drop-down lists (New Sibling Status and New Sibling Access Level) allow the user to specify what Status and Access Level these newly created, place-holder, Sibling Answers will have prior to pushing in the translation. If “Default” is selected, Language I/O will create them with the same Status and Access Level as the Sibling English Answer.

The New Sibling Answer Status and New Sibling Answer Access Level drop-down lists will be populated with all status values defined in your OSvC repository, including custom statuses.

Note that in previous versions, Language I/O always created these place-holder Answers with a Private status and no Access Level. At a minimum you’ll need to find out from clients which Access Level they want these place-holder Answers to carry.

 

Pulling & Packaging Content

Once you have completed the configuration on the Pull tab (and have content in your OSvC repository that is ready for translation) you are ready to pull and package content for translation. This process reads in the Answer IDs, pulls those Answers from OSvC and packages the content into one folder for each locale selected in the Translations list. The Pull process also performs a number of formatting tasks that are locale specific. This means that even before the content is translated, the content that lives in the French package is already different from the content that lives in the Spanish package. They are not interchangeable.

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 it’s current task before the process ends so don’t expect it to cancel immediately.

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 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.

Localization Package Structure and Handling

It is important to tell your linguists that the localization packages created during the pull should not be combined, taken apart or - besides 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, pushed back into OSvC with its original structure intact.

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 XML file should not be touched unless you are an expert in Language I/O HELP Manifest syntax. 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 11_15_2011_French.

Notice that Language I/O creates one .html file for each element of a OSvC Answer that is pulled for translation. These elements include the Answer text itself, the Description, The Keywords and the Summary. Keywords are not required.

The XML file always has an .xml extension and is titled [Package_Name]_manifest.xml, where [Package_Name] is whatever you specified in the Package Name field on the Pull configuration tab. This manifest file includes a link to each file in this package. It also includes the Answer ID for each answer along with other pertinent answer information.

This file should not be edited if you are not an expert in the syntax of Language I/O HELP manifest files. While each of the files in the localization package can be translated, they should not be moved to different directories. If new files are added to the package, they will be ignored by the application unless the manifest file is manually edited to include them. 

Pushing Translated Answer Content into OSvC

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

Push Rules Path

This is identical to the functionality provided by the Pull Rules Path, except that it happens on the push instead of the pull.

Link Localization Path

This is a file that holds translations of the phrase (In English) so that if a localized OSvC link can't be found, the end user is told that the link they are clicking on, goes to an English link. The first column is the OSvC language code.  The second column is the translation for (In English).  The two columns are tab separated

Translations Path

The Translations Path field should hold the path to the parent directory where the application will look for language specific sub-directories 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:\translated_files\11_15_2011_French

C:\translated_files\11_15_2011_Spanish

You would then select the button next to the Translations Path field to navigate to and select C:\translated_files. The application will search through each sub-directory inside C:\translated_files looking for the manifest file and the referenced, translated .html files.

Translated Answer Status & Translated Answer Access Level

In most cases, the Translated Answer Status and Translated Access Level values can be left as Default. Default means that the translated Answers will inherit the same Status and Access Level as the original English Answer. For example, if - when the original English answer was pulled for translation - the status was set to Public, the French and Spanish translations when pushed will also be set to a status of Public.

 

 

If, however, you want to override the original English answer Status or Access Level and set the Status or Access Level of all translated Answers to Private Status or Everyone Access Level, you can do so by setting the status value accordingly in the Translated Answer Status and Translated Answer Access Level drop-down lists. Every answer that is pushed will then be set to the selected Status or Access Level. Note that for place-holder Sibling answers generated by Language I/O, the selected Status and Access Level on the pull tab will override whatever was selected for New Sibling Status and New Sibling Access Level.

The Translated Answer Status and Translated Answer Access Level drop-down lists will be populated with all status values defined in your OSvC repository, including custom statuses.

Pushing Translated Content

Once you have pulled content from OSvC using the Language I/O HELP desktop application, that content has been translated and returned to you, and you have properly configured the Push tab, you are ready to push the translated answers into OSvC.

Execute the Push Process

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

Cancel 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 must be reviewed preferably during the process but at least after the process has completed. If the text INFO shows up near the beginning of a status message, all is well. These messages are intended to let you know what the application is doing at that particular point in time. 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 OSvC, sometimes the linguist’s translation of the answer summary exceeds the maximum 240 characters allowed by OSvC. In this case, an error will be thrown telling you that that particular answer failed to update and why. The rest of the answers, however, should be updated without any problem. Once the process completes, you have to go back and fix that answer, create a new package and re-upload that answer 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 backs up your log files to your hard drive as a safety precaution. 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 RAC_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. This file or files will be overwritten with each execution so be sure to save it under a different name if you think you’ll need to refer to it later.

The Manifest File

We don’t recommend altering the Manifest file unless you are familiar with both XML syntax and with OSvC concepts such as answer ids, answer status ids, answer access level ids, etc.

Manifest files are stored in a very simple XML structure and are used to define all translatable files that exist in a localization package. Linguists should not touch this file.

Answer IDs and Meta IDs

Each OSvC answer is represented by an element as shown in the example manifest below. The first sub element will be the ID for that answer represented by an tag. Next comes the tag. A Meta ID is the English ID that corresponds to a localized answer. So if we are looking at the Manifest file for a French package - as is the case in the example below - the answer id is 192 which corresponds to the English answer with the answer id of 1.

File Elements

Next come the names of the html files that correspond to this answer including the actual answer file, summary file, keywords file and description files. All files defined in the manifest must exist in the directory or the process will fail. It is also not possible to delete one of these elements from the manifest (such as summary.html) because you only need to update the keywords, for example. The Application requires a file for all required pieces of the answer (summary, answer and description) before it will update any piece.

Misc. Answer Attributes

The remaining values map to elements such as the status of the original English answer, the access level of the original English answer, the user’s ID (this will vary by user and by repository and is set both in last-edited-by and assigned) as well as language attributes. None of these should be edited unless you know what you’re doing.

Debugging Tips:

If you encounter "ERROR Push - Summaries are too long" follow these steps. 

• Look at the line before the error to determine which summary is causing the error. In the example below 21062_summary.html is the offending summary.
  • Example:
    WARN UnpackagerController [path to files]/[language specific sub directory]/21062_summary.html
• Open that file (ex: 21062_summary.html) in a text editor and cut/paste the contents to a temporary file (ex: 21062_summary_TEMP.html)
• Now that summary file should be empty, and you should be able to retry the push
  • If you get the same "Summaries are too long" error for a different summary, follow the above steps for that file and try the push again until it works.
• Once the push is complete, open the Answer in Oracle Service Cloud.  Cut/paste the summary text from the temporary file (ex: 21062_summary_TEMP.html) into the Answer summary.
• Save your changes, and you are done!

NOTE: The reason this bug happens, and this fix works, is because the API applies a limit to the number of bytes in the Summary, but the Oracle Service Cloud GUI applies a limit to the number of characters in the Summary.  Some languages take more than one byte to represent one character, so there may be more bytes than characters.  By entering the Summary text into the OSvC GUI, you are only limited by the character count, not the larger byte count.