# 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.

```typescript
{
  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.

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

### Description Translation Properties

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

```typescript
{
  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.

```typescript
{
  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.

```typescript
{
  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:

```typescript
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
```typescript
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
```typescript
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
```typescript
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
```svelte
<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
```typescript
// 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)