Dynamic PDF Translation

Server	Minimum Version
API Server	9.8.0
PDF Server	5.14.0

Overview

Dynamic PDF Translation allows form submission PDFs to be downloaded with field labels, placeholders, and descriptive text automatically translated into a target language. Translation is driven by a remotely hosted JSON file and activated through a URL query parameter at download time—without requiring the form to be resubmitted.

When a user downloads a PDF for a form submission, they can append a language parameter to the download URL. The PDF server fetches translations from a configured endpoint and replaces matching field text before rendering the PDF.

Changing the language parameter value changes the rendered PDF language immediately, allowing the same submission to be downloaded in multiple languages without modifying the form or submission data.

The Translations URL can be configured in two ways:

• Per form — via the PDF Settings panel in Form Settings, using the Translations URL field. This applies translation to a single form only.

• Globally across all forms in a project — via the Project Settings. When set, the global Translations URL applies to every form in the project that does not have a form-level override.

Global project-level translation is not yet available and will be released in a future update.

How It Works

When a translated PDF is requested:

1. The PDF server reads the language query parameter from the PDF download URL.

2. It fetches the translation JSON from the configured Translations URL.

3. It looks up matching text values for the selected language code.

4. Matching field labels, placeholders, and descriptions are replaced with translated values.

5. The PDF is rendered and returned in the selected language.

If no translation is found for a text string, the PDF server falls back to the original text defined in the form.

Prerequisites

Before using Dynamic PDF Translation, ensure you have:

• The appropriate API Server (9.8.0+) and PDF Server (5.14.0+) versions are deployed in your environment

• A publicly accessible URL hosting a valid translations JSON file (see format below)

Supported Translation Scope

Dynamic PDF Translation applies to text defined in the form. It does not translate submitted user-entered values — submission data remains unchanged and is rendered exactly as entered.

The following form field settings are supported for translation:

Component Setting	Description
Label	The field label displayed above or beside the input field
Description	Help text displayed below the field
Prefix / Suffix	Text displayed before or after the input value
Static Text	Rendered text output from HTML and Content components

Setup & Usage

1. Prepare the translations JSON file

Create a JSON file following the format described below, with a key for each language code and entries for every string in your form that requires translation.

The field names below are examples only. The keys in each language object must exactly match the text used in your own form — labels, static text, and descriptions will vary depending on how your form is built.

{
  "ru": {
    "User Information": "Информация о пользователе",
    "First Name": "Имя",
    "Last Name / Surname": "Фамилия",
    "Date of Birth": "Дата рождения",
    "Email": "Электронная почта",
    "Address": "Адрес"
  },
  "es": {
    "User Information": "Información del usuario",
    "First Name": "Nombre",
    "Last Name / Surname": "Apellido",
    "Date of Birth": "Fecha de nacimiento",
    "Email": "Correo electrónico",
    "Address": "Dirección"
  },
  "zh": {
    "User Information": "用户信息",
    "First Name": "名",
    "Last Name / Surname": "姓",
    "Date of Birth": "出生日期",
    "Email": "电子邮件",
    "Address": "地址"
  }
}

2. Host the Translation File

Host a JSON endpoint and paste in your translations payload. Copy the URL of the hosted endpoint to utilize in the next step.

https://myapi.example.com/v1/translations

The endpoint must be publicly accessible and return a valid Content-Type: application/json response.

3. Configure the Translations URL

Within your Form.io Project, open the form you want to enable translation for.

Click the Form Settings tab and locate the PDF Settings section.

Navigate to the PDF Settings section and paste the hosted endpoint URL in the Translation URL setting field.

Save the form settings.

4. Test PDF Translation

To test the PDF Translation manually, make a submission using your form and download the submission as a PDF.

In the browser, append the language query parameter &language=example to the PDF download URL:

https://your-server/form/<id>/submission/<id>/download&language=es

Only text strings that exist as keys in the translations JSON will be translated. Text not found in the JSON remains in its original language.

5. Switching Languages

Each PDF download request is stateless. Passing a different language parameter value generates a new PDF in the selected language. No changes to the form or submission are required.

https://your-server/submission/<id>/download&language=ru https://your-server/submission/<id>/download&language=zh

In production, switching languages would typically be handled by the application — for example, re-triggering the PDF download request with an updated language value when the user changes their language selection.

Troubleshooting

Symptom	Likely Cause	Resolution
PDF downloads in original language despite parameter	Translations URL not saved, or endpoint inaccessible	Verify the URL is saved in Form Settings and returns valid JSON when opened in a browser
Some fields are not translated	Field text does not exactly match a key in the JSON	Check for typos, trailing spaces, or capitalization differences between the form text and JSON keys
Unsupported language code used	Language code not present in the JSON file	Add the missing language block to the JSON file and re-save the endpoint
PDF server returns an error on download	JSON endpoint unavailable or returning invalid content	Confirm the endpoint is active, publicly accessible, and returning valid JSON