> ## Documentation Index
> Fetch the complete documentation index at: https://flatfileinc-remove-rss-json.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Translating your Space

> translate and customize your Space with text overrides

<Snippet file="shared/dxpbanner.mdx" />

Tailor the language and text in your Flatfile Space with ease! This guide will
lead you step-by-step to allow you to both translate and personalize the text in
your Space in just a couple of simple steps.

## Available Languages

We support translations into these languages:

| Language                | Code       |
| ----------------------- | ---------- |
| German                  | de         |
| English                 | en         |
| English - Great Britain | en-GB      |
| English - Canadian      | en-CA      |
| English - South African | en-ZA      |
| Spanish                 | es         |
| Spanish - Latin America | es-419     |
| French                  | fr         |
| French - Canadian       | fr-CA      |
| French - France         | fr-FR      |
| Indonesian              | id         |
| Italian                 | it         |
| Japanese                | jp         |
| Korean                  | kr         |
| Malay                   | ms         |
| Dutch                   | nl         |
| Polish                  | pl         |
| Portuguese              | pt         |
| Portuguese - Brazilian  | pt-BR      |
| Swedish                 | sv         |
| Thai                    | th         |
| Turkish                 | tr         |
| Vietnamese              | vi         |
| Chinese - Simplified    | zh         |
| Chinese - Traditional   | zh-Hant    |
| Chinese - Hong Kong     | zh-Hant-HK |

<Tip>
  Need more languages? Reach out to us at
  [support@flatfile.io](mailto:support@flatfile.io).
</Tip>

## Setting the language on a Space

Flatfile will auto-detect the user's language based on their browser settings.
If the language is not detectable or is currently unsupported, the system will
automatically be set to English.

### Overriding the language

You can manually set the language on a Space using the languageOverride
property. This property can be set either directly on the Space or at the
environment level if the Space has not yet been created.

All users who use the Space will only see the language set in the language
override property. Browser settings will no longer be respected.

To specify the language, simply assign the appropriate language code (e.g., 'en'
for English, 'fr' for French, etc.) to the languageOverride property.

```jsx listener.ts theme={"system"}
listener.on("space:created", async ({ context: { spaceId } }) => {
  // This space will be in English regardless of the users browser settings
  const updateSpace = await api.spaces.update(spaceId, {
    languageOverride: "en",
  });
});
```

## Adding translations

### Creating your translation files

All our translation files can be found in our
[Platform-Translations repository](https://github.com/FlatFilers/Platform-Translations).
You can fork the repo or simply copy paste the files in the repository to create
your own translation files.

Simply update the values in each file with the text you would like to see.

Once you have created your own translation files, you need to make them
available to Flatfile. This is done via the translationsPath property.

<Tip>
  While creating your JSON translation files, you can opt for partial or full JSON objects:

  **Partial JSON Objects:** Just include those values you want to change. Be sure
  to maintain the same JSON structure to avoid errors.

  **Full JSON Objects:** Copy the translation file from our public repository and
  modify the values as required.
</Tip>

### Setting your Translations Path

To provide translations and text overrides you can use the translationsPath
parameter. You have the flexibility to set up translationsPaths at two levels:

* **Space:** Overrides the environment level setting.
* **Environment:** Used when no Space-level path is defined.

<Info>
  Set your translationsPath to the URL of your **english JSON file**. This should be the URL ending in `/locales/en/translation.json`.

  Don't have an english file? You can use any other language instead.
</Info>

Your `translationsPath` must meet a few requirements to work as expected:

1. It must be a string.
2. The string should be a publicly available URL that returns your JSON
   translation file.
3. It must follow this folder structure:
   ```
   yourCustomTranslationsDirectory/
       └── locales/
           ├── en/
           │   └── translation.json
           ├── es/
           │   └── translation.json
           ...
   ```
   where `yourCustomTranslationsDirectory` can be swapped out for any path
   desired.

<Tip>
  For our translations repository we would set our translationsPath to:
  [https://raw.githubusercontent.com/FlatFilers/Platform-Translations/main/locales/en/translation.json](https://raw.githubusercontent.com/FlatFilers/Platform-Translations/main/locales/en/translation.json)
</Tip>

### Implementing Translations Path

Set up your translations path using our API or the listener. This can be done at
both the Space and environment levels.

```jsx listener.ts theme={"system"}
listener.on("space:created", async ({ context: { spaceId } }) => {
  //set the translation path for the Space
  const updateSpace = await api.spaces.update(spaceId, {
    translationsPath:
      "https://raw.githubusercontent.com/FlatFilers/Platform-Translations/kitchen-sink/locales/en/translation.json",
  });
});
```

<Info>
  Currently we only offer translations and text overrides for the guest
  experience within your Spaces. These means there will be admin only areas that
  are not currently customizable.
</Info>

## Translating Your Custom Actions and Jobs

You can translate your own custom text used in your Actions.

Simply add the new keys to your translation.json file:

```json .../locales/en/translation.json theme={"system"}
{
  "mySubmitAction": {
    "label": "Submit",
    "description": "Done editing the data? Hit submit to send your data",
    "tooltip": "Submit your data",
    "outcome": {
      "heading": "Successful import!",
      "message": "All data has been submitted! You can now click the link below.",
      "urlLabel": "Return to the homepage"
    }
  }
}
```

Then instead of hardcoding strings directly into your action scripts, use JSON
translation keys. Refer to these keys in your script as shown below:

<CodeGroup>
  ```jsx sheet.js theme={"system"}
  sheets : [
    {
      name: "Sheet Name",
      actions: [
        {
          operation: 'Submit',
          mode: 'foreground',
          label: 'mySubmitAction.label',
          type: 'string',
          description: 'mySubmitAction.description',
          primary: true,
          tooltip: 'mySubmitAction.tooltip'
        },
        {...}
      ]
    }
  ]

  ```

  ```jsx listener.js theme={"system"}
  await api.jobs.complete(jobId, {
    outcome: {
      heading: 'mySubmitAction.outcome.heading',
      message: 'mySubmitAction.outcome.message',
      next: {
        type: 'url',
        url: 'https://myHomepage.com',
        label: 'mySubmitAction.outcome.label',
              },
    },
  });
  ```
</CodeGroup>

<br />

<Warning>
  If a translation key is missing from your `translation.json` file, the system
  will display the key itself as a fallback. Therefore, it's encouraged to
  always have a default language translation available to avoid showing raw keys
  to the users.
</Warning>

## Translating Your Documents

The same logic that applies to Actions also applies to your Documents. Just pass
in the custom translation keys that you added to your translation files!

<CodeGroup>
  ```jsx .../locales/en/translation.json theme={"system"}

  { "myDocument": { "title": "Your first Space!" "body": "# Welcome ### Say hello
  to your first Space in the new Flatfile!" } }

  ```

  ```jsx listener.js theme={"system"}

    await api.documents.create(spaceId, {
      title: "myDocument.title",
      body: "myDocument.body"
    });
  ```
</CodeGroup>

## Guidelines for Creating JSON Keys

When creating JSON keys, adhere to the following guidelines:

* **Alphanumeric Keys**: Ensure keys consist of alphanumeric characters to
  prevent issues with parsing.
* **Nested Structure**: Utilize at least one level of nesting (e.g.,
  `key1.key2`) to organize translations effectively and maintain readability.
* **Avoid Whitespace and Control Characters**: Refrain from using spaces,
  newlines, or tabs in your JSON keys to avoid potential issues.
* **Don't End Keys with File Extensions**: Avoid using file extensions (e.g.,
  .csv, .txt) as the terminal segment in a key. For instance, myFileAction.csv
  is discouraged, but myFileAction.csv.uploaded is acceptable.

<Info>
  Always validate your `translation.json` file to ensure it follows the correct
  JSON format to prevent errors during runtime.
</Info>

## Example Project

Find the Localization example in the Flatfile GitHub repository.

<CardGroup cols={2}>
  <Card title="typescript" icon="code-merge" href="https://github.com/FlatFilers/flatfile-docs-kitchen-sink/blob/main/typescript/localization/index.ts">
    Clone the Localization example in Typescript
  </Card>

  <Card title="javascript" icon="js" href="https://github.com/FlatFilers/flatfile-docs-kitchen-sink/blob/main/javascript/localization/index.js">
    Clone the Localization example in Javascript
  </Card>
</CardGroup>