# Create translation sets and links
A **translation set** is a list of translation mappings between two **value sets**. This is helpful if your connection sends messages with different codes or values than your organization uses. Differences in code sets (or Redox **value sets**) might confuse or complicate ingesting data on your side.
Instead of wasting time detangling codes, you can use a **translation set** to define how two **value sets** should map to each other. You can use translation sets to:
- Save time: Automatically translate codes for smooth data exchange instead of manually tweaking data.
- Get relevant data: Make sure data is delivered in a code set that’s pertinent to your context and system.
## Definitions
### What’s a value set?
A **value set** is a list of values that should be translated during the process of data exchange. A value set could be a common code set like LOINC, SNOMED, or any other you know. It could also be a custom code set that your organization uses.
You must define a value set for each system’s code set. This means you should have two value sets to make up one translation set. Essentially, there should be a value set for each code set you want to translate to or from for each system.
### What’s a translation set?
A **translation set** is a list of individual translations between two value sets. A **translation** maps either:
- one value to one value
> **Example: WISCONSIN to WI**
>
> Your connection stores an address value as `WISCONSIN`. Your system stores the same address value as the abbreviated `WI`. A translation can resolve the `WISCONSIN` value at the specified field path to the value you use instead.
- multiple values to one value
> **Example: WISCO or WI to WISCONSIN**
>
> Your connection stores an address value as `WISCONSIN`. Your system stores the same address value as either the abbreviated `WI` or `WISCO`. A translation can resolve your `WI` or `WISCO` values at the specified field path to the value your connection uses instead.
You can either build or import translations when creating or editing a translation set in the dashboard.
> **Mapping operations**
>
> **Translations** are a mapping type of operation, which is one of many operations that can be applied during log processing. [Learn about operations](/basics/data-exchange-with-redox/operations-for-data-processing).
After you link a translation set, we run our magic in the background so that you both send and receive data in the expected format.
> **Translation sets vs. Redox base config translation**
>
> Translation sets are different from Redox base configs, which include their own base translation. Our base translation provides a consistent experience for all our customers.
>
> For each data model, you can see which fields are included in Redox’s base config translation by using the toggle for Show Translation Fields. Review our API specs:
>
> - [Redox data models](https://docs.redoxengine.com/permalink/data-model-landing-page)
> 
> - [Redox FHIR resources](https://docs.redoxengine.com/permalink/fhir-resources-landing-page) or [FHIR notifications](https://docs.redoxengine.com/permalink/fhir-notification-landing-page)
> 
## Prerequisites
- All environment users can view translation sets. However, a user must be assigned to an **engineer** or a **support** role to manage translation sets. [Learn about user roles](/basics/managing-access-for-your-redox-organization/what-are-user-roles).
- You must have already defined two **value sets** either in the Redox dashboard or in a CSV file (must have at least 25 defined values) to create a translation set. [Learn how to create value sets](/how-to-use-redox/create-value-sets).
## View existing translation sets and links
1. Log in to the Redox dashboard.
2. From the side nav menu, click the **Operations** drop-down.
3. The Operations options expand. Click the **Translations** option.
*Translations in the side nav*
4. By default, the Value sets tab opens. Click the **Translation sets** tab.
5. Any existing translation sets in the environment display. Search for or use the filters to narrow down the list of displayed translation sets. Or, **click the subscription link** to expand a translation set row to view link details.
*View translation sets and links*
6. To review a specific translation set, click anywhere its **row** to open the Details page.
## Create a translation set
1. Follow the steps to view translation sets.
2. Click the **New** button.
3. The create form opens. Enter a unique **human-friendly name** up to 500 characters (names must be unique within the environment).
4. You can either build translations from existing value sets in the Redox dashboard or import value sets with translations defined in a CSV file.
1. To build, click the **Build translations from existing value sets** option.
1. In the From drop-down on the left, select the **value set** you want to translate FROM.
2. In the To drop-down on the right, select the **value set** you want to translate TO.
2. To import, click the **Import new value sets with translations in a CSV file** option.
Choose this option if you have lots of values and would prefer to handle mapping translations in a CSV file. _Imported value sets are only temporarily created in the dashboard until you finish creating the translation set_.
1. Instructions display for the import. Click the **Upload a CSV file** button.
> **CSV file requirements**
>
> A CSV file imports successfully if it has:
>
> - exactly two columns (i.e., one column per value set);
> - a header row with the value set names;
> - at least one defined translation (i.e., value in column 1 mapped to value in column 2) but no more than 7,500; and
> - no duplicate values in column 1.
2. A modal opens. Select the **CSV file** you want to import.
> **CSV file errors**
>
> If your file doesn’t meet these criteria, you might get any of these errors:
>
> - `CSV file or format is invalid.`
> - `Duplicate value "" found on column 1 of lines: `
> - `CSV file must not have more than 7,500 rows.`
>
> Make sure that your CSV file is properly formatted to avoid these errors. If you do get one of these errors, fix the issue, then re-select it to validate again.
3. The file passes validation.
5. The default directionality and the selected value sets populate. [Learn more about directionality](https://docs.redoxengine.com/permalink/4GJXunyoAI3s05VrrRkJ09/#technical-reference-directionality). Next, build your translations. From the drop-down fields, select the **values** to map to each other.
6. Click the **Add** button to add a new row for as many translations as you need (up to 7,500 translations).
> **"In use" values and directionality**
>
> An “in use” label appears next to any FROM value that has already been selected. You can’t map a FROM value more than once. However, you can map multiple FROM values to the same TO value. This changes the directionality to **uni-directional**.
7. Translation sets are case sensitive by default. If your data won’t be consistently cased, toggle the **Case sensitive** option to OFF. This is helpful to avoid creating unique translation sets just for differing cases.
If you turn off case sensitivity, any value that matches a FROM value, regardless of casing, will be translated to the indicated TO value.
> **Disabled case sensitive option**
>
> You might see the case sensitive toggle disabled. This happens when:
>
> - There are at least two FROM values that would match without case sensitivity (e.g., `WISCONSIN` and `wisconsin`). Remove any conflicting FROM values to enable the case sensitive toggle.
> - The translation set has at least one TO-FROM link, and there are at least two TO values that would match without case sensitivity. Remove any TO-FROM links or duplicate TO values to enable the case sensitive toggle.
8. Review the table with your translations and make any changes. You can edit by clicking the **drop-down fields** in the rows or click the **Delete** icon to delete translations.
9. Click the **Create set** button.
*Create translation set*
10. Follow the instructions to link the translation set to apply these translations to your traffic.
## Link a translation set
To apply translations, you have to link the translation set to the relevant **log processing stage** and **field path**.
1. Follow the instructions to view existing translation sets.
2. Find the translation set you want to link and click anywhere in its **row**.
3. The Details page opens. Under the Translation set links section, click the **Link** button.
4. The create form opens with the translation set name displayed.
5. Under Set directionality, select the **radio button** to specify the direction the translation should be applied.
If you want a translation set to be applied in both directions, you must create two separate links (one for each direction). However, you can only create one link at a time. [Learn more about directionality](https://docs.redoxengine.com/permalink/4GJXunyoAI3s05VrrRkJ09/#technical-reference-directionality).
> **Uni-directional sets**
>
> You can’t link a uni-directional translation set in the TO-FROM direction.
6. Select the **connected organization** with the subscription you want to link the translation to.
7. Click the **Subscription** drop-down.
8. A modal opens with the subscriptions in your environment. Use the Search field or the Connection drop-down to narrow down the available options. Or, use the page options at the bottom of the modal to navigate through the pages.
9. Select the **radio button** of the subscription you want to link a translation set to, then click the **Select Subscription** button.
10. The Data model field populates with the subscription's data model. This can be changed if you're using composable processors and expect the data model to change during processing. [Learn more about composable processors](/basics/data-exchange-with-redox/orchestrate-your-unique-data-workflows).
11. Select the appropriate log **processing location** to link the translation set to. [Learn more about log processing stages](https://docs.redoxengine.com/permalink/790exE7anSFdJdupyjnidt/#processing-stages-and-operations).
> **Links and processing stages**
>
> You can link a translation set to up to four log stages, depending on whether your organization owns both sides of the subscription (i.e., both the source and destination). [Learn about log processing stages](https://docs.redoxengine.com/permalink/790exE7anSFdJdupyjnidt/#processing-stages-and-operations).
>
> - If your organization owns both sides of the subscription, you can link a translation set to any of the stages, whether **inbound** or **outbound**.
> - If your organization owns only one side of the subscription, you can link a translation set to the two log stages you own. For example, if you own the source side of the subscription, you can link a translation set to the `source-request` or `source-response` stages.
>
> Your connection could also link their own translation sets to their processing stages. This means translation is likely happening to more than just one field, and there could be different translation happening on both sides of the exchange.
*Create a translation set link*
12. Select the **field path** you want to link the translation set to.
A **field path** is like an “address” for a particular field and value in the data payload. You can link a translation set to one or more field paths. This means you can use one translation set to update multiple values in a data payload.
1. A modal opens for testing the field path and value. You can change your selection by clicking the **Field Path** drop-down again to view a list of fields.
2. Once you have the correct path, use the validation tools to test your choice.
_Or, if you don_’_t want to test, you can skip and proceed to the next step._
1. Find a log payload for the subscription you want to translate. [Learn more about searching for logs](/how-to-use-redox/search-for-logs).
2. Copy and paste the **log payload** into the **Test Message** section.
3. On the right side of the modal, under **Field Values**, the value that displays is the one found at the field path you selected.
> **No Redox validation**
>
> Redox doesn’t validate the translation set link. But this step gives you an idea of whether you selected the right field path by using an existing log payload.
3. Click the **Select** button on the bottom right of the modal.
*Select and test a field path*
13. Click the **Add field path** to repeat the process for as many field paths as you need. This is what allows a translation set to alter multiple values in one data payload at a time.
14. Click the **Create** button.
*Click the Create button*
15. The new link appears in the table and automatically applies to the linked subscription’s traffic.
> **Operation details in logs**
>
> If a log has used any custom operations, you can view the related operation details when you click the related processing stage. Learn about data operations and:
>
> - [log details for filters](https://docs.redoxengine.com/permalink/4zsR9aQxb4vJmTK7jPzWj2/#log-processing-and-filters)
> - [log details for translation sets](https://docs.redoxengine.com/permalink/790exE7anSFdJdupyjnidt/#data-operations)
> - [log details for config modifiers](https://docs.redoxengine.com/permalink/790exE7anSFdJdupyjnidt/#config-modifier-details)
16. Repeat this process for as many links as you need.
## Edit a translation set
1. Follow the steps to view translation sets.
2. Find the translation set you want to edit and click anywhere in its **row**.
3. Click the **Edit** button.
> **Editing promoted assets**
>
> You can’t edit production assets if they’ve been promoted from staging. First edit the asset in staging, then re-promote to production.
4. The edit form opens. Add, edit, or delete translations in the set.
> **Edit values in a translation**
>
> Remember to edit a value set first if you need to edit specific values in a translation. [Learn how to edit a value set.](https://docs.redoxengine.com/permalink/57h6bja3T7Qy0Mf1ai7uMQ/#edit-a-value-set)
> **Changing directionality**
>
> A translation set is bi-directional by default. However, a bi-directional set changes to uni-directional if you add at least two mappings with the same TO value. You must remove any TO-FROM links first, though, since you can’t have TO-FROM links with duplicate TO values.
>
> To change a uni-directional set back to bi-directional, you must remove all mappings with duplicate TO values.
> **Inactive value sets**
>
> A translation set may point to an inactive value set version. However, once you edit an active translation set, it will automatically point to the latest active version of value set(s). In other words, you can’t edit an active translation set with outdated value set(s).
>
> If you don’t want to use the active version(s) of value sets, you can cancel out of any edits to the translation set.
5. Click the **Save** button.
*Edit a translation set*
## Delete a translation set
1. Follow the steps to view translation sets.
2. Find the translation set you want to delete. Click the t**hree-dots** icon, then the **Delete** option.
3. A confirmation modal opens. Click the **Delete** button.
*Delete a translation set*
## Edit or delete a translation set link
1. Follow the steps to view translation sets.
2. Find the translation set with the link you want to delete and click anywhere in its **row**.
3. The Details page opens. Under the Translation set links section, find the link you want to edit or delete. Click the **three-dots** icon.
4. From the drop-down menu, click the relevant option.
1. Select the **Edit** option.
1. The edit form opens. Edit any of the details, then click the **Save** button.
*Edit a translation set link*
2. Select the **Delete** option.
1. A confirmation modal opens. Click the **Delete** button.
> **Deleting a translation set link**
>
> You can delete a translation set link that’s in use. Logs will still process, but without the translation set link, no translation will occur.
*Delete a translation set link*
## Promote a translation set
During implementation, you can build and test a translation set in a staging environment. Once you’re confident it works, you can promote it to production.
When you promote, the value set is automatically promoted, too. Value sets can’t be promoted on their own.
Promoting an asset saves time and avoids introducing errors by having to rebuild it in a different environment. [Learn more about promoting assets](/implementation-guide/promote-assets-in-your-redox-organization).
1. Follow the steps to view translation sets.
2. Make sure you’re in a **Staging** environment.
*Select the staging environment*
3. Find the translation set you want to promote and click anywhere in its **row**.
4. The Details page opens. Click the **Promote** button.
5. A confirmation modal opens to acknowledge that you’re exiting staging and proceeding to production. Click the **Proceed** button. Otherwise, click the **Cancel** button to discard the promotion.
*Promote a translation set to production*
6. The Details page in the production environment opens.
1. To make any changes to the translation set, click the **Go to Staging** button.
*Go to staging to edit*
2. A confirmation modal opens to acknowledge that you want to switch environments. Click the **Proceed** button to continue.
3. The Details page opens in the staging environment. [Follow the instructions to edit a translation set](https://docs.redoxengine.com/permalink/4GJXunyoAI3s05VrrRkJ09/#edit-a-translation-set).
4. Once changes are successfully made, re-promote the translation set to keep the assets in sync across environments.
7. Next, create subscription link(s) to apply the translation set in your production environment.
## Restore a translation set version
Every time you edit a translation set, you create a new version of the asset. You can restore a version of a translation set that’s not currently in use. This may be helpful when troubleshooting to see where an error might have been introduced or to resolve an error by using a version that worked previously.
1. Follow the steps for viewing translation sets.
2. Find the translation set you want to restore and click anywhere in its **row**.
3. The Details page opens. Click the **Restore** button.
4. A modal opens. From the drop-down, select a **version** to restore.
> **Restore notes**
>
> Restoring means activating a version that’s not in use. That means you can go backwards or forwards a version.
>
> Keep in mind you can’t restore a version that’s already in use or an asset that’s been deleted.
5. The diff view shows what’s different between the current and selected version. Review the differences, then click the **Restore** button.
> **Versions after editing**
>
> If you edit an asset after restoring a previously used version, a new version is created.
>
> For example, let’s say you were on version 3 and you restore version 2. Then you make and save edits to version 2. This creates version 4 of the asset. At that point, you can still restore to version 3 at any time.
*Restore a translation set*
6. For promoted assets, restoring a version only applies to the current environment. If you restore a version in staging, you might need to re-promote the asset if you want to apply it to production as well.
> **What happens to value sets?**
>
> If a restored translation set points to an inactive value set version, the restored translation set will continue to use the inactive value set(s). Translations will still process as defined by the inactive value set(s).
>
> However, once you edit an active translation set, it automatically points to the latest active version of value set(s). In other words, you can’t edit an active translation set with outdated value set(s).
*Unpushed changes*
*Out of sync versions*
## Technical reference: Directionality
A translation set is **bi-directional** by default. This means the values can be translated in either direction: FROM-TO or TO-FROM. When you map more than one value to the same value, the translation set becomes **uni-directional**. A uni-directional translation set can only be linked going FROM - TO.
A translation set can be either **bi-directional**, or **uni-directional**.
- **Bi-directional** (_default_): A translation can potentially be linked twice, meaning the translation could happen in both directions. For example, a translation that maps between Value A and Value B means that the values can be translated on both sides of the exchange, back and forth.
*Bi-directional translation set linked to two log processing stages*
- **Uni-directional**: A translation can only be linked once going in one direction. This works for translating one value to one or multiple values to one.
For example, if you have a translation from Value to Value B, the translation happens only once and won’t be translated back. Specifically, Value B wouldn’t ever be translated to Value A. You could also have a translation from Value A _or_ Value C to Value B.
*Uni-directional translation set linked to one log processing stage*
A translation set automatically changes from the default bi-directional option to uni-directional if you add translations for multiple values to the same value. This can only happen if you don’t have any other bi-directional links, however. To change a uni-directional set _back_ to bi-directional, remove all translations with mappings to the same value.
> **Platform API endpoints**
>
> This article describes how to manage translations and translation sets in the **Redox dashboard**. To manage translation sets via **API**, use these **Redox Platform API** endpoints instead:
>
> - [Create translation set](https://docs.redoxengine.com/permalink/8cd86192-98e3-5379-9f04-0c05d203108a-create-translation-set)
> - [Update translation set](https://docs.redoxengine.com/permalink/fc0064d2-f201-5fba-93ad-99670f9d49bb-update-translation-set)
> - [Delete translation set](https://docs.redoxengine.com/permalink/6010c75b-5f20-5a71-ba1f-e7a8247b2061-delete-translation-set)
> - [Restore translation set](https://docs.redoxengine.com/permalink/0411484a-7bb8-5022-bfab-fb3ba6886d26-restore-translation-set)
> - [Add translation](https://docs.redoxengine.com/permalink/fd1f656e-0671-5207-9a4e-666a45884c12-create-translation)
> - [Remove translation](https://docs.redoxengine.com/permalink/d8041ccb-5207-5693-9878-a7b76131c93b-delete-translation)
> - [Create link](https://docs.redoxengine.com/permalink/8726021f-509c-526e-b651-a0966aa56ecf-create-translation-set-link)
> - [Update link](https://docs.redoxengine.com/permalink/5c00e8cc-7801-52c8-a067-3976ae997710-update-translation-set-link)
> - [Delete link](https://docs.redoxengine.com/permalink/5b42ff36-d744-5760-8524-77061f8d9f8f-delete-translation-set-link)
> - [Promote asset](https://docs.redoxengine.com/permalink/00e540fd-52b8-5bcd-8b56-e392e9db575e-promote-asset)