Skip to main content

Documentation

Import & Export

File formats, import behavior, and strict data integrity guarantees

LocaleLens supports importing and exporting translations in standard formats. We prioritize data integrity — we prefer failing safely over silent data mutation.

Imports are previewed, validated, and applied atomically — either everything succeeds or nothing changes.

Supported Formats

Keys must follow LocaleLens key format rules (1-200 characters, alphanumeric with dots/underscores/hyphens).

JSON
Nested or flat structure

Best for developers and CI workflows. Preserves structure.

Supported structures:

  • Nested: {"common": {"save": "Save"}}
  • Flat: {"common.save": "Save"}
  • i18next format with namespaces

File requirements:

  • UTF-8 encoding (BOM supported)
  • Max file size: 5 MB
  • Extension: .json
CSV
Spreadsheet-compatible

Best for translators and spreadsheets. Flat, Excel-compatible.

Expected format:

  • First row: headers (key,en,de,fr)
  • First column: translation key
  • Subsequent columns: locale values

File requirements:

  • UTF-8 encoding (BOM supported)
  • Comma or semicolon delimiter (auto-detected)
  • Max file size: 5 MB
  • Extension: .csv
What's Preserved

These are always preserved during import/export:

  • ImportExportTranslation key names (exact)
  • ImportExportTranslation values (exact)
  • ImportExportLocale codes
  • ImportExportUnicode characters
  • ImportExportNested key structure
  • ExportEmpty values (exported as empty string)
What's Ignored (Never Imported)

These are safely ignored during import (no error, no data change):

  • Non-string values — arrays, objects, numbers, booleans are skipped
  • Null values — treated as "no translation"
  • Comments — JSON doesn't support comments; they cause parse errors
  • Metadata fields — fields like _meta or $schema
What Causes Errors

These will show an error and prevent import:

  • Invalid JSON/CSV syntax — malformed files are rejected
  • File too large — exceeds 5 MB limit
  • Limit exceeded — would exceed key or locale account limits
  • Invalid key format — keys must be 1-200 characters, alphanumeric with dots/underscores/hyphens

When an error occurs, no partial data is imported. The import is atomic — it either fully succeeds or fully fails.

If creating locales would exceed your account limits, the import fails before applying any changes.

Data Integrity Guarantees
Our Commitments
  • Round-trip integrity: Exporting then re-importing the same file produces identical data. We verify this with automated tests.
  • No silent mutation: We never modify your translation values during import or export. No trimming, no case changes, no encoding conversion.
  • Atomic imports: Imports are all-or-nothing. If any part fails, no data is changed. You'll never have a half-imported state.
  • Preview before apply: Import always shows a preview of what will change before applying. No surprises.
  • Duplicate detection: If the same key appears multiple times in a file, we warn you and use the last value (last value wins — explicit, consistent behavior).
Import Options
Create Missing Keys

When enabled (default), keys in the file that don't exist in the project are created.

When disabled, only existing keys are updated.

Create Missing Locales

When enabled (default), locales in the file that don't exist in the project are created.

Subject to account locale limits.

Overwrite Existing

When enabled, existing translations are replaced with values from the file.

When disabled (default), existing translations are kept.

Import Progress

For large imports, LocaleLens shows a real-time progress bar with status updates.

Import phases:

  • Validating — checking file format and limits
  • Importing — processing translations
  • Finalizing — saving changes to database
  • Complete — import finished successfully

Import history is retained for 14 days for auditing purposes.

Export Options

Export options are designed to match common downstream workflows.

JSON Export
  • One file per locale
  • Nested structure preserved
  • Pretty-printed with 2-space indent
  • UTF-8 encoding without BOM (by design)
CSV Export
  • All locales in one file
  • Flat key structure
  • Comma delimiter
  • UTF-8 encoding with BOM (by design, Excel compatible)
Recommended Workflows
  • CI / Git-based projects: JSON import/export
  • Translator collaboration: CSV export → spreadsheet → CSV import
  • One-time migration: JSON import with "Create missing keys/locales" enabled