Translations

This set of endpoints will allow you to create translations for your forms. They are currently in beta and are subject to change.

Before getting started, you will need to:

• Ensure your plan includes Multi-language feature (check plans here)
• Have a published form with at least one translation language. This guide explains how to do it through the UI.

Once you've added languages to your form settings, they will be automatically translated until this feature is fully released. Still, you can use the API to customize the contents for each language.

The following languages are supported:

Language code: Language name

• ar: Arabic
• ca: Catalan
• ch: Chinese (simplified)
• cs: Czech
• da: Danish
• de: German
• el: Greek
• en: English
• es: Spanish
• et: Estonian
• fi: Finnish
• fr: French
• he: Hebrew
• hr: Croatian
• hu: Hungarian
• it: Italian
• ja: Japanese
• ko: Korean
• lt: Lithuanian
• nl: Dutch
• no: Norwegian
• pl: Polish
• pt: Portuguese
• ru: Russian
• sv: Swedish
• tr: Turkish
• uk: Ukrainian
• zh: Chinese (traditional)

Use the language code to specify the language of any translation.

After adding the desired languages in your form settings, you have two different ways to create a translation:

1. Translate the form manually
2. Translate the form automatically using AI

NOTE: If you try to operate over a translation in a language that does not exist in the form settings, the endpoints will return errors.

You can upload custom translations using the Update form translation endpoint. This works as an upsert, so it will create new translations for a language, or update them with the new payload if they exist already.

To use it, you can either: get the main translation payload (read below), or request automatic translations first. Then, introduce your changes and PUT them back to this endpoint.

Getting the main translation payload

You can get the main translation payload by using the Retrieve form translation endpoint. This will respond with a demo schema that you can later modify, and PUT back to the Update form translation endpoint.

To make things easier, we're also providing an Auto-translate form endpoint that can help you get started. This endpoint will automatically translate your form to the language you're requesting, and will be saved as a custom translation.

If the result is good enough, you will already be able to use it in your typeforms. Now if you need to customize it, you could PUT that full payload with your changes to the Update form translation endpoint.

In case you missed this endpoint's response, given the translation will be stored already, you can always retrieve it using the Retrieve form translation endpoint.

Translations could have three different status:

• not_translated: when a language exists in form.settings.translation_languages but there’s no content created yet
• translated: when a translation is created and is in sync with the published form content
• update_required: when a translation that was previously translated gets out of sync with the published form content (i.e. if you add a new question or modify a field title after creating a translation)

In order to know the current status of all your translations, you can use the Retrieve translation statuses endpoint.

NOTE: While we migrate customers that are using the legacy version of this feature, translations with not_translated status will be also available for respondents in the published form. Respondents will get live translations (auto-translating using AI) as legacy translations used to work. Once the migrations are done, only translations with translated status will be available for respondents. You can ensure this won't ever happen (ie. only serving your custom translations) by either uploading them, using auto-translate, or removing empty languages entirely from your form settings.

To remove an existing translation, you can use the Delete form translation endpoint.

By calling this, the translation will be removed permanently from the database and it won’t be available anymore.

NOTE: This will only delete the translation content and not the language row in the form settings. While we're supporting both custom and legacy translations feature, this action will keep serving that language with automatic translations until this beta is fully released. If you don't want that to happen, you need to manually remove the language from your form settings.