l10n

Dovetail Software Localization Tool For Clarify-defined and User-defined Lists.

Purpose:

This tool allows to export a list or a set of lists from Clarify/Amdocs database into individual files. The files contain comma (with some exceptions) -separated text, one line per list element per local value. These files can be modified in a text editor. Then the files can be imported into the database to create/modify localized elements.

Prerequisites:

• If the localized values contain any characters outside of ANSI character set the database must be capable of storing Unicode text. For example, for German, the ä, ö, ü, and ß characters do not require the database to be Unicode-enabled, whereas the ą, ę, ć, ż, and other Polish characters can only be stored in a Unicode-enabled database. Consult [this article] (http://dovetailsoftware.com/clarify/mpawelczyk/2008/08/19/unicode-database-conversion-and-usage/) for guidance on how to make a Clarify/Amdocs database Unicode-enabled.
• table_fc_loc_elm must be defined in the database schema.
• a list element to be localized must exist in the database.
• Dovetail Software's fcSDK must be installed on the computer running the tool.

Assumptions:

• there are no duplicate title values in a Clarify list
• there are no duplicate title values at any level of a used-defined pop-up list

Methodology:

• localized values are stored in table_fc_loc_elm rows related to either:
  -- table_gbst_elm rows for Clarify lists
  -- table_hgbst_elm rows for used-defined pop-up lists
• each table_fc_loc_elm row stores the locale code of the value, in xx-XX format (as specified [here] (http://msdn.microsoft.com/en-us/library/ms533052%28vs.85%29.aspx), e.g. "pl-PL" for Polish).
• one row in table_gbst_elm or table_hgbst_elm table can have many related table_fc_loc_elm rows, one for each language in use.
• one row in table_fc_loc_elm can be related to only one row of either table_gbst_elm or table_hgbst_elm. The same row in table_fc_loc_elm can't be used to localize elements in both table_gbst_elm and table_hgbst_elm at the same time even if they store the same title value.
• it's not required to localize entire list. Individual elements can have as many localizations as needed, one per language, independently from each other.
• rows in table_gbst_elm and table_hgbst_elm are not modified by this tool.

Notes:

• the tool allows for export-once-import-to-many approach which means the lists may be exported only once form a template database, localized, then imported to as many databases as needed, without having to go through export-edit steps for each database separately.
• Clarify list elements are searched for by title. If they are already localized, the localized values will be updated.
• used-defined pop-up list elements are searched for by title at a level they belong to. If they are already localized, the localized values will be updated.

Preparations:

• install Dovetail Software's fcSDK.
• prepare connection info in fc.env file.
• make sure the table_fc_loc_elm is defined in the database schema. If it's not, use Dovetail Software Schema Editor to import \schema\l10n.schemascript.xml file.
• make the database Unicode-enabled if any localized values are expected to contain any characters outside of ANSI character set.

Usage:

1. export a list first:
   -- use ExportLocalizedGBSTListElement.js code for Clarify list(s)
   -- use ExportLocalizedHGBSTListElement.js code for used-defined pop-up list(s)
   -- language code must be specified in xx-XX format. If a language has only the xx symbol e.g. "af" for Afrikaans, use "af-AF".
   -- a list is exported whole, no individual elements can be selected
   -- each list exports to a separate file named list-name_GBST_locale.txt or list-name_HGBST_locale.txt.
2. modify exported file by adding a localized value at the end of each line of your choice. The value should be in a language indicated by locale code.
   Important:
   -- the file is encoded in Unicode format to allow language-specific characters.
   -- use proper text editor capable of handling Unicode-encoded files.
   -- do not convert the file to other encoding method to avoid data loss/misrepresentation.
3. import a list:
   -- use ImportLocalizedGBSTListElement.js code for Clarify list(s)
   -- use ImportLocalizedHGBSTListElement.js code for used-defined pop-up list(s)

How to localize a Clarify list:

1. run export tool:
   -- export individual list:
   CScript //E:JScript ExportLocalizedGBSTListElement.js /locale:xx-XX [/path:full_path_to_output_files] /list:list_name
   -- export multiple lists: CScript //E:JScript ExportLocalizedGBSTListElement.js /locale:xx-XX [/path:full_path_to_output_files] /list:list_name-1,list_name-2,...
   -- export all lists:
   CScript //E:JScript ExportLocalizedGBSTListElement.js /locale:xx-XX [/path:full_path_to_output_files]
   Notes:
   -- /locale parameter is mandatory
   -- if /path parameter is not used, output files will be created in current directory
   -- if a list name contains blanks or any of /\?:*"<>|.,', enclose in double-quotes, e.g. /list:"Problem Severity Level"
   -- if a list name contains any of /\?:*"<>|.,' they will be replaced by "-" in the name of the output file
   -- each list exports into a separate file, e.g. "Problem Severity Level_GBST_pl-PL.txt".
   -- IMPORTANT! If a list name(s) contain(s) at least one comma character, use this alternate format (enclose list names in double-quotes, separate them with blanks):
   CScript //E:JScript ExportLocalizedGBSTListElement.js /locale:xx-XX [/path:full_path_to_output_files] "list_name-1" "list_name-2"...
   -- IMPORTANT! If a list name or a list element contains a comma character, a different separator (any of |;:!#^.?*-_ ) may be used, and will be determined by the tool.

2. edit the file:
   -- file name example:
   Problem Severity Level_GBST_pl-PL.txt
   -- file format:
   list_name,title,locale,localized_value
   -- exported data example:
   Problem Severity Level,High,pl-PL,
   -- add or modify the localized_value at the end of the row:
   Problem Severity Level,High,pl-PL,Wysokie

3. run import tool:
   -- import individual list:
   CScript //E:JScript ImportLocalizedGBSTListElement.js /file:full_path_to_input_file
   -- import multiple lists:
   CScript //E:JScript ImportLocalizedGBSTListElement.js /file:full_path_to_input_file-1,full_path_to_input_file-2,...
   -- import all lists from current folder:
   CScript //E:JScript ImportLocalizedGBSTListElement.js /folder:.
   -- import all lists from specific folder:
   CScript //E:JScript ImportLocalizedGBSTListElement.js /folder:full_path_to_input_files
   Notes:
   -- use /file parameter to run the tool for each list individually or specify multiple file names separated by commas.
   -- use /folder parameter to run the tool for all list file names matching *_GBST_*.txt
   -- the /folder parameter takes precedence over the /file parameter.
   -- if a file or folder name contains blanks, enclose in double-quotes, e.g. /file:"Problem Severity Level_GBST_pl-PL.txt"

How to localize a used-defined pop-up list:

1. run export tool:
   -- export individual list:
   CScript //E:JScript ExportLocalizedHGBSTListElement.js /locale:xx-XX [/path:full_path_to_output_files] /list:list_name
   -- export multiple lists: CScript //E:JScript ExportLocalizedHGBSTListElement.js /locale:xx-XX [/path:full_path_to_output_files] /list:list_name-1,list_name-2,...
   -- export all lists: CScript //E:JScript ExportLocalizedHGBSTListElement.js /locale:xx-XX [/path:full_path_to_output_files]
   Notes:
   -- /locale parameter is mandatory
   -- if /path parameter is not used, output files will be created in current directory
   -- if a list name contains blanks or any of /\?:*"<>|.,', enclose in double-quotes, e.g. /list:"Notification Types"
   -- if a list name contains any of /\?:*"<>|.,' they will be replaced by "-" in the name of the output file
   -- each list exports into a separate file, e.g. "Notification Types_HGBST_pl-PL.txt".
   -- IMPORTANT! If a list name(s) contain(s) at least one comma character, use this alternate format (enclose list names in double-quotes, separate them with blanks):
   CScript //E:JScript ExportLocalizedHGBSTListElement.js /locale:xx-XX [/path:full_path_to_output_files] "list_name-1" "list_name-2"...
   -- IMPORTANT! If a list name or a list element contains a comma character, a different separator (any of |;:!#^.?*-_ ) may be used, and will be determined by the tool.

2. edit the file:
   -- file name example:
   Notification Types_HGBST_pl-PL.txt
   -- file format:
   list_name,title,locale,localized_value
   -- exported data example:
   Notification Types,Digital Pager,pl-PL,
   -- add or modify the localized_value at the end of the row:
   Notification Types,Digital Pager,pl-PL,Przywoływacz cyfrowy
   Notes:
   -- for a multi-level list, each element is fully qualified by elements at all preceding levels:
   list_name,title[,title]...,locale,localized_value
   -- for example: CR_DESC list, the "PC" -> "Windows 3.1" -> "16m" element is represented like this:
   CR_DESC,PC,Windows 3.1,16m,pl-PL,16 megabajtów
   -- only the last value in this path is localized, which is "16m".

3. run import tool:
   -- import individual list:
   CScript //E:JScript ImportLocalizedHGBSTListElement.js /file:full_path_to_input_file
   -- import multiple lists:
   CScript //E:JScript ImportLocalizedHGBSTListElement.js /file:full_path_to_input_file-1,full_path_to_input_file-2,...
   -- import all lists from current folder:
   CScript //E:JScript ImportLocalizedHGBSTListElement.js /folder:.
   -- import all lists from specific folder:
   CScript //E:JScript ImportLocalizedHGBSTListElement.js /folder:full_path_to_input_files
   Notes:
   -- use /file parameter to run the tool for each list individually or specify multiple file names separated by commas.
   -- use /folder parameter to run the tool for all list file names matching *_HGBST_*.txt
   -- the /folder parameter takes precedence over the /file parameter.
   -- if a file name contains blanks, enclose in double-quotes, e.g. /file:"Notification Types_HGBST_pl-PL.txt".

Usage Tips:

• An alternate way to import all exported and localized lists in one run (per list type) without a need to specify all file names. To do this, merge all localized lists, e.g. into "cl125_GBST_pl-PL.txt" file for Clarify lists and into "cl125_HGBST_pl-PL.txt" file for used-defined pop-up lists. Then use these commands:
  -- for Clarify lists:
  CScript //E:JScript ImportLocalizedGBSTListElement.js /file:"cl125_GBST_pl-PL.txt"
  -- for used-defined pop-up lists:
  CScript //E:JScript ImportLocalizedHGBSTListElement.js /file:"cl125_HGBST_pl-PL.txt"
  Note:
  -- do not merge Clarify lists and used-defined pop-up lists into one file.
• List names can be supplied to ExportLocalizedGBSTListElement.js and ExportLocalizedHGBSTListElement.js modules in both formats at the same time, e.g.
  CScript //E:JScript ExportLocalizedGBSTListElement.js /locale:xx-XX [/path:full_path_to_output_files] /list:"list_name-1" "list_name-2"
  In this scenario, list_name-1 cannot contain comma character while list_name-2 can.