Localization

Every user-facing string in the widget 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,
  publishableKey: "pk_test_...",
  importIdentifier: "user-import",
  locale: {
    general: {
      cancel: "Abbrechen",
      back: "Zurück",
      next: "Weiter",
      finish: "Fertig",
      required: "Pflichtfeld",
      optional: "Optional",
    },
    widget: {
      title: "Daten importieren",
    },
    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 widget section:

Section	What it covers
`general`	Shared labels: cancel, back, next, finish, required, optional, matched/unmatched
`widget`	Widget chrome: title, loading, close confirmation, error messages
`sessionRecovery`	Resume 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 phantom column names

Sections

General

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`	Explains why Next is disabled on the upload step.
`nextDisabledSelectSheet`	`Select a valid sheet to continue`	Explains why Next is disabled until a valid worksheet is selected.
`nextDisabledSelectHeader`	`Select a header row to continue`	Explains why Next is disabled until a header row is selected.
`nextDisabledMatchColumns`	`Map all required columns to continue`	Explains why Next is disabled until required fields are matched.
`nextDisabledMatchOptions`	`Complete all required options to continue`	Explains why Next is disabled until required option mappings are done.
`nextDisabledReviewValidating`	`Validation in progress, please wait…`	Explains why Next is disabled while review validation is still running.
`nextDisabledReviewInvalid`	`Fix all invalid rows to continue`	Explains why Next is disabled while invalid review rows remain.

Variable	Default value	Purpose
`title`	`ExpressCSV Widget`	Main title shown in the widget chrome.
`loading`	`Loading…`	Loading state shown while the widget initializes.
`closeConfirmTitle`	`Are you sure?`	Title of the confirm dialog shown before closing the widget.
`closeConfirmDescription`	`Closing this dialog will cause you to lose any progress made so far.`	Body text explaining the consequence of closing the widget.
`closeConfirmCancel`	`Cancel`	Button label for staying in the widget.
`closeConfirmContinue`	`Continue`	Button label for confirming the close action.
`errorTitle`	`Unable to Continue`	Title shown in a top-level widget error state.
`startOver`	`Start Over`	Button label for resetting the import flow after an error.
`invalidPublishableKey`	`This publishable key is not recognized. Check your configuration and try again.`	Error shown when the widget receives an invalid publishable key.

Session Recovery

Variable	Default value	Purpose
`message`	`You have an incomplete import. Resume where you left off?`	Prompt shown when a saved session can be resumed.
`discard`	`Discard Session`	Button label for discarding a saved import session.
`resume`	`Resume Session`	Button label for resuming a saved import 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`	`Restored session`	Status shown when a previous session is restored.
`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 widget 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.
`transformTooltip`	`Transform data with AI`	Tooltip for opening the AI transform panel.
`transformTitle`	`Transform data with AI`	Title shown in the AI transform panel.
`transformClose`	`Close`	Button label for closing the transform panel.
`transformCloseDiscardTooltip`	`Close panel and discard changes`	Tooltip for closing the panel and discarding unapplied changes.
`transformCloseTooltip`	`Close panel`	Tooltip for closing the transform panel without extra context.
`transformError`	`Cannot generate transformation`	Error message shown when AI transform generation fails.
`transformPlaceholder`	`Describe a change you want to make, use @ to mention columns`	Placeholder text in the AI transform prompt input.
`transformGenerating`	`Generating transformation...`	Status shown while the AI transformation is being generated.
`transformApplying`	`Applying transformation to data...`	Status shown while the AI transformation is being applied.
`transformDiscard`	`Discard changes`	Action label for discarding generated transform changes.
`transformApply`	`Apply changes`	Action label for applying generated transform changes.
`transformUnappliedTitle`	`You have unapplied changes`	Warning dialog title shown before closing with pending transform changes.
`transformUnappliedDescription`	`Your transformation changes have not been applied yet. Do you want to discard them?`	Warning dialog body shown for unapplied transform changes.
`transformKeepEditing`	`Keep editing`	Button label for returning to the transform editor.
`transformDiscardClose`	`Discard & Close`	Button label for discarding transform changes and closing the panel.
`transformAbortTitle`	`Abort transformation?`	Warning dialog title shown while a transformation is still running.
`transformAbortDescription`	`Your transformation is currently running. Closing the panel will abort the operation and you'll lose any progress.`	Warning dialog body shown before aborting an active transformation.
`transformAbortClose`	`Abort & Close`	Button label for aborting the current transformation and closing the panel.
`transformSubmit`	`Submit`	Action label for sending a transformation request.

Phantom Column

Variable	Default value	Purpose
`defaultName`	`new column {number}`	Default name for a newly created empty column.
`remove`	`Remove`	Action label for deleting a phantom column.
`removeTooltip`	`Remove this empty column`	Tooltip for the phantom-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.

On this page