Skip to Content

Translation design


This page goes over the design of the Translations system.


Translations are stored in bundles. Bundles are comprised of translation keys which map to translations.

Image 2017 3 27 16 29 39

In the Bundle described above, a control name or label with the value "Customer" will be translated to English (US), Spanish, or Japanese according to the user's profile.

Translation key

The Translation Key is used to lookup a translation. The Translation Key is the text that appears within the Vinyl IDE for your app. When you import translation keys for your app, Vinyl pulls in values from all of the control names, labels, events, and validation messages.

Most of the time the translation key will be identical to the default translation (English-US). However there are occasions where it is beneficial to create a logical "surrogate" key to differentiate two translations.

As an example, let's say that you have two identically named controls in your app - "Building":

  • In one case, Building refers to a physical structure.
  • In the other case, Building refers to the action of constructing a thing.

Although these two English translations are equivalent, other languages may use distinct words. For instance in German, the word for building (structure) is "Gebäude" whereas the word for building (action) is "Aufbau". To solve this problem, you can enter a distinct control name such as "Building_Structure". In your bundle, you would then customize the English translation of the "Building_Structure" translation key to be "Building" and the German translation to be "Gebäude".

App bundle linkage

Apps are linked to one and only one Bundle. Any data sources that are linked to an app also become linked to the app's bundle. For instance:

Image 2017 3 27 16 38 21

A Bundle can also be linked to from multiple apps.

Image 2017 3 27 16 39 48

In general, it is safest to have one bundle per app. This becomes particularly true when you go to migrate your LP from Dev > QA > Prod. Bundles are packaged in with your app in an LP and following the one app, one bundle rule helps to avoid collisions when installing separate LP files.

Translated items

The following items are currently handled by the Translation system:

  • Control names, labels, short labels
  • Event pre, post success, post failure messages
  • Validation message
  • Templates
  • Columns marked supports translations

Determining user language

The users language is determined by evaluating the following (in order):

  1. Vinyl user profile language setting.
  2. $cultureId passed in via the URL query string. This will also set the Vinyl culture cookie.
  3. Vinyl culture cookie.
  4. The browser Accept-Language request header.


For case #4, Vinyl will choose the highest ranked language. There is no fallback logic to try and choose the next best language.

Substitution formats

As well, translations can be tagged with a substitution format.

  • Default: Format will try to be determined automatically based on the string content.
  • None: No substitution necessary
  • DotNet: Format uses numbered brackets to substitute parameters
    • E.g. "The {0} fox jumped over the fence".
  • Handlebar: Format uses named brackets to substitute parameters like column name.
    • E.g. "The {AnimalColour} fox jumped over the fence".