Translation Codes allow you to take any value and change it to be something else. This is often necessary when sending data to external systems, including your student information system.
You may be familiar with Export Values on Prompts, where you have an entry term option Fall 2020, and your SIS expects F20, so you configured this as an Export Value on the Prompt.
Translation Codes work in much the same way, but they can be used with any value - not just prompt-based custom fields.
To create Translation Codes, you must first create a Translation Key with the basic settings that each code associated with the Key will share.
Translation Key & Code Configuration Settings
Translation Codes are associated with a key, much like Prompts, that groups the codes together. All Translation Codes with the same key have the same Value Type.
There are five Value Types that can be used when configuring Translation Codes:
- String (Discrete Values)
- Real Number (Inclusive Range of Values)
- Integer (Inclusive Range of Values)
- Date (Inclusive Range of Values)
- DateTime (Inclusive Range of Values)
When you create a New Key, you will have to select the Value Type for all of your translation codes. You are also able to enter Default Export Values if you would like values that do not equal any Translation Code values within the key group to always send a specific value. Once a key has been created, you may use the Edit button at any time to update these settings.
The Value Type String takes a single string value, which means that String-based Translation Codes have a one-to-one relationship with the potential values.
The Value Types: Real Number, Integer, Date, and DateTime will convert the value to be translated to the selected type and then find the Translation Code where the value falls between the Minimum Value and the Maximum Value. These values are inclusive, which means that if you have a Real Number translation code, and you enter 1.5 as the Minimum Value and 3.49 as the Maximum Value, any value starting at and including 1.5 up to and including 3.49 will use that Translation Code. For Translation Codes where the values are discrete rather than a range, simply enter the same value for both the Minimum Value and the Maximum Value.
While on the Translation Key page, click New Translation Code to add codes to the Translation Key group.
Each Translation Code can have up to five Export Values configured, so the same Translation Codes can be used for multiple systems or multiple fields within the same system, if the Minimum and Maximum Values are the same.
Use in Query
Once you have configured Translation Codes, they are available to use with exports within the Query tool.
When editing an export, update the Export Value setting to Translation Export Value (Translation Export Value 2 - 5 are also available), and then select the Key of the Translation Codes that you would like to use for that particular export.
Important!
Null Value setting - Keep in mind that if you do not have a Default value configured for the Translation Code Key, the result will be Null (blank) if the value did not match any of the Translation Codes with the selected Key. You can configure a Null Value on the export to provide a default value for just that export.
If a Default value is configured for the Translation Code Key, then the value will never be Null (blank).
Use in Forms
Translation Codes are also available to use in calculated form fields.
To use Translation Codes, drag a Translation form element from the Form Builder Palette onto the form (the order in which this element appears on the form does not affect its behavior).
Translations are hidden elements on the page, but provide a Label for the translation code for your own use while editing the form.
The Script Key is what you will use to reference this translation in a calculated field, so this value should be unique on the form, and it should not contain special characters.
The Data Type specifies what the output value is typed as. For example, if you are planning to use the translation within a math calculation, the Data Type should be Real (if the value needs to include decimals) or Int (if the values being calculated are only whole numbers).
Choose one of your configured Translation Codes from the select list.
Select which Translation Export value should be used for this translation.
To use this Translation, add another form field with a calculation formula that contains: translate("key", @export), where key would be replaced with the Script Key that you configured, and export would be replaced with the export key of the form field that you wish to translate.
Important!
If a string value is being translated, append the export key in the calculation formula with "_text".
In these cases, use the following format for the calculation formula: translate("key", @export_text)
For example:
To use this to translate the form field with the export key reader_rating, the form field calculation will include: translate("rating_number", @reader_rating)
Using just the above formula will result in the calculated form field equaling the translation value, which is useful to save additional form field values based on the translation of another form field.
The translation can also be included within more complex formula logic, including math calculations. For example, since the data type of the above example is a number, the calculation can be:
5 * (translate("rating_number", @reader_rating) + @extra_rating)
Important!
A single form can have any number of translation form elements included. It is important to note that if the same Translation Code and Export Value will be used more than once, you can reference the same translation form element multiple times.
You need to add multiple translation elements if your translations use different Translation Codes, or if you are referencing different export values (e.g. Export Value for one translation and Export Value 2 in another).
The translation elements are referenced by the Script Key setting, so always be sure to give these elements unique Script Keys.