x-type-schema i18n Support

Internationalization features for type schema field translations

i18ninternationalizationtype-schematranslations

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:

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

For Descriptions:

  1. x-type-schema.i18nDescriptionKey (with replacers if provided)
  2. x-type-schema.i18nDescription (inline translation)
  3. schema.description (regular description)
  4. undefined (no fallback generation for descriptions)
Markdown llm.txt