Every user-facing string in the importer can be overridden through the locale option. You only need to provide the keys you want to change — the rest fall back to the defaults.

Usage

Pass a partial locale object to useExpressCSV():

import { useExpressCSV, x } from "@expresscsv/react";

const schema = x.row({
  name: x.string().label("Name"),
  email: x.string().email().label("Email"),
});

const { open } = useExpressCSV({
  schema,
  getSessionToken: async () => fetchSessionToken(),
  importIdentifier: "user-import",
  locale: {
    general: {
      cancel: "Abbrechen",
      back: "Zurück",
      next: "Weiter",
      finish: "Fertig",
      required: "Pflichtfeld",
      optional: "Optional",
    },
    dropzone: {
      prompt: "CSV- oder Excel-Datei hierher ziehen",
      or: "oder",
      browse: "Datei auswählen",
    },
  },
});

The type is DeepPartial<ExpressCSVLocaleInput> — every level is optional.

Locale Structure

The locale object is organized by section:

Section	What it covers
`general`	Shared labels: cancel, back, next, finish, required, optional, matched/unmatched; advance-blocked error toasts (`nextDisabled`, `finishBlocked`, `nextBlockedFallback`)
Importer chrome	Title, loading, close confirmation, error messages
`sessionRecovery`	Recovered sessions prompt for interrupted imports
`dropzone`	File drop area: prompt, browse button, clear/processing labels
`upload`	Upload step: expected columns, template download labels
`selectSheet`	Sheet selection: title, subtitle, preview labels, column/row counts
`selectHeader`	Header row selection: title, subtitle, empty column warnings
`matchColumns`	Column matching: headers, match status, conflict warnings, previews
`matchOptions`	Option matching for select/multiselect fields
`review`	Review step: filters, sorting, transforms, export, validation messages
`validation`	Validation-specific labels
`status`	Success and error screens
`steps`	Step names shown in the progress indicator

Interpolation

Some strings contain {placeholder} tokens that are filled at runtime. Keep the placeholders intact when overriding:

locale: {
  selectHeader: {
    showingRows: "Zeige {displayed} von {total} Zeilen",
  },
  steps: {
    progress: "Schritt {currentStep} von {totalSteps}",
  },
}

Common placeholders:

Placeholder	Used in
`{count}`	Column counts, row counts, validation issue counts
`{name}`	Sheet names, column names
`{format}`	Template download format
`{displayed}`, `{total}`	Row pagination
`{currentStep}`, `{totalSteps}`	Step progress
`{value}`	Custom option values
`{description}`	Fix descriptions
`{fieldName}`	Empty-column creation actions
`{rowCount}`, `{columnName}`	Column preview labels
`{remaining}`	Option lists with hidden matches
`{number}`	Generated empty column names

Sections

nextDisabled*, nextBlockedFallback, and finishBlocked* strings are shown as error toasts when the user clicks Next or Finish while advance is blocked. Repeated attempts reuse the same toast id so only one of these messages is visible at a time.

Variable	Default value	Purpose
`cancel`	`Cancel`	Button label for canceling the current action or dialog.
`back`	`Back`	Button label for moving to the previous step.
`next`	`Next`	Button label for moving to the next step.
`finish`	`Finish`	Button label for completing the import flow.
`required`	`required`	Label shown for required fields.
`optional`	`Optional`	Label shown for optional fields.
`matched`	`Matched`	Status label for items that have been matched successfully.
`unmatched`	`Unmatched`	Status label for items that still need a match.
`custom`	`Custom`	Label used when a value is custom rather than predefined.
`nextDisabledUpload`	`Upload a file to continue`	Error toast when advance is blocked on the upload step.
`nextDisabledSelectSheet`	`Select a valid sheet to continue`	Error toast when advance is blocked until a valid worksheet is selected.
`nextDisabledSelectHeader`	`Select a header row to continue`	Error toast when advance is blocked until a header row is selected.
`nextDisabledMatchColumns`	`Map all required columns to continue`	Error toast when advance is blocked until required fields are matched.
`nextDisabledMatchOptions`	`Complete all required options to continue`	Error toast when advance is blocked until required option mappings are done.
`nextDisabledReviewValidating`	`Validation in progress, please wait…`	Error toast when advance is blocked while review validation is still running.
`nextDisabledReviewInvalid`	`Fix or delete all invalid rows to continue`	Error toast when advance is blocked while invalid review rows remain.
`nextDisabledReviewEmpty`	`Add at least one row to continue`	Error toast when advance is blocked because the review grid has no rows.
`finishBlockedMissingReviewOrSchema`	`Cannot finish: review data or schema is missing.`	Error toast when Finish is invoked without review data or schema (unexpected state).
`finishBlockedCellsInvalidOrValidating`	`Cannot finish while cells are invalid or still validating. Wait for validation to finish and fix any errors.`	Error toast when Finish runs while synced cells are still invalid or validating (authoritative check after grid sync).
`finishBlockedNoRecords`	`Add at least one record before completing the import.`	Error toast when Finish runs with no records.
`nextBlockedFallback`	`Complete the current step before continuing.`	Error toast when advance is blocked but no specific reason was resolved (edge case).

Importer

Variable	Default value	Purpose
`title`	`ExpressCSV`	Main title shown in the importer chrome.
`loading`	`Loading…`	Loading state shown while the importer initializes.
`closeConfirmTitle`	`Are you sure?`	Title of the confirm dialog shown before closing the importer.
`closeConfirmDescription`	`Closing this dialog will cause you to lose any progress made so far.`	Body text explaining the consequence of closing the importer.
`closeConfirmCancel`	`Cancel`	Button label for staying in the importer.
`closeConfirmContinue`	`Continue`	Button label for confirming the close action.
`errorTitle`	`Unable to Continue`	Title shown in a top-level importer error state.
`startOver`	`Start Over`	Button label for resetting the import flow after an error.

Recovered sessions

Variable	Default value	Purpose
`message`	`You have a recovered session available. Continue where you left off?`	Prompt shown when a Recovered Session is available.
`discard`	`Discard Recovered Session`	Button label for discarding a Recovered Session.
`resume`	`Recover Session`	Button label for loading a Recovered Session.

Dropzone

Variable	Default value	Purpose
`ariaLabel`	`Upload CSV or Excel file`	Accessible label for the file upload dropzone.
`clearAriaLabel`	`Clear file`	Accessible label for the clear-file control.
`clearTooltip`	`Clear this file and start again`	Tooltip for the control that removes the current file.
`clearConfirmTitle`	`Clear file?`	Confirmation dialog title shown before removing the current file.
`clearConfirmDescription`	`This will clear the file and any mappings or edits you've made.`	Confirmation dialog body shown before clearing the file.
`processing`	`Processing...`	Status shown while the uploaded file is being processed.
`restoredSession`	`Recovered session`	Status shown when a previous session is recovered.
`prompt`	`Drop your CSV or Excel file here`	Main dropzone instruction text.
`or`	`or`	Separator between drag-and-drop and browse actions.
`browse`	`click to browse`	Action label for opening the file picker.

Upload

Variable	Default value	Purpose
`expectedColumns`	`Expected columns`	Heading for the schema preview shown before upload.
`templatePrompt`	`Need a template?`	Prompt introducing the template download controls.
`templateCSV`	`Comma-separated values (.csv)`	Label for the CSV template format option.
`templateXLSX`	`Excel spreadsheet (.xlsx)`	Label for the Excel template format option.
`templateGenerating`	`Generating...`	Status shown while a template file is being generated.
`templateDownloadFormat`	`Download {format}`	Label for downloading a specific template format.
`templateDownload`	`Download`	Generic download label used around template actions.

Select Sheet

Variable	Default value	Purpose
`title`	`Select a Worksheet`	Title of the worksheet selection step.
`subtitle`	`Choose which worksheet to import from your file.`	Helper text explaining the worksheet selection step.
`noWorksheets`	`No worksheets available`	Message shown when the uploaded workbook has no sheets to choose from.
`preview`	`Preview`	Label for worksheet preview content.
`columnCount`	`{count} columns`	Column count label for a worksheet preview.
`rowCount`	`{count} rows`	Row count label for a worksheet preview.
`inSheet`	`in "{name}"`	Context label that includes the selected worksheet name.
`sheetSelected`	`Sheet selected`	Status shown after choosing a worksheet.
`noColumns`	`Selected sheet has no columns`	Error shown when the chosen worksheet contains no columns.
`needsMoreRows`	`Selected sheet needs at least 2 rows`	Error shown when the worksheet does not have enough rows to continue.

Select Header

Variable	Default value	Purpose
`loading`	`Preparing header selection data...`	Loading state shown while header-row preview data is prepared.
`noData`	`No data available`	Message shown when there is no uploaded data to inspect.
`noDataDescription`	`Please upload a CSV file in the previous step to continue.`	Helper text shown when the header step cannot continue without data.
`title`	`Set Header Row`	Title of the header selection step.
`subtitle`	`Select which row contains your column headers. By default, we use the first row.`	Helper text explaining how to choose the header row.
`validHeader`	`Valid header row selected`	Success status shown when a valid header row is chosen.
`emptyColumns`	`{count} empty columns in this row`	Warning label showing how many empty columns a candidate header row has.
`allColumnsEmpty`	`All columns empty in this row`	Warning shown when every header cell in a row is empty.
`emptyColumnsTooltip`	`Header rows must not contain empty columns. Please select a different row.`	Tooltip explaining why a row with empty columns is invalid.
`showingRows`	`Showing {displayed} of {total} rows`	Pagination label for the header-row preview table.
`showAll`	`Show All`	Action label for expanding the preview to all rows.
`moveUp`	`Move header row up`	Action label for shifting the selected header row upward.
`moveDown`	`Move header row down`	Action label for shifting the selected header row downward.

Match Columns

Variable	Default value	Purpose
`loading`	`Preparing column mapping data...`	Loading state shown while column-matching data is prepared.
`autoMatching`	`Auto-matching columns...`	Status shown while the importer automatically suggests column matches.
`title`	`Match Your Columns`	Title of the column matching step.
`subtitle`	`Match your CSV columns to the expected fields. Required fields must be matched or created.`	Helper text explaining how column matching works.
`csvColumnHeader`	`CSV Column Name`	Table header for incoming file columns.
`matchFieldHeader`	`Match to Field`	Table header for the target schema field selection.
`selectFieldPlaceholder`	`Select field...`	Placeholder in the field selection control.
`searchFieldsPlaceholder`	`Search fields...`	Placeholder in the searchable field picker.
`noFieldsFound`	`No fields found.`	Empty state shown when no schema fields match the search.
`unmatchAll`	`Unmatch all`	Action label for clearing all current column mappings.
`unmatchAllConfirmTitle`	`Unmatch all columns?`	Confirmation dialog title for clearing all mappings.
`unmatchAllConfirmDescription`	`This will clear all column mappings.`	Confirmation dialog body for clearing all mappings.
`allRequiredMatched`	`All required fields matched`	Success status shown when every required field has a match.
`matchingConflicts`	`{count} matching conflicts`	Status label showing how many conflicting matches need attention.
`validationIssuesFound`	`Validation issues found`	Status label shown when validation issues are detected during matching.
`goToNextConflict`	`Go to next conflict`	Action label for jumping to the next mapping conflict.
`unmatchedRequiredFields`	`{count} unmatched required fields`	Status label showing how many required fields still need matches.
`requiredFieldsNotMatched`	`Required fields not matched`	Warning label for unmatched required fields.
`goToUnmatchedFields`	`Go to unmatched fields`	Action label for jumping to unmatched required fields.
`validationIssues`	`{count} validation issues`	Count label for column-level validation issues.
`goToNextIssue`	`Go to next issue`	Action label for jumping to the next validation issue.
`addEmptyColumnsForRequired`	`Add empty columns for required fields`	Section label for creating blank columns for required fields.
`createEmptyColumn`	`Create empty column for {fieldName}`	Action label for adding a blank column for a required field.
`requiredFieldsNotAssigned`	`Required fields not assigned`	Warning label when required fields still are not assigned.
`addEmptyColumnTooltip`	`Add an empty column for this required field`	Tooltip for the create-empty-column action.
`previewTooltip`	`Preview data for this column`	Tooltip for opening the column data preview.
`previewShowing`	`Showing {rowCount} rows of {columnName}`	Title for the column preview panel.

Match Options

Variable	Default value	Purpose
`loading`	`Preparing option matching data...`	Loading state shown while option-matching data is prepared.
`title`	`Match Dropdown Values`	Title of the option matching step.
`subtitle`	`Match your file's values with the accepted dropdown options for each field.`	Helper text explaining how option matching works.
`csvValueHeader`	`CSV Source Value`	Table header for values from the imported file.
`matchOptionHeader`	`Match to Option`	Table header for the accepted option target.
`selectOptionPlaceholder`	`Select option...`	Placeholder in the option selection control.
`searchOptionsPlaceholder`	`Search options...`	Placeholder in the searchable option picker.
`noOptionsFound`	`No options found.`	Empty state shown when no options match the search.
`optionalBadge`	`Optional`	Badge shown for fields where option matching is optional.
`customValuesHint`	`This field allows custom values, so unmatched values will be kept as-is.`	Helper text explaining that unmatched values can still be accepted.
`showMore`	`Show {count} more ({remaining} remaining)`	Action label for revealing more unmatched values.
`useCustomValue`	`Use "{value}"`	Action label for keeping a custom value instead of matching it.
`allValuesMatched`	`All values matched`	Success status shown when every value has a match.
`unmatchedValues`	`{count} unmatched values`	Count label for unmatched option values.
`unmatchedValuesFound`	`Unmatched values found`	Warning label shown when unmatched option values remain.
`goToNextUnmatched`	`Go to next unmatched value`	Action label for jumping to the next unmatched option value.
`valueCount`	`{count} values`	Count label for grouped source values.

Review

Variable	Default value	Purpose
`completing`	`Completing your import...`	Status shown while the final import submission is running.
`loading`	`Preparing review data...`	Loading state shown while review data is prepared.
`title`	`Review Your Data`	Title of the review step.
`subtitle`	`Review your data and fix any validation issues before completing.`	Helper text explaining the review step.
`validating`	`Validating data...`	Status shown while review validation is running.
`noRecords`	`No records to import`	Empty state shown when there are no rows to review.
`validatingCells`	`Validating cells...`	Status shown while individual cells are being validated.
`allRecordsValid`	`All {count} records are valid`	Success label shown when every reviewed record is valid.
`recordCount`	`{count} records`	Count label for the total number of records in review.
`filterAll`	`All`	Filter tab label for showing all rows.
`filterValid`	`Valid`	Filter tab label for showing only valid rows.
`filterInvalid`	`Invalid`	Filter tab label for showing only invalid rows.
`clearFilters`	`Clear filters`	Action label for removing active review filters.
`noInvalidRows`	`No invalid rows`	Empty state shown when there are no invalid rows in the current view.
`applyAutofix`	`Apply autofix`	Action label for applying a single suggested fix.
`invalidValue`	`Invalid value`	Label shown on cells or rows with invalid data.
`undo`	`Undo`	Action label for undoing the previous review edit.
`redo`	`Redo`	Action label for redoing a reverted review edit.
`autofixCount`	`{count} Autofixes`	Count label for the number of available autofixes.
`applyAllAutofixes`	`Apply all {count} autofixes`	Action label for applying every available autofix.
`autofixItem`	`Autofix: {description} ({count})`	Label for a grouped autofix option with a description and count.
`filter`	`Filter`	Generic label for filter actions or controls.
`actions`	`Actions`	Generic label for the actions menu or column.
`addRecord`	`Add record`	Action label for adding a new record manually.
`deleteSelectedRecords`	`Delete selected records ({count})`	Action label for deleting the currently selected records.
`exportSelectedRecords`	`Export selected records ({count})`	Action label for exporting the selected records.
`exportFilteredRecords`	`Export filtered records ({count})`	Action label for exporting the filtered set of records.
`exportAllRecords`	`Export all records ({count})`	Action label for exporting every reviewed record.
`exportCSV`	`Export as CSV (.csv)`	Export format label for CSV downloads.
`exportXLSX`	`Export as Excel (.xlsx)`	Export format label for Excel downloads.
`sortAZ`	`Sort A-Z`	Sort label for ascending alphabetical text order.
`sortZA`	`Sort Z-A`	Sort label for descending alphabetical text order.
`sortLowHigh`	`Sort Low to High`	Sort label for ascending numeric values.
`sortHighLow`	`Sort High to Low`	Sort label for descending numeric values.
`sortOldestNewest`	`Sort Oldest to Newest`	Sort label for chronological ascending order.
`sortNewestOldest`	`Sort Newest to Oldest`	Sort label for chronological descending order.
`sortEarlyLate`	`Sort Early to Late`	Sort label for earlier-to-later time values.
`sortLateEarly`	`Sort Late to Early`	Sort label for later-to-earlier time values.
`sortFalseTrue`	`Sort False then True`	Sort label for boolean false-first ordering.
`sortTrueFalse`	`Sort True then False`	Sort label for boolean true-first ordering.
`sortAscending`	`Sort Ascending`	Generic ascending sort label.
`sortDescending`	`Sort Descending`	Generic descending sort label.
`removeSort`	`Remove sort`	Action label for clearing the current sort.
`unpinColumn`	`Unpin Column`	Action label for unpinning a review table column.
`pinColumn`	`Pin Column`	Action label for pinning a review table column.
`clearColumn`	`Clear column`	Action label for clearing values in a column.
`columnAutofix`	`Autofix: {description}`	Label for a column-wide autofix action.
`applyAllColumnAutofixes`	`Apply all autofixes`	Action label for applying every autofix in a column context.
`removeFilter`	`Remove filter`	Action label for removing a specific filter.
`columnMenu`	`Column menu`	Accessible label for the column actions menu.
`emptyDataTitle`	`No data available`	Empty state title shown when review data is missing.
`emptyDataDescription`	`Please complete the previous steps to review your data.`	Empty state description shown when review cannot start yet.
`editFilter`	`Edit filter`	Action label for editing an existing filter.
`filteredColumns`	`Filtered Columns`	Section label for columns with active filters.
`unfilteredColumns`	`Unfiltered Columns`	Section label for columns without active filters.
`columnsLabel`	`Columns`	Generic label for the columns list or menu section.
`promptedEditsTooltip`	`Edit data with a prompt`	Tooltip for opening the prompted edits panel.
`promptedEditsTitle`	`Prompted edits`	Title shown in the prompted edits panel.
`promptedEditsClose`	`Close`	Button label for closing the prompted edits panel.
`promptedEditsCloseDiscardTooltip`	`Close panel and discard changes`	Tooltip for closing the panel and discarding unapplied changes.
`promptedEditsCloseTooltip`	`Close panel`	Tooltip for closing the prompted edits panel without extra context.
`promptedEditsError`	`Cannot generate prompted edit`	Error message shown when prompted edit generation fails.
`promptedEditsPlaceholder`	`Describe a change you want to make, use @ to mention columns`	Placeholder text in the prompted edits input.
`promptedEditsGenerating`	`Generating prompted edit...`	Status shown while the prompted edit is being generated.
`promptedEditsApplying`	`Applying prompted edit to data...`	Status shown while the prompted edit is being applied.
`promptedEditsDiscard`	`Discard changes`	Action label for discarding generated prompted edits.
`promptedEditsApply`	`Apply changes`	Action label for applying generated prompted edits.
`promptedEditsUnappliedTitle`	`You have unapplied changes`	Warning dialog title shown before closing with pending prompted edits.
`promptedEditsUnappliedDescription`	`Your prompted edits have not been applied yet. Do you want to discard them?`	Warning dialog body shown for unapplied prompted edits.
`promptedEditsKeepEditing`	`Keep editing`	Button label for returning to the prompted edits editor.
`promptedEditsDiscardClose`	`Discard & Close`	Button label for discarding prompted edits and closing the panel.
`promptedEditsAbortTitle`	`Abort prompted edit?`	Warning dialog title shown while a prompted edit is still running.
`promptedEditsAbortDescription`	`Your prompted edit is currently running. Closing the panel will abort the operation and you'll lose any progress.`	Warning dialog body shown before aborting an active prompted edit.
`promptedEditsAbortClose`	`Abort & Close`	Button label for aborting the current prompted edit and closing the panel.
`promptedEditsSubmit`	`Submit`	Action label for sending a prompted edit request.

Empty Column

Variable	Default value	Purpose
`defaultName`	`new column {number}`	Default name for a newly created empty column.
`remove`	`Remove`	Action label for deleting an empty column.
`removeTooltip`	`Remove this empty column`	Tooltip for the empty-column remove action.

Validation

Variable	Default value	Purpose
`showOtherMatch`	`Show other match`	Action label for viewing an alternative validation match.

Status

Variable	Default value	Purpose
`successTitle`	`Import Complete`	Title shown on the successful import completion screen.
`successDescription`	`Your data has been imported successfully.`	Description shown on the successful import completion screen.
`errorTitle`	`Import Failed`	Title shown on the failed import screen.
`errorDescription`	`An error occurred while delivering your data.`	Description shown on the failed import screen.
`close`	`Close`	Button label for dismissing the final status screen.

Steps

Variable	Default value	Purpose
`upload`	`Upload`	Step label shown for the upload step in the progress UI.
`selectSheet`	`Select Sheet`	Step label shown for the worksheet selection step.
`selectHeader`	`Select Header`	Step label shown for the header selection step.
`matchColumns`	`Match Columns`	Step label shown for the column matching step.
`matchOptions`	`Match Options`	Step label shown for the option matching step.
`review`	`Review`	Step label shown for the review step.
`progress`	`Step {currentStep} of {totalSteps}`	Progress label that includes the current step number and total step count.

Localization