Localization

Every string the grid writes on its own — visible text, aria-labels, tooltips, placeholders, menu items, filter operators, screen-reader announcements, keyboard shortcut labels and default column headers — is one key of GridLocaleText. Translate them with a localeText map, or in code with getLocaleText.

Translating with `localeText`

import { createGrid, type GridLocaleText } from "@agility-workbench/grid";

const de: Partial<GridLocaleText> = {
  rowsPerPage: "Zeilen pro Seite",
  page: "Seite",
  pageOfTotalOption: "{page} von {total}",
  sortAscending: "Aufsteigend sortieren",
  sortDescending: "Absteigend sortieren",
  selectAll: "(Alle auswählen)",
  blanks: "(Leer)",
  rowsSelectedOne: "{count} Zeile ausgewählt",
  rowsSelectedOther: "{count} Zeilen ausgewählt",
};

createGrid(host, { columnDefs, rowData, pagination: true, localeText: de });

<Grid columnDefs={columnDefs} data={rows} localeText={de} />

<awb-grid [columnDefs]="columnDefs" [rowData]="rows" [localeText]="de" />

The map is partial: a key you leave out keeps its English default. The keys are typed, so a misspelt key is a compile error.

Placeholders. Strings with variables carry {name} placeholders ("Page {page} of {total}"). Keep the names; move them wherever the sentence needs them.
Plurals. A count-dependent string has two keys, …One and …Other (rowsSelectedOne / rowsSelectedOther). The grid picks …One when the count is exactly 1. That is enough for any language with one singular and one plural form.
Dedicated options win. loadingMessage, noRowsMessage, pivotNoValuesMessage, pivotEmptyMessage, paginationUnknownTotalTooltip, filterParams.miniFilterPlaceholder, paginationControls.aggregateScope.unavailableMessage, groupTotalRowLabel and a column's own label override the matching keys (loading, noRows, …).

Translating in code with `getLocaleText`

getLocaleText is called for every string. It receives the key, the text the grid would otherwise use (your localeText entry or the English default, with its placeholders still in) and the placeholder values. Whatever it returns is interpolated afterwards, and it wins over localeText.

Use it for plural rules with more than two forms, ICU messages, or a translation library:

const plural = new Intl.PluralRules("pl");
const rowsSelected = {
  one: "{count} wiersz zaznaczony",
  few: "{count} wiersze zaznaczone",
  many: "{count} wierszy zaznaczonych",
  other: "{count} wiersza zaznaczonego",
};

createGrid(host, {
  columnDefs,
  rowData,
  localeText: pl, // the plain strings
  getLocaleText: ({ key, defaultValue, variableValues }) => {
    if (key === "rowsSelectedOne" || key === "rowsSelectedOther") {
      return rowsSelected[plural.select(Number(variableValues?.count))];
    }
    return defaultValue;
  },
});

With a library such as i18next, map the grid's keys into a namespace and fall back to the default:

getLocaleText: ({ key, defaultValue, variableValues }) =>
  i18next.t(`grid.${key}`, { defaultValue, ...variableValues }),

The resolver applies {placeholder} interpolation after the callback, so the callback may return text with placeholders still in it or fully formatted text.

Reusing the grid's strings in your own components

api.getLocaleText(key, variableValues?) resolves a key exactly as the grid does, so a custom header component, cell renderer or menu item can say "Sort Ascending" in the grid's language:

const api = createGrid(host, {
  columnDefs: [
    {
      key: "region",
      label: "Region",
      columnMenu: ({ items }) => [
        ...items,
        { id: "csv", label: api.getLocaleText("exportAsCsv"), onClick: () => api.exportDataAsCsv() },
      ],
    },
  ],
  rowData,
  localeText: de,
});

class MyHeader {
  init(params) {
    this.eGui.title = params.api.getLocaleText("shortcutSortColumn");
  }
}

For a …One / …Other pair, pick the key from the count and pass { count }.

Switching language

localeText and getLocaleText are creation-only: the grid reads them once. To switch language, create the grid again — in React, change the key of <Grid>; in Angular, re-render <awb-grid> (for example inside an @if or @for keyed by the locale); with createGrid, destroy() and create it again. The bindings warn in development if either changes on a mounted grid.

Numbers and dates

Formatting is separate from translation. Number, currency and date cells follow the column's formatterOptions — locale (default "en-US"), currency, format and the number options — and the set filter's tree layout names its months in that locale too:

{ key: "amount", type: ColumnType.CURRENCY, formatterOptions: { locale: "de-DE", currency: "EUR" } }

What stays as written

Text your application supplies — column labels, menu items, filterOptions labels, cell values and formatted values.
Messages for developers: console warnings and the errors passed to onError.
Keyboard key names in menu accelerators and the shortcut table (Ctrl+C, Esc), which follow the platform's convention.
Export file names (grid-all.csv) and the Excel sheet name (Export).
The blank-value group key (Blanks) used by row grouping and pivot column headers, which is also the group's identity; the set filter's (Blanks) row is translatable (blanks).

All keys

Key	English default
`loading`	Loading data...
`noRows`	No rows to show
`pivotNoValues`	Choose Aggregate on a column to add values
`pivotEmpty`	Add row groups, column labels or values to build the pivot
`hierarchyNavigationMode`	Hierarchy navigation mode
`gridNavigationMode`	Grid navigation mode
`noRowsMatchSearch`	No rows match "{text}"
`noRowsMatchFilters`	No rows match the current filters
`findNoMatches`	No matches
`findMatchOfTotal`	Match {index} of {total}
`rowsPerPage`	Rows per page
`page`	Page
`firstPage`	First page
`previousPage`	Previous page
`nextPage`	Next page
`lastPage`	Last page
`pageOfTotalOption`	{page} of {total}
`pageCountUnknown`	{count}+
`pageOfTotal`	Page {page} of {total}
`pageOfAtLeastTotal`	Page {page} of at least {total}
`pageOfAtLeastTotalWithHint`	Page {page} of at least {total}. {hint}
`paginationUnknownTotal`	More rows may exist on the server; the total updates as they load
`aggregate`	Aggregate
`aggregateScopeNone`	None
`aggregateScopeCurrentPage`	Current page
`aggregateScopeEntireDataset`	Entire dataset
`hideAggregateRow`	Hide aggregate row
`moreFooterControls`	More footer controls
`moreFooterControlsAggregationOn`	More footer controls (aggregation on)
`newPivotSheet`	New pivot sheet
`aggregateScopeEntireDatasetUnavailable`	Entire-dataset totals need a server aggregation source: the data source's getAggregates, or serverSideAggregationSource.
`aggAvgShort`	Avg
`changeAggregation`	Change {column} aggregation. Current function: {aggregate}
`changeAggregationTooltip`	{aggregate} — change aggregation function
`grandTotal`	Grand Total
`groupTotal`	Total {group}
`pivotTotal`	Total
`aggCount`	Count
`aggDistinctCount`	Distinct Count
`aggSum`	Sum
`aggAvg`	Average
`aggMin`	Min
`aggMax`	Max
`aggMedian`	Median
`aggFirst`	First
`aggLast`	Last
`views`	Views
`savedViews`	Saved views
`savedViewNamed`	Saved view: {name}
`noSavedViews`	No saved views
`saveCurrentViewMenu`	Save current view…
`updateView`	Update “{name}”
`renameViewMenu`	Rename “{name}”…
`deleteViewMenu`	Delete “{name}”…
`saveCurrentView`	Save current view
`renameView`	Rename view
`viewName`	View name
`deleteViewConfirm`	Delete “{name}”?
`deleteViewMessage`	This removes the view from the application-owned list.
`viewNamed`	View: {name}
`exportTable`	Export table
`export`	Export
`exportSelection`	Selection
`exportEntireTable`	Entire table
`exportCsv`	CSV
`exportExcel`	Excel
`exportTableAsCsv`	Table as CSV
`exportTableAsExcel`	Table as Excel
`togglePivotMode`	Toggle pivot mode
`pivot`	Pivot
`pivotMode`	Pivot mode
`pivotModeOn`	Pivot mode on
`pivotModeOff`	Pivot mode off
`moreToolbarActions`	More toolbar actions
`moreToolbarActionsActive`	More toolbar actions (active)
`moreActions`	More actions
`search`	Search
`searchHighlighting`	Search — highlighting “{term}”
`searchFiltering`	Search — filtering by “{term}”
`columnsEllipsis`	Columns…
`groupedBy`	Grouped by
`sortBy`	Sort by
`groupedByCount`	Grouped by ({count})…
`sortByCount`	Sort by ({count})…
`sectionSummary`	{caption} {count}
`sectionSummaryEditorOne`	{caption} {count} column — open the editor
`sectionSummaryEditorOther`	{caption} {count} columns — open the editor
`sectionSummaryEditorEmpty`	{caption} — open the editor
`moreGroupingLevelsOne`	{count} more grouping levels — open the grouping editor
`moreGroupingLevelsOther`	{count} more grouping levels — open the grouping editor
`moreSortColumnsOne`	{count} more sort columns — open the sort editor
`moreSortColumnsOther`	{count} more sort columns — open the sort editor
`rowGrouping`	Row grouping
`columnSorting`	Column sorting
`rowGroupingOrder`	Row grouping order
`columnSortPriority`	Column sort priority
`addGroup`	Add group
`addSort`	Add sort
`addGroupEditor`	+ Add group
`addSortEditor`	+ Add sort
`clearRowGrouping`	Clear row grouping
`clearGrouping`	Clear grouping
`clearAllSorting`	Clear all sorting
`clearSorting`	Clear sorting
`reorderHintHorizontal`	Use Left and Right arrows to reorder.
`reorderHintVertical`	Use Up and Down arrows to reorder.
`groupChip`	{column}, grouping level {index} of {total}. {hint}
`sortChipAscending`	{column}, sort priority {index} of {total}, ascending. {hint}
`sortChipDescending`	{column}, sort priority {index} of {total}, descending. {hint}
`removeFromRowGrouping`	Remove {column} from row grouping
`removeFromSorting`	Remove {column} from sorting
`sortDirectionFixedAscending`	{column} sort direction is fixed to ascending
`sortDirectionFixedDescending`	{column} sort direction is fixed to descending
`sortColumnAscending`	Sort {column} ascending
`sortColumnDescending`	Sort {column} descending
`cancel`	Cancel
`save`	Save
`delete`	Delete
`columns`	Columns
`columnManagement`	Column management
`pivotSetup`	Pivot setup
`openColumnPanel`	Open column panel
`closeColumnPanel`	Close column panel
`searchColumns`	Search columns
`searchColumnsPlaceholder`	Search columns…
`allColumns`	All columns
`allMatchingColumns`	All matching columns
`modified`	Modified
`resetLayout`	Reset layout
`columnLayoutReset`	Column layout reset
`pinnedLeft`	Pinned left
`pinnedRight`	Pinned right
`noColumns`	No columns
`noMatchingColumns`	No matching columns
`columnsHiddenOne`	{count} column hidden
`columnsHiddenOther`	{count} columns hidden
`columnsShownOne`	{count} column shown
`columnsShownOther`	{count} columns shown
`matchingColumnsHiddenOne`	{count} matching column hidden
`matchingColumnsHiddenOther`	{count} matching columns hidden
`matchingColumnsShownOne`	{count} matching column shown
`matchingColumnsShownOther`	{count} matching columns shown
`expandColumnGroup`	Expand {group}
`collapseColumnGroup`	Collapse {group}
`showColumn`	Show {column}
`hideColumn`	Hide {column}
`columnHidden`	{column} hidden
`columnShown`	{column} shown
`pinColumn`	Pin {column}
`unpinned`	Unpinned
`pinLeftOption`	Pin left
`pinRightOption`	Pin right
`columnPinnedLeft`	{column} pinned left
`columnPinnedRight`	{column} pinned right
`columnUnpinned`	{column} unpinned
`moveItemUp`	Move {item} up
`moveItemDown`	Move {item} down
`movedToPosition`	{item} moved to position {position} of {total}
`groupRole`	Group
`groupRoleNumbered`	Group {index}
`pivotRole`	Pivot
`pivotRoleNumbered`	Pivot {index}
`removeFromRowGroups`	Remove {column} from row groups
`removeFromPivotColumns`	Remove {column} from pivot columns
`removeAggregateFromColumn`	Remove {aggregate} aggregate from {column}
`removedFromRowGroups`	{column} removed from row groups
`removedFromPivotColumns`	{column} removed from pivot columns
`aggregateChangedTo`	{column} aggregate changed to {aggregate}
`aggregateRemovedFrom`	{aggregate} aggregate removed from {column}
`rowGroupsWell`	Row groups
`columnLabelsWell`	Column labels
`valuesWell`	Values
`addRowGroup`	Add row group
`addPivotColumn`	Add pivot column
`addValue`	Add value
`valueEntry`	{column} — {aggregate}
`wellEmpty`	None
`wellOrder`	{well} order
`removeFromWell`	Remove {item} from {well}
`movedToPositionInWell`	{item} moved to position {position} of {total} in {well}
`noColumnsToAdd`	No columns available to add
`aggregateFunctionFor`	Aggregate function for {column}
`dropToSectionEnd`	Drop here to move branch to section end
`searchPlaceholder`	Search…
`findPlaceholder`	Find…
`searchAllColumns`	Search all columns
`findInAllColumns`	Find in all columns
`clearSearch`	Clear search
`searchOptions`	Search options
`closeSearch`	Close search
`closeSearchHint`	Close (Esc)
`previousMatch`	Previous match
`nextMatch`	Next match
`previousMatchHint`	Previous match (Shift+Enter)
`nextMatchHint`	Next match (Enter)
`findMatchesOne`	{count} match
`findMatchesOther`	{count} matches
`findUnavailableServerSide`	Highlighting matches is not available when rows load from the server
`findUnavailablePivot`	Highlighting matches is not available while the grid is pivoted
`matchModeLabel`	Match
`matchAllWords`	All words
`matchExactPhrase`	Exact phrase
`matchWholeCell`	Whole cell
`matchCase`	Match case
`behaviorFilterRows`	Filter rows
`behaviorHighlightMatches`	Highlight matches
`anchorLabel`	Anchor
`anchorRight`	Right
`anchorLeft`	Left
`keepFilterWhenClosed`	Keep filter when closed
`activeSearchPill`	Active search — click to edit
`sheets`	Sheets
`addPivotSheet`	Add pivot sheet
`pivotSheetsUnsupported`	Pivot sheets need the client-side row model without tree data
`dataSheetName`	Data
`pivotSheetName`	Pivot {index}
`sheetCopyName`	{name} (copy)
`renameSheet`	Rename sheet {name}
`rename`	Rename
`changeColor`	Change color
`duplicate`	Duplicate
`sheetColorNone`	None
`sheetColorCustom`	Custom…
`lastSheetCannotBeDeleted`	The last sheet cannot be deleted
`sheetActions`	Sheet actions
`sheetColorRed`	Red
`sheetColorOrange`	Orange
`sheetColorAmber`	Amber
`sheetColorLime`	Lime
`sheetColorGreen`	Green
`sheetColorTeal`	Teal
`sheetColorCyan`	Cyan
`sheetColorBlue`	Blue
`sheetColorIndigo`	Indigo
`sheetColorViolet`	Violet
`sheetColorPink`	Pink
`sheetColorGray`	Gray
`sortAscending`	Sort Ascending
`sortDescending`	Sort Descending
`clearSort`	Clear Sort
`clearSorts`	Clear Sorts
`hideColumnMenu`	Hide Column
`hideColumnsMenu`	Hide Columns
`pinColumnMenu`	Pin Column
`pinColumnsMenu`	Pin Columns
`pinLeft`	Pin Left
`pinRight`	Pin Right
`unpinColumn`	Unpin Column
`unpinColumns`	Unpin Columns
`manageColumns`	Manage columns…
`clearSelection`	Clear Selection
`columnsCount`	{count} columns
`showSparklines`	Show Sparklines
`barSparklines`	Bar Sparklines
`lineSparklines`	Line Sparklines
`areaSparklines`	Area Sparklines
`aggregateNumeric`	Aggregate (numeric)
`aggregateString`	Aggregate (string)
`clearAggregation`	Clear Aggregation
`clearAggregations`	Clear Aggregations
`exportAsCsv`	Export as CSV
`exportAsExcel`	Export as Excel
`ungroup`	Ungroup
`ungroupAll`	Ungroup All
`grouping`	Grouping
`groupByColumn`	Group by Column
`groupByColumns`	Group by Columns
`replaceExistingGrouping`	Replace Existing Grouping
`addToExistingGrouping`	Add to Existing Grouping
`removeColumnFromGrouping`	Remove Column from Grouping
`removeColumnsFromGrouping`	Remove Columns from Grouping
`clearAllGrouping`	Clear All Grouping
`pivotOnColumn`	Pivot on Column
`pivotOnColumns`	Pivot on Columns
`replaceExistingPivot`	Replace Existing Pivot
`addToExistingPivot`	Add to Existing Pivot
`removeColumnFromPivot`	Remove Column from Pivot
`removeColumnsFromPivot`	Remove Columns from Pivot
`exitPivotMode`	Exit Pivot Mode
`cut`	Cut
`copy`	Copy
`copyWithHeaders`	Copy with Headers
`paste`	Paste
`fillDown`	Fill down
`fillRight`	Fill right
`fillAsCopyInstead`	Copy cells instead
`fillAsSeriesInstead`	Fill series instead
`exportWithRowGroups`	Export with row groups
`exportLeafRows`	Export leaf rows
`exportGroupHeadingNotInRange`	The group heading column is not part of the selected range.
`insert`	Insert
`insertRowAbove`	1 row above
`insertRowBelow`	1 row below
`pinRow`	Pin row
`pinRows`	Pin rows
`unpinRow`	Unpin row
`unpinRows`	Unpin rows
`pinToTop`	Pin to top
`pinToBottom`	Pin to bottom
`menu`	Menu
`submenu`	Submenu
`cellMenu`	Cell menu
`columnMenu`	Column menu
`columnMenuMultiple`	Column menu, {count} columns
`rowNumber`	Row number
`selectAllRows`	Select all rows
`deselectAllRows`	Deselect all rows
`groupColumn`	Group
`hierarchyColumn`	Hierarchy
`sparklineColumn`	Sparkline
`filterEqual`	Equal
`filterNotEqual`	Not equal
`filterGreaterThan`	Greater than
`filterGreaterThanOrEqual`	Greater than or equal
`filterLessThan`	Less than
`filterLessThanOrEqual`	Less than or equal
`filterBetween`	Between
`filterNotBetween`	Not between
`filterContains`	Contains
`filterExcludes`	Excludes
`filterStartsWith`	Starts with
`filterEndsWith`	Ends with
`filterIsBlank`	Is blank
`filterIsNotBlank`	Is not blank
`filterNotIn`	Not in
`filterDialog`	Filter {column}
`filterJoinAnd`	AND
`filterJoinOr`	OR
`filterValue`	Filter value
`filterAny`	Any
`filterTrue`	True
`filterFalse`	False
`clearFilterValue`	Clear
`filterApply`	apply
`filterCancel`	cancel
`filterClear`	clear
`filterReset`	reset
`selectAll`	(Select All)
`blanks`	(Blanks)
`selectAllValues`	Select all values
`includeBlankValues`	Include blank values
`filterValues`	Filter values
`setFilterSearchPlaceholder`	Type to filter values
`setFilterSearchPlaceholderWithExample`	Type to filter values, e.g. {example}
`setFilterLoading`	Loading data…
`setFilterLoadError`	Error loading values
`setFilterLoadFailed`	Failed to load values
`setFilterRowCountUnitOne`	row
`setFilterRowCountUnitOther`	rows
`filledCellsOne`	Filled {count} cell
`filledCellsOther`	Filled {count} cells
`filledCellsAsCopiesOne`	Filled {count} cell as copies
`filledCellsAsCopiesOther`	Filled {count} cells as copies
`filledCellsAsSeriesOne`	Filled {count} cell as a series
`filledCellsAsSeriesOther`	Filled {count} cells as a series
`fillNothingNoEditableCells`	Nothing to fill: no editable cells
`fillNothingNoAdjacentData`	Nothing to fill: no data beside the selection
`rowsSelectedOne`	{count} row selected
`rowsSelectedOther`	{count} rows selected
`columnsSelectedOne`	{count} column selected
`columnsSelectedOther`	{count} columns selected
`rangeSelected`	{rows} by {columns} selected
`rangeRowsOne`	{count} row
`rangeRowsOther`	{count} rows
`rangeColumnsOne`	{count} column
`rangeColumnsOther`	{count} columns
`selectionCleared`	Selection cleared
`sortingCleared`	Sorting cleared
`sortedBy`	Sorted by {columns}
`sortedBySeparator`	, then
`sortedColumnAscending`	{column} ascending
`sortedColumnDescending`	{column} descending
`loadingAnnouncement`	Loading data
`rowsLoadedOne`	{count} row loaded
`rowsLoadedOther`	{count} rows loaded
`selectEditorLoading`	Loading…
`ratingValue`	{value} of {max}
`shortcutQuickFilter`	Quick filter
`shortcutNextSheet`	Next sheet
`shortcutPreviousSheet`	Previous sheet
`shortcutOpenColumnMenu`	Open column menu
`shortcutOpenColumnFilter`	Open column filter
`shortcutExtendColumnSelectionLeft`	Extend the column selection left
`shortcutExtendColumnSelectionRight`	Extend the column selection right
`shortcutExtendColumnSelectionFirst`	Extend the column selection to the first column
`shortcutExtendColumnSelectionLast`	Extend the column selection to the last column
`shortcutFirstColumn`	First column
`shortcutLastColumn`	Last column
`shortcutPreviousColumn`	Previous column
`shortcutNextColumn`	Next column
`shortcutEnterRows`	Enter the rows
`shortcutSelectColumn`	Select column
`shortcutSortColumn`	Sort column
`shortcutSwitchTreeNavigationMode`	Switch tree navigation mode
`shortcutTreeNavigation`	Tree navigation
`shortcutToggleRowSelection`	Toggle row selection
`shortcutSelectRow`	Select row
`shortcutOpenActionFrame`	Open the cell's action frame
`shortcutEditCell`	Edit cell
`shortcutSelectAllCells`	Select all cells
`shortcutCopy`	Copy
`shortcutCut`	Cut
`shortcutPaste`	Paste
`shortcutFillDown`	Fill down
`shortcutFillRight`	Fill right
`shortcutUndo`	Undo
`shortcutRedo`	Redo
`shortcutClearCells`	Clear cell contents
`shortcutMoveToHeader`	Move to the column header
`shortcutTypeToEdit`	Start editing by typing
`shortcutMoveUp`	Move up
`shortcutMoveDown`	Move down
`shortcutMoveLeft`	Move left
`shortcutMoveRight`	Move right

Translating with localeText​

Translating in code with getLocaleText​

Reusing the grid's strings in your own components​

Switching language​

Numbers and dates​

What stays as written​

All keys​