Adding a language to Tableau Server 9.0 and above

If you find yourself embedding Tableau Server but serving areas with languages that are not part of the standard set provided by default, it is possible to add support for additional language.

DISCLAIMER: Not supported by Tableau whatsoever, may break at any time, may void your warranty, proceed with caution!!!.

Adding a New Language

There are two parts to Tableau Server that are visible to the end user: vizportalclient, the UI of Tableau Server and vizqlserver, which draws all of the vizes that are embedded in an iframe. These instructions will add a language to vizqlserver, but we’ll also do some work on vizportalclient to make sure everything is in order.

Inside the postgreSQL repository, there is a table called “language_prefs”. If you SELECT * this, you’ll find the languages that appear in the Language selection box for each user. Tableau Server also uses this table on startup to determine which languages exist in the server. To add a Russian language pack:

INSERT INTO language_prefs VALUES
(‘ru’,’русский’,900,’/help/en_US’,’ru_RU’)

The third value fixes the order the languages appear in the selector box for each user. The default pattern goes up by 100 each time, and there are 8 original languages, so our first new language is 900 and we’ll just increment from there. The fourth value is the help file, which we’ll leave pointed to the English help, because that’s one thing we’re not going to take into our own hands for translation.

If you just tried this with the readonly user, you received a message that you don’t have privileges. That user isn’t named “readonly” for nothing. To do this warranty voiding action, you’ll have to find a user with admin rights, which might be mentioned in various blog posts. If you can find the user and its password, you are qualified to continue.

At this point, when you restart Tableau Server it will try and look for the Russian files. They don’t exist yet, so we better create some. The first place we look is

C:\Program Files{ (x86)}\Tableau\Tableau Server\{version}\vizqlserver\public\v_{versionnumber}\javascripts\

In this directory you’ll find a set of files named “jsstrings_”. Open up “jsstrings_en.js” and you’ll find a JavaScript object with keys and text that clearly line up with every bit of text found in the viz iframe. We can use this as our template for translation. Save As a copy as “jsstrings_ru.js”, and then modify something you’ll see immediately once all the changes are in place. I suggest “ToolbarDownload:” or “ToolbarEdit:” as good candidates.

Eventually you’ll want to translate all of these strings so that the end user gets the desired experience. This takes care of vizqlserver — the jsstrings file controls it all. Now let’s do some work on vizportalclient just to make sure the server doesn’t balk when it looks for a language. Let’s look in

C:\Program Files{ (x86)}\Tableau\Tableau Server\{version}\vizportalclient\public

Notice that there are directories for each language. Let’s copy the ‘en’ folder and rename that copy ‘ru’. If you compare the files in each of the directories, you’ll notice that they are all identical, with placeholders where the translated text goes. This is convenient and means there is no danger in just replicating the ‘en’ folder for each new language we add.

When if you look into

C:\Program Files{ (x86)}\Tableau\Tableau Server\{version}\vizportalclient\public\loc

you’ll find “__.json” files like “en.json” which include most of the strings that are used in the Tableau Server UI. Let’s just copy en.json and rename is “ru.json”. You could translate these later if you needed to, but for now let’s leave them in English so we can still navigate when we test our new language.

C:\Program Files{ (x86)}\Tableau\Tableau Server\{version}\vizportalclient\public\locales does not need any changes — the codes for almost every locale is already here and ready.

There are two more files we need to change to enable the new language, and we make the same change to both of them:

C:\Program Files{ (x86)}\Tableau\Tableau Server\{version}\vizportalclient\public\vizportalLibs.js
C:\Program Files{ (x86)}\Tableau\Tableau Server\{version}\vizportalclient\public\messageformat_locales.js

In later version (10.2 for sure, probably earlier), vizportalLibs.js is replaced by vizportalMinLib.js, but it has the same section to edit.

Each has a section that looks like:

MessageFormat.locale.de=function(n){return n===1?”one”:”other”}
MessageFormat.locale.en=function(n){return n===1?”one”:”other”}
MessageFormat.locale.es=function(n){return n===1?”one”:”other”}
MessageFormat.locale.fr=function(n){return n===0||n==1?”one”:”other”}
MessageFormat.locale.ja=function(n){return “other”}
MessageFormat.locale.ko=function(n){return “other”}
MessageFormat.locale.pt=function(n){return n===1?”one”:”other”}
MessageFormat.locale.zh=function(n){return “other”}

We want to add a line recognizing our new locale:

MessageFormat.locale.ru=function(n){return n===1?”one”:”other”}

I’m duplicating the English options, but it might make sense to use that of Chinese or Korean on languages in other character sets. I’m not entirely sure what this does, but it seems to affect pluralizations in the angular.js framework underneath. We’re not concerned here with vizportal so much so I just want everything my vizportal to show in English for the time being.

At this point, you’ve set up enough to restart the server and see your new language be available. Every time you update the language file, you may need to clear your browser cache to see the changes. You do not have to restart server — the JSON strings are actually brought into the browser fresh from the server with a browser cache refresh (at least in the vizqlserver process).

Note: You’ll want to copy all of the custom files you create before you do an upgrade, then put them back in place afterward, checking that no new values have been added to the jsstrings files for the supported languages. You also should keep a copy of the original vizportalMinLibs.js and messageformat_locales.js that you can substitute back in place so nothing gets messed up when you upgrade.

Note 2: In 10.0+, every content file has an equivalent .gz file which will be read if it exists. You can rename all of these with “.old” at the end so that the Apache server will ignore them. Or you can gzip your modified files to replace them. You also MUST follow these steps to disable server-side caching so that your new files will be delivered.

Enabling A NEW Language For a User

Each user in Tableau has language and locale preference settings. You can see your own using My Account Settings

account settings

or set them for any user you can admin using the Site Users page. By default these are set to “Unspecified”.

unspecified language locale

When these are “Unspecifed”, Tableau Server will try and use the locale settings in the browser to determine which language to use. However, this functionality is hard-coded and not changed by adding our new language in the repository. Each language that is not officially supported has its own default that it goes to (most of them default to en_US surprise surprise).

So to make our new language work, we have to specifically select it in the list.

new russian language

That’s kind of a pain for every user, particularly in embedded environments. There’s currently no way to set Language and Locale for a user via the REST API. If we trust ourselves enough, it is possible to set this via the repository. In the user_prefs table, each system_user_id that has ever had settings set has an entry, with language_id and locale_id fields. These match up to the language and locales that we put in the language_prefs table in the beginning. You can match the system_user_ids with the visible Tableau usernames by joining the system_users table and looking at the system_users.name column. If you feel confident in updating the repository, you can do an update to the user_prefs table to set languages programmatically.

SELECT *
FROM user_prefs up
JOIN system_users su on up.system_user_id = su.id
WHERE su.name = '{username}'
Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s