# CSV & Excel import

> Import terminology from CSV or Excel files with column mapping and conflict resolution.

**Category:** Import & Export | **Tab:** features

---

Import existing terminology into Black Ice from CSV or Excel files. The importer handles column mapping, duplicate detection, and conflict resolution.

## Supported formats

- **CSV** (.csv) — Comma-separated values
- **Excel** (.xlsx) — Microsoft Excel workbooks (first sheet is used)

## Import process

1. Navigate to **Import** in the sidebar
2. Upload your file
3. **Map columns** — Match your file's columns to Black Ice fields (concept name, class, locale, preferred term, etc.)
4. **Preview** — Review the parsed data before importing
5. **Resolve conflicts** — create missing classes and choose Keep or Replace for every changed translation
6. Click **Import**

## Column mapping

The importer auto-detects common column names but lets you manually map any column:

| Black Ice field | Common CSV headers |
|----------------|-------------------|
| Concept name | name, concept, term |
| Class | class, category, type |
| Description | description, notes, definition |
| Locale | locale, language, lang |
| Preferred term | translation, target, preferred_term |
| Allowed variants | variants, alternatives, allowed |
| Forbidden variants | forbidden, blocked, do_not_use |

## When a translation in the file differs from Black Ice

If a concept already exists and the file has a **different** term for a market that already has one, the importer shows both side by side — **Black Ice:** the current term, **File:** the new one — and asks you to choose:

- **Keep Black Ice term** — nothing changes for that market.
- **Replace with file term** — the file's term replaces it and goes back to **Pending** for review.

Nothing is preselected and you can't continue until every difference has a choice. Use the bulk buttons to keep or update all, then override individual rows.

The review step lists exactly what will happen (e.g. *1 added · 1 replaced · 1 kept*). If you kept everything, it says **No changes to save**. After saving, a results screen confirms what was actually replaced, kept or failed.

Other rules:

- Blank cells stay **Missing** — the source term is never copied into empty target columns.
- New markets on existing concepts are added as Pending; source terms are never changed by an import.

## Tips

- **Include a header row** — The first row should contain column names
- **One row per term** — Each row represents one term in one locale for one concept
- **Use consistent locale codes** — Match the codes defined in your workspace (e.g., `en-us`, `es-es`)