Translating data components

In back-end data processing, locales play a crucial role in ensuring that data is interpreted and manipulated in a manner consistent with specific cultural and regional conventions. By configuring and utilizing locales, developers can prevent data inconsistencies, enhance the accuracy of data operations, and ensure the integrity of back-end processes, ultimately contributing to the robustness and reliability of software applications.

The C3 AI Type System provides a robust framework for defining and manipulating data structures and their behaviors. One of the advanced features of this system is the translate by functionality, encapsulated within the FieldTypeBase Type.

Copy link to this section

Overview of FieldTypeBase

The FieldTypeBase Type serves as an abstract type within the C3 AI Type System, defining the foundational structure for field types. Fields in this context refer to data fields (member variables) and methods (functions callable on the Type). The FieldTypeBase Type encompasses various properties and behaviors, including the translate by functionality.

The translate by functionality, represented by the translatedBy property in FieldTypeBase, is designed to facilitate the localization and internationalization of data within the C3 Agentic AI Platform. It allows for the dynamic translation of field values based on predefined translation mappings, ensuring that data can be presented in a locale-specific manner.

Copy link to this section

Technical implementation

The translatedBy property in the FieldTypeBase Type is a string, representing the identifier of the translation mapping to be applied to the field. This property is annotated with @dsl(syntax="translate by", ident=true), indicating that it is a domain-specific language (DSL) construct, and its value should be treated as an identifier.

When a field is marked with translate by, the C3 AI runtime environment automatically applies the specified translation mapping to the field's value whenever the field is accessed. This ensures that the value is localized according to the user's locale or the application's configuration.

Copy link to this section

Translation identifiers

Translations are uniquely identified by combining the locale and key attributes, separated by a period (locale.key). The key serves as an identifier for a translatable message.

Copy link to this section

Translation conventions for data fields

For data fields marked with translate by, the translation key must follow the convention:

data.<Type name>.<object id>.<field name>

This ensures consistency and manageability across various data components.

Copy link to this section

Usage and implications

To utilize the translate by functionality, developers define a field within a type and annotate the field with the translate by syntax, specifying the identifier of the translation mapping.

Copy link to this section

Translate by example

This is the package for the TranslateBy application.

Name you package file: translateByApplication.c3pkg.json.

{
  "name": "translateByApplication",
  "description": "A package to test translateBy functionality"
}

To learn about the organization and structure of a package, see Package Management Overview.

In the Employee type notice the greeting field is marked with translate by.

entity type Employee {
  name: string
  greeting: string translate by id
}

To provide the English translation for the name field, you would add an entry to the metadata folder in your package:

<your package name>/metadata/Translation/en.csv

id,locale,key,value
en.data.Employee.engineer.greeting, en, data.Employee.engineer.greeting, Engineer says hi!
en.data.Employee.manager.greeting, en, data.Employee.manager.greeting, Manager says hi!

With the locale set to en-US, fetching the Employee.engineer object would return Engineer says hi! for the name field.

Changing the locale to es without providing a Spanish translation would result in a blank name field.

To provide the Spanish translation for the name field, you would add an entry to the metadata folder in your package:

<your package name>/metadata/Translation/es.csv

id,locale,key,value
es.data.Employee.engineer.greeting, es, data.Employee.engineer.greeting, Ingeniero dice hola!
es.data.Employee.manager.greeting, es, data.Employee.manager.greeting, Gerente dice hola!

To test the translate by functionality you can run the commands below in the C3 AI Console.

Create an instance of the Employee type.

Employee.make({ "id": "engineer"}).create();

Fetch the Employee type and notice the output for greeting is in English.

Employee.fetch({ filter: "id == 'engineer'", include: "id, name, greeting" }).objs;

Get the current Context and set this Context's language to Spanish. If called on the default Context then the new language can be used for all subsequent type-system actions. The default language for a connection is en-US.

C3.context().setLanguage('es');

Fetch the Employee type and notice the output for greeting is in Spanish.

Employee.fetch({ filter: "id == 'engineer'", include: "id, name, greeting" }).objs;

Create another instance of the Employee type.

Employee.make({ "id": "manager"}).create();
Employee.fetch({ filter: "id == 'manager'", include: "id, name, greeting" }).objs;

Notice the value for greeting is in Spanish. Set this Context's language to English.

C3.context().setLanguage('en');

Fetch an instance of the Employee object and notice it is now in English.

Employee.fetch({ filter: "id == 'manager'", include: "id, name, greeting" }).objs;

This topic presents a comprehensive guide on leveraging the translate by functionality within the C3 AI Type System to facilitate dynamic data translation and localization. By utilizing the FieldTypeBase Type and its translatedBy property, developers can create software applications that can adapt to different locales, ensuring data consistency.