Follow

Grand Teton Release: Using LinguistNow Help for Oracle Service Cloud Desktop Application

Overview

The LinguistNow HELP desktop application pulls Answer content from the Oracle RightNow CX repository, marshals that content into localization packages and imports translated RightNow Answer content back into RightNow. This documentation will cover use of the LinguistNow HELP application for Oracle RightNow. The categories of functionality are divided as follows.

  • installing and launching the LinguistNow HELP desktop application
  • pulling answer content from RightNow for translation
  • pushing translated content back into RightNow
  • reading LinguistNow HELP Log Files
  • reading LinguistNow HELP Manifest Files

Installation and launch

The LinguistNow HELP desktop application is a Java application and can be run on recent versions of Windows and Mac operating systems. It is downloaded from a web page at https://golinguist.com/linguistnow/login.jsp

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

  • Once you submit your RightNow username and password, the page will refresh with a Launch button and explanatory text, validating the Language I/O client for whom you have logged in. Click on the Launch button and your credentials will be used to download the LingiustNow application to your computer.

  • This will download a jnlp file. Browse to where it was downloaded and double click it to launch.
  • 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 RightNow, the LinguistNow 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 RightNow that LinguistNow is connected to.

Pulling Answer Content from RightNow

To pull answer content from RightNow for translation, your first step will be to enter several 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. You will also see an advanced tab that 

The advanced tab allows users to edit their RightNow 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 RightNow 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 RightNow repository to your local computer.

Answer IDs

In the Answer IDs text field, enter the RightNow Answer IDs you want to pull from your RightNow repository to your local machine. Each ID must be separated by a comma and NO SPACES. If you wanted to pull answers 204 and 184 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 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.

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

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. 

Pull Rules Path

***Applying the rules on the pull 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 LinguistNow 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 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 RightNow language ID. In the above example, the application sees 9 and understands that this rule applies only to French answers because 9 is the RightNow 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. 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 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 LinguistNow 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 from your RightNow 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 RightNow repository. The Application will append this name with the name of the locale. 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 RightNow repository. You can select one or more 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 and Spanish, but not the others.

New Sibling Status & New Sibling Access Level

When LinguistNow pulls English Answers out of RightNow for translation, it simultaneously validates that there is a place to put translated Answers when they are ready. Within RightNow, 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 LinguistNow has already pushed a translation for a given English Answer into RightNow, this means a Sibling Answer already exists and LinguistNow 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 LinguistNow 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 RightNow, must 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, LinguistNow 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 RightNow repository including custom statuses.

Note that in previous versions, LinguistNow always created these place-holder Answers with a Private status and no Access Level. At a minimum you will 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 RightNow 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 RightNow and packages the content into one folder for each locale selected in the Translations list.

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.

 \

Confirm the Pull

After starting the pull there will be a warning box that asks if you want to continue. Select Yes to continue and No to stop.

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.

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 RightNow 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 LinguistNow HELP Manifest syntax. The contents of a single localization package look as shown below. In the following case, the name of the locale-specific directory (or localization package) is 11_15_2011_French.

Notice that LinguistNow creates one .html file for each element of a RightNow Answer that is pulled for translation. These elements include the Answer text itself, the Description, the Keywords (optional) and the Summary.

The XML file always has an .xml extension and is titled [Package_Name]_manifest.xml, where [Package_Name] is what 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 only be edited by an expert in the syntax of LinguistNow 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 RightNow

From the push tab, you will configure the application to push translated content from your local machine into your RightNow 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 Rightnow link can't be found, the end user is told that the link they are clicking on, goes to an English link. The format of the file is Rightnow language code tab translation

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:\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 subdirectory 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 the original English answer that was pulled for translation had a status of Public, the French and Spanish translations when pushed would also have 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 LinguistNow, 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 RightNow repository, including custom statuses.

Pushing Translated Content

Once you have pulled content from RightNow using the LinguistNow 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 RightNow.

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.

Confirm the Push

After starting the push there will be a warning box that asks if you want to continue. Select Yes to continue and No to stop.

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 RightNow, sometimes the linguist’s translation of the answer summary exceeds the maximum 240 characters allowed by RightNow. In this case, an error will be thrown telling you that the answer failed to update and why. The rest of the answers, however, should be updated without any problem. Once the process completes, you must go back and fix that answer, create a new package and re-upload that answer only.

FATAL

A FATAL message is the most severe and means that the entire push or pull operation has failed and will need to be fixed and restarted. For example, fatal errors can be caused 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 RightNow 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 RightNow 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. 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. These should only be edited by experts with the process.

0 Comments

Article is closed for comments.
Powered by Zendesk