Translating the HTML5 viewer's locale files

This article shows you how to use a text editor and Microsoft Excel (or equivalent spreadsheet software) to extract the text strings for translation and then re-insert them into the json files. An example spreadsheet is attached to this article.

Creating a New Translation

Find your HTML5 viewer's default locale files (typically in C:\inetpub\wwwroot\Html5Viewer\Resources\Locales).

Make two new copies of Mapping.en-US.json.js and Mapping.Infrastructure.en-US.json.js -- one as a back-up, in case something goes awry, and one set to be your new locale files. Rename the two new locales accordingly (e.g., Mapping.Infrastructure.nb-NO.json.js). The other three locale files (Charting.en-US.json.js, Framework.UI.en-US.json.js, Mapping.Charting.en-US.json.js) are small enough that it's easier to simply translate them by hand.

For each file:

• Open the json file in a text editor and copy the text. Paste that text into a new text document.
  • For Mapping.en-US, copy the section of the file that you want to manipulate in Excel. Omit the datepicker and timepicker entries at the top and bottom of the file, as their structure doesn't work well for what we're going to do -- they're easy enough to update manually in the locale file. For the 2.7 version of Mapping.en-US.json.js, this would be line 71 ("language-accessibility-form-named-container-hidden": "...") to line 2028 ("language-workflow-workflows": "...").
• Do a search and replace to replace ": " (including the double-quotes) to ":|^" Those characters are: double-quote, colon, vertical bar or pipe (https://en.wikipedia.org/wiki/Vertical_bar), caret, double-quote".
  • We're using the pipe character so that we can use it as a column delimiter in Excel, so it's important that this character doesn't already appear in the original locale file. If it does, note the string where it appears so you can correct it in a later step. It's not something you'd normally expect to see in a string in the viewer, so this probably won't be an issue, but it's good to check, just in case.
  • We're using the caret character as a placeholder character that we can easily strip out later. It's necessary initially because, without it, the value string from the key/value pair will start with a double-quote character, which Excel will unhelpfully strip out. By having a character other than the double-quote at the front of the string, we prevent Excel from removing any subsequent quote marks. This character should also be unique, so it's a good idea to check for it in the existing locale files. If there's already a caret somewhere in a file, use a different unique character, or even a sequence of characters that doesn't already appear in the files.
• Open a new Excel workbook (or a new tab in an existing one) and paste the contents of your new text file into the spreadsheet. After pasting, ensure there's nothing in the B column -- i.e., there's only one column of text.
  • With the text you've pasted still highlighted in column A, switch to the Data tab and click on the Text to Columns button.
  • Select the "Delimited" radio button and click Next.
• Uncheck any delimiters that are selected by default. Check the Other box and in the field following it, enter a vertical bar. Click Finish.

• You should now have two columns in your spreadsheet: the keys in A and the values in B.
  • If there were any vertical bar characters in the original locale file, you'll need to scroll down to it and manually combine the extra cells into a single key and/or value entry.
• Select all of column B and do a search and replace. Search for ^ and replace it with nothing. If you substituted another unique character or string instead of ^, search for that instead. You should now have strings with their double-quotes and commas intact.

• Column C is where the localized strings should go.
  • In the accompanying sample spreadsheet, column C currently holds the invariant strings as place holders.
  • Note that the accompanying double-quotes and trailing comma are necessary for the json to be valid at the end. If you lose them from column C, you can add them back with the formula in column D.
• Enter the following formula in cell D2 (if you use a different row than row 2, adjust accordingly):

  =CONCATENATE(A2, " ", C2)

?

• Copy this formula to every cell in the column with a corresponding row of data (e.g., for the 2.7 Mapping.Infrastructure.json.js file, copy the formula from D2 down the column to D739, inclusive).Copy the values from column D (minus the header row, if applicable) and replace the corresponding lines of invariant values in the appropriate locale file.
  • For Mapping.xx-XX.json.js, you'll still need to translate the datepicker and timepicker values manually.

Very important: once you have finished editing your locale files, you should validate them to ensure that the json is valid. If the locale files are invalid json, the viewer will not load them. Common culprits for errors include unescaped quotes within value strings, missing comma after value strings, and an unnecessary comma after the last value string in an array (this is easy to do if you reorder the keys at any point).

Translating Subsequent Viewer Versions

Each new feature release of the HTML5 viewer (i.e., major or minor versions) will introduce new language keys; maintenance versions typically tend not to add new keys, although it does happen. Any release could also introduce changes to existing strings. When upgrading to a new viewer version, it's a good idea to compare the new locale files to their older counterparts to see what's new. If there are only a few changes, it may be feasible to simply merge the new keys into a copy of your older locale files and translate the new strings manually. If there are many changes, however, you may find it easier to repeat the process for creating a new translation.