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

# Import Translations

> Import existing translation data into a project.

There are two ways to import translations: the **dashboard** (CSV or JSON,
any size, with a staging step) and the **public API** (JSON only, for
scripts and CI). Both apply changes as a background job, so large imports
don't block the request.

## Dashboard Import

Upload a file from the dashboard's bulk import screen:

* CSV (key / value columns)
* JSON (key-value structure, matching the export shape)

Uploaded data is staged first, then applied as a background job.

## API / CLI Import

`POST /api/v1/push` (scope `translations:write`) takes a JSON request
body whose `content` field holds the translation file as a string — the
easiest way to call it is the [CLI](/api/cli):

```bash theme={null}
lingulink push locales/de.json --lang de              # merge
lingulink push locales/de.json --lang de --dry-run     # preview only, no writes
lingulink push locales/de.json --lang de --mode replace
```

`--dry-run` parses and validates the file, returning a row count and a
create/update preview, without touching the database. Nested JSON objects
flatten into dot-separated keys (`{"auth":{"title":"Sign in"}}` imports as
`auth.title`); a `null` value imports as the literal string `"null"` and
arrays flatten into index-suffixed keys (`key.0`, `key.1`, ...) rather
than being rejected — avoid `null`/array values in files you push.

## Recommended Flow

1. Prepare clean key and locale columns
2. Validate file encoding and structure
3. Import in **merge** mode first (or `--dry-run` via the API/CLI)
4. Verify sample keys before a full rollout

## Import Modes

* **Merge**: add/update entries without removing existing records
* **Replace**: intentionally overwrite the existing dataset

## Common Failures

* Invalid locale headers
* Duplicate keys with conflicting values
* Unexpected encoding issues (non UTF-8)
* Payload over the size cap (12 MB / 50,000 rows for the API/CLI path)

## Next Steps

* Automate it with the [CLI](/api/cli)
* Pull the result back out via [Export Formats](/api/export-formats)