Title: x-type-schema i18n Support

Description: Internationalization features for type schema field translations

Tags: i18n, internationalization, type-schema, translations

---

x-type-schema i18n Support

This document describes the new internationalization (i18n) features added to the x-type-schema system.

New Properties

The XTypeSchema interface now supports five optional properties for internationalization:

Title Translation Properties

i18n?: InlineTranslation
Provides inline translations for the schema field title.

{
  type: "string",
  "x-type-schema": {
    i18n: {
      de: "Deutscher Titel",
      en: "English Title",
      fr: "Titre français"
    }
  }
}

i18nKey?: string
Specifies a translation key for the title for use with the i18n system.

{
  type: "string", 
  "x-type-schema": {
    i18nKey: "form.field.name"
  }
}

Description Translation Properties

i18nDescription?: InlineTranslation
Provides inline translations for the schema field description.

{
  type: "string",
  description: "Regular description", // fallback
  "x-type-schema": {
    i18nDescription: {
      de: "Deutsche Beschreibung",
      en: "English Description",
      fr: "Description française"
    }
  }
}

i18nDescriptionKey?: string
Specifies a translation key for the description for use with the i18n system.

{
  type: "string", 
  "x-type-schema": {
    i18nDescriptionKey: "form.field.description.help"
  }
}

Shared Properties

i18nReplacers?: Record<string, string>
Provides replacers/variables for both title and description translation keys.

{
  type: "string",
  "x-type-schema": {
    i18nKey: "form.field.validation.max",
    i18nDescriptionKey: "form.field.description.max",
    i18nReplacers: {
      max: "100",
      fieldName: "age"
    }
  }
}

Utility Functions

Shared Package (@smallstack/shared)

Schema Utilities

Title Functions:
getI18nFromSchema(schema) - Extracts inline title translations
getI18nKeyFromSchema(schema) - Extracts title translation key
getI18nReplacersFromSchema(schema) - Extracts replacers
createTranslatableFromSchema(schema) - Creates Translatable object from title key + replacers
getSchemaTranslation(schema) - Gets appropriate title translation (inline or key-based)
getTitleForSchema(schema) - Gets i18n-aware title for schema
getTitleForPath(schema, path) - Gets i18n-aware title for path

Description Functions:
getI18nDescriptionFromSchema(schema) - Extracts inline description translations
getI18nDescriptionKeyFromSchema(schema) - Extracts description translation key
createTranslatableDescriptionFromSchema(schema) - Creates Translatable object from description key + replacers
getSchemaDescriptionTranslation(schema) - Gets appropriate description translation (inline or key-based)
getDescriptionForSchema(schema) - Gets i18n-aware description for schema
getDescriptionForPath(schema, path) - Gets i18n-aware description for path

General Functions:
hasI18nInfo(schema) - Checks if schema has any i18n information (title or description)

Enhanced createInlineTranslationSchema
Now accepts both title and description i18n properties:

createInlineTranslationSchema({
  title: "Custom Title",
  description: "Custom Description",
  i18n: {
    de: "Benutzerdefinierter Titel", 
    en: "Custom Title"
  },
  i18nKey: "form.custom.title",
  i18nDescription: {
    de: "Benutzerdefinierte Beschreibung",
    en: "Custom Description"
  },
  i18nDescriptionKey: "form.custom.description",
  i18nReplacers: {
    context: "user"
  }
});

Client Package

Client Utilities
getTranslatedTitleForSchema(schema) - Gets translated title using i18n system
getTranslatedTitleForPath(schema, path) - Gets translated title for path
getTranslatedDescriptionForSchema(schema) - Gets translated description using i18n system
getTranslatedDescriptionForPath(schema, path) - Gets translated description for path

Integration with Existing Components

FormService
New methods added:
getI18nTitleForPath(path) - Returns InlineTranslation | Translatable | string
getI18nDescriptionForPath(path) - Returns InlineTranslation | Translatable | string

DetailView (TypePropertiesGridComponent)
Now automatically uses i18n-aware titles and descriptions with fallback to regular title/description properties.

Usage Examples

Basic Inline Translation
const schema: TypeSchema = {
  type: "object",
  properties: {
    email: {
      type: "string",
      title: "Email", // fallback for title
      description: "Enter your email address", // fallback for description
      "x-type-schema": {
        i18n: {
          de: "E-Mail",
          en: "Email", 
          fr: "E-mail"
        },
        i18nDescription: {
          de: "Geben Sie Ihre E-Mail-Adresse ein",
          en: "Enter your email address",
          fr: "Entrez votre adresse e-mail"
        }
      }
    }
  }
};

Translation Key with Replacers
const schema: TypeSchema = {
  type: "object", 
  properties: {
    age: {
      type: "number",
      "x-type-schema": {
        i18nKey: "form.field.age.title",
        i18nDescriptionKey: "form.field.age.description.validation",
        i18nReplacers: {
          min: "18",
          max: "100",
          fieldName: "age"
        }
      }
    }
  }
};

Mixed Approach
const schema: TypeSchema = {
  type: "object",
  properties: {
    username: {
      type: "string",
      title: "Username", // fallback
      "x-type-schema": {
        // Use inline translation for title
        i18n: {
          de: "Benutzername",
          en: "Username"
        },
        // Use translation key for description 
        i18nDescriptionKey: "form.field.username.help",
        i18nReplacers: {
          minLength: "3",
          maxLength: "20"
        }
      }
    }
  }
};

In Components
<script>
  import { getTranslatedTitleForPath, getTranslatedDescriptionForPath } from "../utils/i18n.client.utils";
  
  // These will use i18n if available, fallback to regular title/description
  const title = getTranslatedTitleForPath(schema, "fieldName");
  const description = getTranslatedDescriptionForPath(schema, "fieldName");
</script>

<div class="field">
  <label>{title}</label>
  <input type="text" />
  {#if description}
    <p class="help-text">{description}</p>
  {/if}
</div>

In FormService
// In your component using FormService
const formService = getContext("formService");

// Get i18n-aware title and description
const i18nTitle = formService.getI18nTitleForPath("fieldName");
const i18nDescription = formService.getI18nDescriptionForPath("fieldName");

// Use with translation function
const translatedTitle = t(i18nTitle);
const translatedDescription = t(i18nDescription);

Backward Compatibility

All new properties are optional. Existing schemas continue to work without modification. The system gracefully falls back to existing title/description properties when i18n properties are not provided.

The new description i18n properties follow the same pattern as the existing title i18n properties, ensuring consistency and ease of adoption.

Priority Order

When multiple title sources are available, the system uses this priority:

For Titles:
x-type-schema.i18nKey (with replacers if provided)
x-type-schema.i18n (inline translation)
schema.title (regular title)
Generated title from field name (e.g., "userName" becomes "UserName")

For Descriptions:
x-type-schema.i18nDescriptionKey (with replacers if provided)
x-type-schema.i18nDescription (inline translation)
schema.description (regular description)
undefined (no fallback generation for descriptions)