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

# Excel Import/Export

> Bulk management of translation files through Sonamu UI

Sonamu UI provides functionality to export and import i18n dictionaries as Excel files. Translators or planners can work in spreadsheets and apply changes all at once.

## Excel Export

### Exporting from Sonamu UI

1. Access Sonamu UI (`http://localhost:34900/sonamu-ui`)
2. Click **i18n** in the left menu
3. Click the **Export** button in the top right
4. Download the Excel file

### Excel File Structure

```mermaid theme={null}
block-beta
    columns 4

    block:header:4
        A1["Sonamu Dictionary"]
    end

    space:4

    H1["key"] H2["source"] H3["ko"] H4["en"]

    D1["entity.User"] D2["entity"] D3["사용자"] D4["User"]
    D5["entity.User.email"] D6["entity"] D7["이메일"] D8["Email"]
    D9["common.save"] D10["project"] D11["저장"] D12["Save"]
    D13["error.notFound"] D14["project"] D15["찾을 수 없습니다"] D16["Not found"]

    style A1 fill:#e2e8f0,stroke:#64748b
    style H1 fill:#f1f5f9,stroke:#64748b
    style H2 fill:#f1f5f9,stroke:#64748b
    style H3 fill:#f1f5f9,stroke:#64748b
    style H4 fill:#f1f5f9,stroke:#64748b
```

| Column          | Description                                               |
| --------------- | --------------------------------------------------------- |
| `key`           | Dictionary key                                            |
| `source`        | `entity` (auto-extracted) or `project` (manually written) |
| `ko`, `en`, ... | Translation values for each locale                        |

## Excel Import

### Importing After Translation Work

1. Perform translation work in the exported Excel file
2. Click the **Import** button on the i18n page in Sonamu UI
3. Select the Excel file
4. Review and apply the changes

### Import Behavior

| source    | defaultLocale (ko)    | Other locales (en) |
| --------- | --------------------- | ------------------ |
| `entity`  | Updates `entity.json` | Saved to `en.ts`   |
| `project` | Saved to `ko.ts`      | Saved to `en.ts`   |

<Note>
  The defaultLocale values for `entity` source directly modify the Entity's title, prop.desc, and
  enumLabels.
</Note>

## Translation Workflow

```mermaid theme={null}
flowchart TD
    A[Developer: Define Entity] --> B[pnpm sync]
    B --> C[Generate sd.generated.ts]
    C --> D[Sonamu UI: Export]
    D --> E[Translator: Excel work]
    E --> F[Sonamu UI: Import]
    F --> G[Update ko.ts, en.ts]
    G --> H[Update entity.json]

    style D fill:#10b981,color:#fff
    style F fill:#10b981,color:#fff
```

### Recommended Workflow

1. **Development phase**: Only write defaultLocale (ko) labels when defining Entities
2. **Translation phase**: Excel export -> Deliver to translation team -> Import after translation is complete
3. **Maintenance**: Repeat the same process when adding new keys

## Handling Function Values

Function values are preserved as-is in Excel:

| key                   | ko                                         |
| --------------------- | ------------------------------------------ |
| `common.results`      | `(count: number) => \`\${count}개 결과\`\`    |
| `validation.required` | `(field: string) => \`\${field}은(는) 필수\`\` |

During import, arrow function patterns (`(...) => ...`) are automatically detected and saved as functions.

## Important Notes

* **Key changes**: Changing an existing key adds it as a new key; the original key is retained
* **Key deletion**: Deleting a row in Excel does not remove it from the existing dictionary
* **Source change not allowed**: Changes from `entity` to `project` are ignored
* **Empty values**: Empty cells are ignored (the key is not removed from that locale)

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

  <Card title="Entity Labels" icon="tag" href="/en/advanced-features/i18n/entity-labels">
    Auto-extracted labels
  </Card>
</CardGroup>