Overview

The Kinetic Platform provides the ability to translate forms and portals displayed to end users into multiple languages.

Contexts

A context is basically the "location" where you want to look up the translation.

The "Shared" context is just that -- translations that can be shared across any form, datastore form, or "other" area (i.e., custom). Under normal circumstances all bundle / Kapp translations are entered in the shared context. If you need to apply unique translations for a form (or items that just shouldn't / wouldn't ever need to be shared) these go in the form's context. And if you need to apply unique translations for a datastore form, these go in the datastore's form context. Custom Contexts are groups of translations that might be for a special purpose outside of the standard bundle, form, or datastore form framework -- maybe something specific for a Kapp.

Each context type is given a specific naming convention in the structure of:
Forms: kapps.[kapp name].forms.[formslug]
Datastore Forms: datastore.forms.[formslug]
Custom: cutom.[nameprovided]

All Forms and Datastore forms appear in their respective areas together with their auto-populated context values.

Translations Cascade

At run-time, normal translation processing is to start with the shared context data and overlay with form / datastore / custom context data to determine the full set of translations for the page / form being rendered. In the translation UI, you see this happen visually -- enter in data in the shared context first, then proceed to a form which happens to have the same key as the shared context. The data will auto-populate from the same-language shared context value (in italicized) to indicate it has a shared value (and you can't delete the value). If necessary, the shared context value can be overridden with a more precise / accurate translations for the specific context.

Language Fallback

Kinetic tranlsations support language families and variants.
Family: English
Variant: British, American, Canadian, etc.

When translating, the system uses the language value on the user's CE record (or the browser setting) to determine language requested. The system tries to match the specificity of the user's requested locale to the translation values for the requested context, falling back from variant, to family, to original key value; there is no cross-language activity (i.e., display in a default language if the requested language family is not found).

Translations in Bundle / Non-form pages:

Bundle work

All displayed content written in the bundle should be wrapped with tags:
I am a walk-in

At run time, CE will replace anything in these tags with translated values.

All Services, Queue, and Tech Bar content has been wrapped. Ideally, any / all newly written functionality should be wrapped -- regardless of whether or not translations are required at this time for. In my mind, this includes code written specifically for customers. Translations can be used in "unique ways" to fix / adjust terminology. Example: For Tech Bar, one of our clients calls them "TCXs". We translated the term "Tech Bar" to "TCX" to give it a more personal feel with no need to change the bundle.

Translation Actions

All bundle / non-form pages are translated in the Shared Context. The Key is the value within the tags, the Value is what the translation should be.

Translation in forms

Fields

By default, the key value for all forms will be the field Name. These will automatically populate once any translation has been entered for a form. Example: For any form, choose a language, key of "a" and enter a value of "1" and click 'Create Translation'. All the field names along with any shared translations will automatically appear. Once any valid translation has been entered, the placeholder can be removed.

HTML elements:

HTML that include text should also be translated by wrapping the translatable content with ${translate()}:
${translate('Scheduling Appointment For User')}

Content wrapped like this will automatically be displayed as translatable keys in the form context (just like field names).
These translation keys can also be placed in the shared or form context.

Custom text / Javascript

Often custom javascript is used to generate messages / content on the pages. Displayed content should be wrapped with K.translate().
K.translate('The selected data could not be found. Please consult an administrator.')

Content wrapped like this will NOT automatically be displayed as translatable keys. The data needs to be manually entered as a key value.
Additionally, if this key is entered in the Shared context, it WILL translate, but will not be automatically displayed in the form. Note: Just like any other translation, this can be placed in the shared or form context.

Translations need to be published

Once a translation has been defined, it isn't visible within the system until it has been published. The Translation UI will indicate when there are translations to be published. Publishing only takes a second to do: Click the notification text; at the next screen review, and click 'Publish'.

Default Locale

This is the locale that is shown when a user’s preferred locale is not available. Translation entry values are not considered missing (since it is assumed that the key can be used when the value is not set). Other translation locales will default to the default locale if they are missing entries because there may be keys that are not intended to be human labels.

Translations keys are case and space sensitive

Translation keys must match exactly. Custom translations keys entered with extra spaces or incorrect capitalization will not match.

Field name changes do not automatically update translations

When fields are changed on a form, translations must be considered, there is no automatic link between a field and translation.

Special considerations when changing the slug name of a form and cloning forms

If a form's slug changes, the translations do not automatically migrate to the new context; they remain with the original context. The translation UI only will display contexts for existing forms, meaning the old translations aren't immediately visible / accessible. Therefore, we should indicate that users should either recreate the translations manually or:

1. Export any translations for a form before changing it's slug.
2. Proceed with adjusting the forms' slug
3. Edit the exported CSV translations with the context name
4. Import the new translations

Similarly, if a form is cloned, the translations do not automatically get cloned along with it. Users should either manually create new translations data for the cloned form, or:

1. Clone the form as normal
2. Export translations from the original form
3. Update to reflect the context based on the new form
4. Reimport the translations
5. Update imported entries based on form changes (there will likely be new questions and perhaps questions that were deleted but still have translations listed).