Translating your Space

Translate and customize your Space with text overrides

The DevXP engineering team hosts office hours every Thursday at 11 a.m. Pacific Time where we answer your questions live and help you get up and running with Flatfile. Join us!

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
English	en
French	fr
German	de
Indonesian	id
Italian	it
Japanese	jp
Korean	kr
Portuguese	pt
Portuguese - Brazilian	pt-BR
Spanish	es
Turkish	tr
Vietnamese	vi
Chinese	zh

Need more languages? Reach out to us at [e-mail].

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.

listener.ts

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. 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.

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.

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.

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.

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.

For our translations repository we would set our translationsPath to: https://raw.githubusercontent.com/FlatFilers/Platform-Translations/main/locales/en/translation.json

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.

listener.ts

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",
  });
});

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.

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:

.../locales/en/translation.json

{
  "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:

sheet.js

sheets : [
  {
    name: "Sheet Name",
    actions: [
      {
        operation: 'Submit',
        mode: 'foreground',
        label: 'mySubmitAction.label',
        type: 'string',
        description: 'mySubmitAction.description',
        primary: true,
        tooltip: 'mySubmitAction.tooltip'
      },
      {...}
    ]
  }
]

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.

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!

.../locales/en/translation.json

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

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.

Always validate your translation.json file to ensure it follows the correct JSON format to prevent errors during runtime.

Example Project

Find the Localization example in the Flatfile GitHub repository.

typescript

Clone the Localization example in Typescript

javascript

Clone the Localization example in Javascript