Language / Translations

In the HybridForms App, there are 3 areas for language control:

1. App Settings: The language of the App
2. Form Definition: The default language and culture settings for the Form Template
3. Form Translation: The translations for the Form

App Settings

The chosen App language is applied to all general parts of the App that are not Form Definition contents. The user can choose the App language in the settings page.

Info

Currently fully supported languages are English and German.

Settings page - Language

Form Definition

The language of the Form Definition can also be specified. This is done server side on the Form Definition settings page in the template area.

Admin UI Template settings - Language/culture

Info

The Form Template language definition affects the default behaviour of the Form Controls "DatePicker", "TimePicker" and "NumericField" unless any explicitly defined options or form translations are provided.

Form Translation

Form Translations allow you to provide forms in multiple languages for users

In the form template, use placeholders for any content that needs translation. Define these placeholders by enclosing the placeholder ID in curly brackets and prefixing it with an at-sign (@).f

<var data-hf-name="Title">{{@Title}}</var>
<li data-hf-title="{{@StructureTitles.Controls}}">...</li>

Translations are managed via a JSON file (which the app uses internally) or, for easier administration, an Excel file. Translation files should be included within your form template files. If an Excel file (translation.xlsx) is provided, the JSON file is automatically generated when uploaded to the server or used in FormDev. Therefore, if you are using an Excel file, make all changes there instead of modifying the JSON file directly.

The keys used in your form template must be defined in the corresponding translation file (either JSON or Excel). Additionally, the translation file specifies the supported languages and provides necessary context and metadata.

caution

The translation file (JSON or Excel) must be named translation.json or translation.xlsx. Otherwise, the server and app will not recognize these files as valid translation files.

JSON Translation File

In addition to the section where you define languages and their corresponding translations, the JSON file must include the following key-value pairs:

• langSchema
• langLabels
• langCulture
• langDefault
• langPDF
• schemaVersion
• keys (containing all defined text element placeholders)
• metakeys (optional)

These elements ensure proper localization and functionality within the application.

{
    "keys": {
        "de-DE": {
            "Title": "Demo Formular",
            "Page1.Label": "Seite 01",
            "Page1.FirstNameCtrl": "Vorname",
            "staticHTML": "<div class=\"foo\">This is static html</div>"
        },
        "en-US": {
            "Title": "Demo form",
            "Page1.Label": "Page 01",
            "Page1.FirstNameCtrl": "First name",
            "staticHTML": "<div class=\"foo\">This is static html</div>"
        },
        "es-ES": {
            "Title": "formulario de demostración",
            "Page1.Label": "página 01",
            "Page1.FirstNameCtrl": "Nombre de pila",
            "staticHTML": "<div class=\"foo\">Esto es html estático</div>"
        }
    },
    "metadata": {
        "Title": {
            "remark": null,
            "reference": "Form title"
        },
        "Page1.Label": {
            "remark": "A comment to this translation key",
            "reference": "Page 1 Title"
        },
        "Page1.FirstNameCtrl": {
            "remark": "A comment to this translation key",
            "reference": "Page 1 | Tab 1 | block-id"
        },
        "staticHTML": {
            "remark": "static html that is included on page 1",
            "reference": "Page 1 | Tab 1 | block-id"
        }
    },
    "langSchema": ["de", "en", "es"],
    "langCulture": ["de-DE", "en-US", "es-ES"],
    "langLabels": ["Deutsch", "Englisch", "Español"],
    "langDefault": "es",
    "langPDF": "user-defined",
    "schemaVersion": "2.0.0"
}

Key	Value	Description
langSchema*	["de","en","es"]	Provide an array of the language abbreviations for any language your form should be translated into.
langLabel*	["Deutsch", "English", "Español"]	Provide an array of the language names for any language your form should be translated into.
langDefault*	"en"	Provide the default language of a new created Form Item.
langCulture*	"["de-DE", "en-US" ]"	Provide an array of the HTML language codes.
langPDF	"user-defined"	Define the language the Form PDF should be created in. You can either set this property to one of the defined lang schemes or to user-defined. If the latter option is chosen the PDF is created in the language the user has used to fill out the Form.
keys	{ "de-DE": { "Title": "QA Testformular 1", "ShortTitle": "QA Short Title 1", ... }, "en-US":: { "Title": "QA Testformular 1", "ShortTitle": "QA Short Title 1", ... }}	Provide the text variants for all of your placeholders.
metakeys	{ "Title": {"remark": "the form title", "reference": "form title" }, {...}}	Provide context information to your translation keys. This property is optional.
schemaVersion*	"schemaVersion": "2.0.0"	Define the schema version of the translation.json file. Please use "2.0.0" if you use the schema that is documented here.

Info

Please keep in mind the sequence inside the values: the defined langSchema ["de, en, fr" ] must be matched by the placeholder values ["de-DE", "en-US", "fr-Fr" ] for a correct translation!

warning

If you define HTML or double-quotes in your translation key and this translation key is used in data-hf-options of a control, replace the quotes with the HTML entity """. Another option would be to use the HTML-pipe (see below).

Excel Translation File

If you choose to use an Excel file for translations, the recommended approach is to download the following Excel translation template.

Download Excel Translation Template

Translation Pipes

Use pipes to transform translation string outputs. Pipes are simple functions to use in translation placeholders. Add the pipe symbol ("|") with a pipe function keyword after your translation key.

Usage:

<var data-hf-name="Title">{{@Title | toUppercase}}</var>
{{@staticHTML | escape}}
<li data-hf-title="{{@StructureTitles.Controls}}">...</li>

Pipe Function	Example	Description
escape	{{@staticHTML | escape}}	If you include translation content with HTML or quotes within data-hf-options add an "escape" pipe. Note: don't use HTML pipes outside of data-hf-options.
toUppercase	{{@staticHTML | toUppercase}}	Transform the output of the translation to an uppercase string.
toLowercase	{{@staticHTML | toLowercase}}	Transform the output of the translation to a lowercase string.