> ## Documentation Index
> Fetch the complete documentation index at: https://sonamu.cartanova.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# i18n Overview

> Architecture of Sonamu's internationalization system

Sonamu has a built-in type-safe internationalization (i18n) system. Through the **SD (Sonamu Dictionary)** function, it detects key typos at compile time and automatically extracts Entity labels to simplify translation work.

## Key Features

* **Type Safety**: Compile-time errors when using non-existent keys
* **Automatic Entity Label Extraction**: title, prop.desc, and enum labels are automatically included in the dictionary
* **Function Value Support**: Dynamic message generation (`(count) => \`\${count} items\`\`)
* **Korean Helpers**: Particle handling (은/는, 이/가), pluralization, etc.
* **Excel import/export**: Manage translation files through Sonamu UI
* **Locale-specific Column Support**: Multilingual DB columns like `name_ko`, `name_en`

## Architecture

```mermaid theme={null}
flowchart TB
    subgraph Config["sonamu.config.ts"]
        I18N["i18n: {\ndefaultLocale: 'ko',\nsupportedLocales: ['ko', 'en']\n}"]
    end

    subgraph Files["api/src/i18n/"]
        KO["ko.ts\nKorean dictionary"]
        EN["en.ts\nEnglish dictionary"]
        GEN["sd.generated.ts\nEntity labels + SD function"]
    end

    subgraph Usage["Usage examples"]
        CODE["SD('error.notFound')\nSD('entity.User.email')"]
    end

    Config --> Files
    Files --> Usage

    style Config fill:#f1f5f9,stroke:#64748b
    style GEN fill:#10b981,color:#fff
```

## Auto-generated Files

`sd.generated.ts` includes the following:

| Item            | Description                    | Example Key           |
| --------------- | ------------------------------ | --------------------- |
| Entity Title    | Entity's title property        | `entity.User`         |
| Prop Label      | prop's desc property           | `entity.User.email`   |
| Enum Label      | enumLabels definition          | `enum.UserRole.admin` |
| SD Function     | Type-safe translation function | -                     |
| localizedColumn | Multilingual DB column support | -                     |

## Workflow

```mermaid theme={null}
flowchart LR
    A[Define Entity] --> B[pnpm sync]
    B --> C[Generate sd.generated.ts]
    C --> D[Write ko.ts/en.ts]
    D --> E[Use SD function]

    style A fill:#4f46e5,color:#fff
    style C fill:#10b981,color:#fff
```

1. Define title, prop.desc, and enumLabels in Entity
2. Run `pnpm sync` to auto-generate `sd.generated.ts`
3. Write project dictionaries in `ko.ts`, `en.ts`
4. Use `SD("key")` function to get text matching the current locale

<CardGroup cols={2}>
  <Card title="Setup" icon="gear" href="/en/advanced-features/i18n/setup">
    Initial i18n configuration
  </Card>

  <Card title="Using the SD Function" icon="code" href="/en/advanced-features/i18n/dictionary">
    Writing and using dictionaries
  </Card>
</CardGroup>