Translation Codes

Translation codes change a stored value to another value, either between systems or within Slate. This is often useful when you send data to an external system, such as a student information system (SIS). For example, a current term value of Fall 2023 can be translated to F23 when the receiving system expects the shorter code.

If you have used Export Values on Prompts, translation codes work in a similar way. Translation codes can be used with values beyond prompt-based custom fields.

Common use cases for translation codes include:

• Changing a program name to an application deadline

• Changing a major to a college

• Grouping or converting GPAs

• Changing subject lines in mailings

• Values in scheduled exports through queries

• Discount codes in forms

Each translation code can store up to five export values, so the same translation code can support multiple receiving systems or multiple fields in the same system.

Creating a translation code

Translation codes are grouped together under a translation key.

To create a translation key:

1. From the main navigation, select Database.

2. Under Automations, select Translation Codes.

3. Select New Key.

4. Configure the following settings:

   • Key: Keys describe and group translation codes. Each key must be lowercase and include no spaces. Translation codes that share the same key must have the same value type.

   • Type: Determines what type of data the translation code expects as input.

     • String: any text string of characters

     • Real Number: numbers that include decimals

     • Integer: whole numbers without decimals

     • Date: a date value

     • DateTime: a timestamp that includes date and time

   • Default Export Value (1-5): Enter up to five fallback values to use when an input value does not match any translation code in the key. For example, No rating or Invalid date.

5. Select Save.

You are redirected to the Translation Codes page for the key you just created. You can edit the key later to update key-level settings, including default export values.

To create translation codes:

1. Select New Code.

2. Configure the following settings:

   • Status: Active

   • Value: The input value

     • String values must match exactly for a translation to occur.

     • This option appears only for string value types.

   • Minimum/Maximum Value: The minimum and maximum possible input field value

     • Appears for all non-string value types.

     • Values are inclusive, treated as less-than-or-equal-to and greater-than-or-equal-to operators.

     • For a discrete non-string value, enter the same value for both the minimum and maximum value.

   • Export Values (1-5): The new values to which the input values are translated

3. Select Save.

Create as many codes as necessary for your process.

Importing translation codes

Import translation codes in batch by adding the Translation Code Import source format to your database from the Source Format Library.

Example: Primary citizenship -> country code

Translation codes can translate the value of query exports.

For example, in a scheduled export query to another system, you may want primary citizenship information, or country of origin, to appear as a particular country code.

Best practice: Upload translation codes in bulk with the Translation Code Import source format.

In a query, create an export. In this example, we select Citizenship (Primary). The Edit Part popup appears.

Configure the following settings:

• Export Value: Translation Code

• Translation Key: Select your translation key from the list. In this example, we select country_code.

• Translation Value: Select the translation export value that fits your situation. If you have more than one translation value, reference your list of translation values for this key in Database → Translation Keys.

• Null Value: If you did not set a default export value for the translation key and nothing matches your translation codes, Slate defaults to Null, or empty. You can configure a Null value here to provide a default value for just this export.

Select Preview Results to see the translated value:

Example: Date range → season

You can translate date ranges to season export values.

Example: GPA -> rating

You can use translation codes to assign GPA ranges to your own rating scale.

Minimum and maximum values are inclusive. Say you enter 1.5 as the minimum and 3.49 as the maximum. All values starting at and including 1.5 up to and including 3.49 would qualify for the code that translates to 1 and Needs Improvement.

This example also uses a default export value to capture values that do not fall into the above range.

A default export value also works with the string data type.

Example: Calculations in forms

Translation codes can be used in form fields with calculations.

Note

Make sure you have a field to store the translated value.

Add a form field for the input value

Create a form field to accept the input value from the user. In this example, the user enters their GPA in a text field.

Copy the export key value, in this case sys:school:gpa, because you need it later. Save the field.

Add the Translation element from the form palette

Select the Translation element from the form builder palette. The Translation element is hidden on the form. Its label is for your own use while editing, and the order in which the element appears on the form does not affect its behavior.

In the Edit Field popup, configure the following settings:

• Status: Active

• Label: Enter a name for internal use.

• Script Key: Enter a unique key to be referenced by a calculated field on the form, which you will create next. In this example, we enter rating.

• Translation: Select the translation code to use. In this example, rating.

• Translation Export: Select an export value from your possible translations.

Save the element.

Add a hidden field with a calculation to translate the input value

Add another field. Configure the following settings:

• Label: Tell internal users that this field is a destination for translation.

• System Field: Select the field that represents the value to be translated to. In this case, our Rating field.

• Calculation Formula: Enter translate("<SCRIPT KEY>",@<EXPORT KEY>), where:

  • <SCRIPT KEY> is the script key from the Translation element. In our case, rating.

  • <EXPORT KEY> is the export key of the input field you created earlier. In our case, sys:school:gpa.

• Options: Select Hidden / accessible through script.

Save the field.

Additional configurations to the calculation formula

• A form can have multiple Translation elements.

  • If you want to use the same translation code and export value more than once, you can reference the same Translation element multiple times.

  • Multiple Translation elements must be included in the form when using different export values for a single translation code. For example, Export Value 1 for one translation and Export Value 2 for another.

• If a string value is being translated, append _text to the export key in the calculation formula, as in translate("<SCRIPT KEY>", @<EXPORT_KEY>_text).

• For translating form fields with the export key, such as reader_rating, the calculation formula should contain that key, as in translate("rating_number", @reader_rating).

• Translation codes can also be included in math calculations, like this example: 5 * (translate("rating_number", @reader_rating) + @extra_rating).

Test the form

Make a test submission on the form. Then, make a Quick Query for the target export on the test record to see whether the value has been translated.