Translations

Marble field translations can be utilized for widget translation needs. This eliminates the requirement for adding an extra layer of translatable code generation.

A marble client file should be created to generate the translations required for the content of each widget (Separate client file for each widget). The name of the client file should correspond to the ID of the widget. Please refer to the Naming conventions section for more details on how to name the client file.

The client file should contain only one page and one list element, named TranslationsPage and TranslationsList which includes all the translatable text represented by fields. A corresponding projection file can be used to create the necessary data structure/dataset required for the list element defed in the client. If there is a projection available already (used for managing data related to the widget), then it is recommended to use the same projection file to create the data structure for the translations list.

Example:

Client: RecentDocumentsWidget.client

page TranslationsPage using WidgetTranslationSet {
   list TranslationsList;
}
list TranslationsList for WidgetTranslation {
   field WidgetTitle {
      label = "Fw Widget Title";
   }
   field WidgetDescription {
      label = "Fw Widget Description";
   },
   field HoursRemaining {
      label = "Job Hours Remaining";
   },
   field WageHoursRemaining {
      label = "Wage Hours Remaining";
   }
}

Projection: RecentDocumentsWidgetHandling.projection

entityset WidgetTranslationSet for WidgetTranslation;
query WidgetTranslation {
   from = "dual";
   attribute WidgetTitle Text;
   attribute WidgetDescription Text;
   attribute HoursRemaining Text;
   attribute WageHoursRemaining Text;
}

Each widget has a metadata file and it includes metadata that is mandatory for the widget functionality. The developer should include translations related metadata in the same file as follows.

 export const RecentDocumentsWidgetMetadata: Metadata = {
    id: "RecentDocumentsWidget",
    title: "WidgetTitle", //translation key
    description: "WidgetDescription",  //translation key
    size: WidgetSize.FullWidth,
    keywords: ["test", "widget","framework"],
    projection: "RecentDocumentsWidgetHandling",
    translations: {
        type: WidgetTranslationType.ClientMetadata,
        client: "RecentDocumentsWidget",
        list: "TranslationsList"
    }
}

The client framework will load the translations through client metadata in the runtime and it will be made accessible to the widget through the Cloud Home Widget base directive.

Translations can be accessed by accessing to the translate$ function exposed through the base class, or through the translate pipe provided through TranslateModule in the base library.

In the client framework side, it will load the client metadata for the widgets already added to the start page and will be stored in the ngrx store.

Default Translations for widget

A .JSON file is used within the widget code structure to define default values for translatable labels. In the event that the Marble client fails to load the translation metadata, the default label values will automatically be retrieved from this .JSON file.

File path - /translations/default-translations.json

Example : default-translations.json

{
    "WidgetTitle": "Daily Project Time Reporting",
    "WidgetDescription": "Complete your daily time reporting using the project time reporting shortcuts and frequently reported project activities.",
    "HoursRemaining": "Job Hours Remaining",
    "WageHoursRemaining": "Wage Hours Remaining"
}

Using translatable text in widgets

Functionality for accessing the translations from your widget is included in the base service widgetFrameworkUtilsService.

Using translations in HTML template

translate pipe can be used to include the translatable labels into the HTML template of your Angular component.

<span>{{'HoursRemaining' | translate}}</span>

Using translations in TS code

call widgetFrameworkUtilsService.translate$ with the relevant translation text name to get the translated value (as a string observable).

translatedWageHoursLabel$: Observable<string> = this.widgetFrameworkUtilsService.translate$('WageHoursRemaining').pipe(take(1));