> For the complete documentation index, see [llms.txt](https://help.form.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.form.io/dev/form-development/translations/resource-based-translations.md).

# Resource-Based Translations

Resource-based translations replace the embedded `i18n` definitions with a Form.io Language resource. Each submission holds one language’s translations, and a controller loads them with `form.addLanguage()` when a user selects that language. Non-developers can then manage translations without changing the application.

### Create a Language Resource

To use resource-based translations, first create a language resource that will contain each language's text terms and corresponding translations. To do so:

1. Create a Language resource within the Project, called **Language.**&#x20;
2. Within this resource, add a **Select Field** (typically called "Language") for the Language Code.\
   This maps the plaintext language name to the language identifier.
3. Within the Select Field's **Data tab**, set **Data Source** to *Value&#x73;**.***
4. For each language the form is localized to, create a **Label** identifying the plantext language name, and a **Value** identifying the language identifier.<br>

   ![Setting the available languages in a Language Resource.](https://656584932-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDuAwTOTr6NFMpkfgwq9x%2Fuploads%2FWJqW5tkqDOPHSMQoHJgZ%2Ftranslation1.png?alt=media\&token=277eea38-e97e-4094-ad59-dbd44b36f040)
5. Add a **Data Map** to the Language Resource (typically called "Translation"), which contains **Text Field** that maps the default language text to the translated text, like the following:

![The key-value pair in a Translation Resource Data Map.](https://656584932-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDuAwTOTr6NFMpkfgwq9x%2Fuploads%2FOpV490VQ4R9dxEuYE2VR%2Ftranslation2.png?alt=media\&token=09964017-fd9b-4df4-8d8d-0505d3bb8bc3)

The completed resource will look like the following:

![](https://656584932-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDuAwTOTr6NFMpkfgwq9x%2Fuploads%2FkcVh9mnscbZ5XZhRHXSf%2Ftranslation3.png?alt=media\&token=be89570b-d809-460e-bf65-fa8046050fb7)

6. Press **Create Resource** button to create the new Resource.

## Filling the Language Resource

Once this is created, use the resource to create a new submission for each translation. The following example illustrates the fields for Español:

![](https://656584932-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDuAwTOTr6NFMpkfgwq9x%2Fuploads%2FitqqMmJ5dmgNoJdi6Kxk%2Ftranslation4.png?alt=media\&token=113fbd9c-6e14-4186-984e-8447200bade2)

Each submission will add the "language". This will be used to manage all of the translations in a standard way. Input the rest of the language translations the same way until there are multiple to choose from.

## Language Resource "Read All Submissions" Access

For most applications, the end user will be authenticated when they are switching between languages. In some cases, the user may be anonymous. As with any resource, ensure that the proper Role has access to the *Read All Submissions* permission within the **Access** section of the Language form.

## Dynamic Language Controller

To allow a user to dynamically switch languages, write the logic that will perform the dynamic language display. The form controller that establishes a dynamic language is straightforwad.\
It will send an API call to the form resource submission API (where the user has Read All submission access) to fetch the Submission that is associated with the language that was chosen.

{% hint style="info" %}
Implement some in-memory cache to reduce re-fetching the submissions as the user clicks between different languages.&#x20;
{% endhint %}

Put most of the logic within the `window.setLanguage` method. Here is what the Form Controller should look like:

```javascript
var languages = {en: true};
window.setLanguage = function(lang) {
  // If we already have loaded the language, then just set it with the sdk.
  if (languages[lang]) {
  	return form.language = lang;
  }
  
  // Fetch the language from the Resource.
  Formio.fetch('https://formiodata.form.io/language/submission?data.language=' + lang).then(function(resp) {
	  return resp.json();
  }).then(function(result) {
    // Ensure future sets will use the cached language.
  	languages[lang] = true;
  
    // Add this language.
    form.addLanguage(lang, result[0].data.translations);
    
    // Set this language.
    form.language = lang;
  });
};
```

Here is a JSFiddle demonstrating this dynamic loading system working:

{% embed url="<https://jsfiddle.net/TanyaFormio/8fu9d603/>" %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.form.io/dev/form-development/translations/resource-based-translations.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
