Bulk-import terms
Upload CSV, TSV, XLSX, or XLS files, map columns to marks, contexts, and languages, and optionally auto-translate the gaps.
Bulk import onboards existing translations — a spreadsheet export from your previous tool, a translator's deliverable, a one-off content drop — in a two-step flow: upload, then map columns and run.
If your translations live as JSON files in a Git repository, don't use bulk import — that's exactly what the CLI sync is for.
Supported formats
| Format | Notes |
|---|---|
| CSV | Comma-separated. The first row is read as column names for the mapping step. |
| TSV | Tab-separated, same handling as CSV. |
| XLSX | Excel 2007+. |
| XLS | Excel 97–2003. |
Step-by-step
Upload
Open the namespace and click Bulk import. Pick your file and continue. LangSync runs a precheck: it validates the format, counts the rows, and reads the column names.
Map columns
The Bulk import settings dialog lists every column found in your file. For each one, pick what it is:
- Ignore — skip the column entirely.
- Mark — the column holding the translation keys.
- Context — the column holding per-term notes.
- Translation — the column holds values for one language; a second dropdown appears to pick which language.
Every language you map must already be attached to the namespace — the import is rejected otherwise, so attach missing languages first.
Choose import behaviour
Two checkboxes control what happens to data that already exists:
- Overwrite existing terms — "Replace existing translations with data from the import." When off, marks that already exist in the namespace are left untouched; when on, the file's values win.
- Translate automatically — "Generate missing translations automatically using AI." After the rows are inserted, a batch auto-translate fills every language your file didn't provide.
Start the import
Click Start import. The import runs in the background — you can leave the page. You'll get an email ("Your bulk import is complete") reporting how many terms were imported.
What the import does, exactly
- Creates a new term for every mark that doesn't exist yet.
- Updates existing marks only if Overwrite existing terms is on.
- Never deletes anything: terms in the namespace that your file doesn't
mention are left exactly as they were. (If you want
delete-what's-gone semantics, that's the CLI's
sync --prune.)
Import lifecycle and expiry
An import moves through the states prechecked → processing →
completed (or failed).
- After the precheck, you have 24 hours to finish the column mapping — unfinished imports expire and you'll need to re-upload.
- Uploaded files are stored only for the duration of the import and are deleted from storage shortly after it completes or fails.
- The finished import is recorded in the
audit log as
term_import.finished.
What bulk import doesn't cover
- Glossary entries. The glossary is managed separately.
- Anything but marks, contexts, and translations. IDs and timestamps are server-generated.
Migrating from POEditor
Coming from POEditor? LangSync's API includes a dedicated POEditor
migrator: give it your POEditor API key, pick which of your POEditor
projects to migrate, and each becomes a LangSync namespace with its
terms and translations imported. Migration fails with a conflict if a
namespace with the project's name already exists. The run is recorded
in the audit log as migrator.imported. See the
API reference for the endpoints.