Localization and RTL
ApexGantt's localization covers several independent concerns: the date and month labels in the timeline header (driven by a dayjs locale and, since 3.22.0, locale.timelineHeaderFormat), the generated strings (driven by locale.messages), how read-only dates are shown (locale.displayDateFormat), the language the chart reports (locale.tag), and the layout direction for RTL languages (locale.direction). Since 3.22.0 a locale pack sets all of them at once.
The Localization & RTL demo switches between English, French, German, Arabic, Hebrew and the Japanese pack.
Locale packs
Since 3.22.0. A locale pack is one plain-data object, safe to keep as JSON, that sets a whole language: the messages, the date names, the header word order, how read-only dates are shown, and the week start that language's users expect. Pass it as locale.pack. It is the base layer: every explicit locale.* and calendar.* option still wins over it.
A pack changes the language and the date formats, not where the year starts. Since 3.23.0 the shipped ja pack sets no fiscal year, and you opt into fiscal years with calendar.fiscalYearStartMonth (see Japanese fiscal years (年度)). A pack's header formats can carry rows used only while a fiscal year is in use, so the same pack reads 2026年 without one and 2026年度 with one.
ApexGantt ships one pack, Japanese (ja). Each pack is a separate file of about 2.8 KB gzip next to the library, so the core bundle does not grow and you load only the languages you use.
import ApexGantt from 'apexgantt'
import { ja } from 'apexgantt/locales/ja'
const gantt = new ApexGantt(document.getElementById('chart'), {
series: tasks,
locale: { pack: ja },
})
gantt.render()
With CommonJS, const { ja } = require('apexgantt/locales/ja'). With script tags, locales/ja.min.js sets ApexGanttLocales.ja and can load before or after the library:
<script src="https://cdn.jsdelivr.net/npm/apexgantt@3.23.1/apexgantt.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/apexgantt@3.23.1/locales/ja.min.js"></script>
<script>
const gantt = new ApexGantt(document.getElementById('chart'), {
series: tasks,
locale: { pack: ApexGanttLocales.ja },
})
gantt.render()
</script>
The pack is also published as apexgantt/locales/ja.json, for tooling or a server that sends it to the page. Types ship for both module formats; the CommonJS types need TypeScript 5.3 or later under node16 or nodenext resolution.
The Japanese pack is reviewed. Since 3.23.1 its status is 'reviewed' (it was 'draft' in 3.22.0 and 3.23.0): Japanese users of ApexGantt reviewed the wording, from the timeline header rows and the fiscal year labels to the filter operators and the screen-reader text. status is metadata only; the chart does not read it. The wording can still change in any release; when it does, that release's notes call it out under "Changed". Pin an exact version if your tests or screenshots depend on the labels. Wording comments are still welcome as issues on the ApexGantt repository.
What ja sets:
tag: 'ja', so the chart root getslang="ja", message templates use Japanese plural and number rules, and text sorts and groups with Japanese collation.- All 123 message strings (every key except
filterOperatorLabel, which reads thefilterOperator*keys), and the dayjsjadate names and formats as plain data (午前/午後,{n}日ordinals). - Japanese header word order at every zoom:
2025年12月over12/29~,1/5~at week zoom, and2026年over第1四半期zoomed out (2026年度once you set a fiscal year; see below). YYYY/MM/DDdates in the task list and tooltips (YYYY/MM/DD HH:mmwheninputDateFormathas time tokens). Editors keepinputDateFormat.- Monday weeks (
weekStart: 1). This shapes the timeline header only and never turns the working calendar on.
Since 3.23.0 the pack sets no fiscal year. In 3.22.0 it set an April fiscal year (fiscalYearStartMonth: 4), so its headers always read 年度; add calendar: { fiscalYearStartMonth: 4 } to keep that. A copy of the 3.22.0 pack that you vendored (ja.json or ja.min.js) still carries the key, and no calendar value turns a pack's fiscal year off, so replace the copy with the 3.23.0 one for calendar years.
Override any part of it as you would without a pack:
locale: {
pack: ja,
messages: { addTask: '追加' }, // one key; the rest stay the pack's
timelineHeaderFormat: { week: { sub: 'M/D~{end:M/D}' } }, // one row; the rest stay the pack's
},
calendar: { weekStart: 0, fiscalYearStartMonth: 4 }, // Sunday weeks, 年度 from April
| Setting | Highest to lowest |
|---|---|
| Messages, per key | locale.messages, then pack.messages, then English |
| Date locale | locale.dateLocale, then pack.dateLocale, then none |
| Header format, per tier and row | locale.timelineHeaderFormat, then pack.timelineHeaderFormat, then built-in |
| Header format while a fiscal year is in use (since 3.23.0) | locale.timelineHeaderFormat.fiscal, then locale.timelineHeaderFormat, then pack.timelineHeaderFormat.fiscal, then pack.timelineHeaderFormat, then the built-in fiscal labels |
| Week start | calendar.weekStart, then pack.weekStart, then the date locale's weekStart, then Sunday |
| Fiscal year start | calendar.fiscalYearStartMonth, then pack.fiscalYearStartMonth, then none (calendar years). Any valid month set in either place, 1 included, puts the chart in fiscal-year mode (since 3.23.0) |
| Direction | locale.direction (when you set it), then pack.dir, then 'ltr' |
| Language tag | locale.tag, then pack.tag, then none |
| Read-only date pattern | locale.displayDateFormat, then the pack's displayDateTimeFormat (time-bearing inputDateFormat) or displayDateFormat, then inputDateFormat |
| Crosshair label | the crosshairLabelFormat function, then locale.crosshairFormat, then pack.crosshairFormat, then built-in |
update({ locale: { pack: undefined } }) returns the chart to English. A string passed as pack logs one warning and is ignored.
Any object of the GanttLocalePack shape works as a pack, so a translation can live in your own code or come from a server as JSON. tag and status are required; every other field is optional. A pack's messages are inserted like locale.messages (see Overriding UI strings), so do not put untrusted input in them.
In React, pass the pack in the options (options={{ locale: { pack: ja } }}); every message in it is a string, so the wrapper sees the same options on each render and no memoizing is needed. The other wrappers take it the same way, through their options.
Japanese fiscal years (年度)
Since 3.23.0. On its own, locale: { pack: ja } shows calendar years and quarters. For 年度 planning add calendar: { fiscalYearStartMonth: 4 }, which is right for most Japanese organizations: the year row switches to 年度 by itself, with no other option to change.
const gantt = new ApexGantt(el, {
series: tasks,
locale: { pack: ja },
calendar: { fiscalYearStartMonth: 4 }, // 年度 from April; leave it out for calendar years
})
calendar.fiscalYearStartMonth | Year row | Quarter row | Narrow quarter |
|---|---|---|---|
| not set | 2026年 (January to December) | 第1四半期 (January to March) | 1Q |
4 | 2026年度 (April 2026 to March 2027) | 第1四半期 (April to June) | 1Q |
1 | 2026年度 (January to December) | 第1四半期 (January to March) | 1Q |
The quarter row never repeats the year, because the year row is always above it. It reads 1Q in cells narrower than 96 px. The label is picked per cell and quarters run 90 to 92 days, so at a zoom that puts the cells either side of 96 px one row can show both 第1四半期 and 1Q. A 年度 is named by the calendar year it starts in, so January to March 2026 is 第4四半期 of 2025年度.
The pack does this with a fiscal block in its timelineHeaderFormat: year: { top: 'YYYY年', sub: 'YYYY年' } for calendar years and fiscal: { year: { top: '{fy}年度', sub: '{fy}年度' } } while a fiscal year is in use. Your own pack can do the same; see Rows for fiscal years only.
Date locale
Pass a dayjs-compatible locale object to locale.dateLocale to localize the month, weekday and AM/PM names in the timeline header, the dates in bar aria-labels and the weekday in the default crosshair label:
import ApexGantt from 'apexgantt'
import localeFr from 'dayjs/locale/fr'
const gantt = new ApexGantt(document.getElementById('chart'), {
series: tasks,
locale: {
dateLocale: localeFr,
},
})
Install dayjs in your project if it is not already present. ApexGantt uses it internally but does not re-export locale files:
npm install dayjs
Then import any locale from dayjs/locale/*. Popular examples:
| Locale | Import path |
|---|---|
| French | dayjs/locale/fr |
| German | dayjs/locale/de |
| Spanish | dayjs/locale/es |
| Japanese | dayjs/locale/ja |
| Arabic | dayjs/locale/ar |
| Hebrew | dayjs/locale/he |
| Chinese (simplified) | dayjs/locale/zh-cn |
| Portuguese | dayjs/locale/pt |
Dates shown with inputDateFormat (the task list, tooltips and task form) keep that format; set locale.displayDateFormat to show them in another pattern. The header keeps the built-in English word order (12月 2025); change it with locale.timelineHeaderFormat. A meridiem may also be a plain [am, pm] pair and an ordinal a '{n}日' template, which keeps a hand-built locale JSON-safe.
Since 3.22.0 week cells follow the week start. With a dateLocale whose weekStart is not 0, week cells start on that day (Monday for de, fr, ru, en-gb and most European locales; Saturday for ar), and the week number on each cell matches it. Before, cells always ran Sunday to Saturday while the numbers followed the locale, so a German chart labelled the week starting Sunday 4 January 2026 as week 1. English, and ja without the pack, are unchanged. Set calendar.weekStart: 0 to keep Sunday weeks; see Week start and fiscal year.
Since 3.22.0 the timeline header rows get lang set to the date locale's name, so CJK text is drawn with the right glyph shapes and screen readers read the dates in that language. Bar aria-labels use the locale's long date (LL): 2026年1月4日 in ja, 4 janvier 2026 in fr.
Language tag
Since 3.22.0. locale.tag takes a BCP 47 tag such as 'ja' or 'ja-JP' (else the pack's tag). When one resolves:
- it is set as the chart root's
lang(alangyou set on the container comes back when the tag goes, and ondestroy()); - message templates use its plural rules and number formatting;
- text sorting and grouping use its collation;
- the progress fields in the task form and inline editor become text fields with a decimal keyboard, so a full-width IME value such as
50is read as 50.
A malformed tag ('ja_JP' for 'ja-JP') is ignored as if unset, so the root gets no lang and sorting falls back to the runtime's collation. Without a tag or a pack the chart's DOM is unchanged.
Read-only dates and the crosshair
Since 3.22.0. locale.displayDateFormat is a dayjs pattern for dates the user reads but does not edit: the Start, End, Baseline Start and Baseline End columns and the bar, milestone and baseline tooltips, formatted in the date locale. Editors keep inputDateFormat, and stored dates are unchanged.
const gantt = new ApexGantt(el, {
series: tasks,
inputDateFormat: 'YYYY-MM-DD',
locale: {
dateLocale: localeFr,
displayDateFormat: 'D MMM YYYY', // 4 janv. 2026
crosshairFormat: { date: 'dddd D MMMM', time: 'D/M HH:mm' },
},
})
locale.crosshairFormat sets the default crosshair label's patterns as strings: date on day-and-coarser tiers (default 'ddd MM/DD/YYYY') and time on halfday, hour and minute tiers (default 'MM/DD HH:mm'). The crosshairLabelFormat function, when set, wins over both. Patterns take the tokens listed under Pattern tokens.
RTL layout
Set locale.direction to 'rtl' to mirror the entire chart: the timeline flows right-to-left, the task list moves to the right side, and the dir="rtl" attribute is applied to the container element.
import ApexGantt from 'apexgantt'
import localeAr from 'dayjs/locale/ar'
const gantt = new ApexGantt(el, {
series: tasks,
locale: {
direction: 'rtl',
dateLocale: localeAr,
},
})
'auto' defers to the document or element's inherited dir attribute. The default is 'ltr'.
Since 3.20.0 a right-to-left chart opens at the start of the timeline, scrollToTask() and setState({ scroll }) work, bars keep their positions after zooming, and the keyboard shortcuts for moving and resizing a focused bar are mirrored (ArrowRight moves a bar earlier). Earlier versions could open scrolled to the far end and misplace bars after a zoom. The first paint now lands flush on the start of the grid, about 40px further than 3.19, which scrolled to the full scroll width.
Saved scroll under RTL. Since 3.20.0 getState().scroll.horizontal is measured from where the time axis starts, which is the right edge under RTL, so 0 is the start of the timeline in both directions. State saved by 3.19 or earlier in an RTL chart was measured from the left edge and restores to a different position. See Saving and Restoring State.
Progress handle under RTL. Since 3.20.0 the progress handle and its percent label sit on the fill edge, centred on it, on first paint and after a progress drag, updateTask({ progress }), undo or redo.
Switching direction at runtime requires an update() call:
gantt.update({ locale: { direction: 'rtl' } })
Overriding UI strings
locale.messages accepts a partial GanttMessages object (typed GanttMessagesInput since 3.22.0). Any key you supply replaces the English default (or the pack's text); unset keys keep their defaults.
const gantt = new ApexGantt(el, {
series: tasks,
locale: {
messages: {
addTask: 'Neue Aufgabe',
deleteSelected: 'Ausgewählte löschen',
undo: 'Rückgängig (Strg+Z)',
redo: 'Wiederholen (Strg+Y)',
exportAsSvg: 'Als SVG exportieren',
editTask: 'Aufgabe bearbeiten',
addChildTask: 'Unteraufgabe hinzufügen',
addSiblingTask: 'Geschwisteraufgabe hinzufügen',
indent: 'Einrücken',
outdent: 'Ausrücken',
deleteTask: 'Aufgabe löschen',
deleteTaskWithChildren: 'Löschen (mit Unteraufgaben)',
},
},
})
Message keys
The table lists the keys up to 3.21. Since 3.22.0 there are 72 more, 124 keys in all, each defaulting to the English text it replaces, so an English chart is unchanged:
- the seven bar tooltip labels:
tooltipTaskLabel('Task:'),tooltipStartLabel,tooltipEndLabel,tooltipDurationLabel,tooltipProgressLabel,tooltipDateLabelandtooltipDependsOnLabel, separate from the baseline tooltip'sstartLabelandendLabel; - the column titles (
columnName,columnStartTime,columnEndTime,columnDurationand the rest;columnConfig[].titlestill wins); - durations (
durationDays,'{count} d';durationWorkingDays,durationHours,durationMinutes),progressValue('{value}%') andlistSeparator; - the dependency tooltip (
tooltipDependencyValue,dependencyLag,dependencyTypeFS,dependencyTypeSS,dependencyTypeFF,dependencyTypeSF); selectedCount('{count} selected'),newTaskName('New task') andexportFileName('gantt-chart-{timestamp}');- the 15 filter operators (
filterOperatorContains,filterOperatorGtand the rest), whichfilterOperatorLabelreads; summaryAriaLabelExpand,summaryAriaLabelCollapseandbarAriaLabelWithProgress, companions of the aria builders below;- 19 aria-label keys, from
taskListAriaLabel('Gantt task list') andtimelineHeaderAriaLabelto the sort, resize, scroll, dependency and dialog-close labels.
The new keys are strings: a {name} in one is filled with that param, and {n, number} and {n, plural, ...} work as in the templates below. The full list, with every default and param, is in the ApexGantt README.
Messages are inserted as text or HTML depending on where they appear, and message text is never escaped for you, so do not put untrusted input in messages. Task data passed in as params (names, ids) keeps the escaping it always had.
The keys up to 3.21:
| Key | Default | Context |
|---|---|---|
zoomIn | 'Zoom In' | Toolbar button (tooltip and aria-label), since 3.20.0 |
zoomOut | 'Zoom Out' | Toolbar button (tooltip and aria-label), since 3.20.0 |
addTask | 'Add task' | Toolbar button |
deleteSelected | 'Delete selected' | Toolbar button |
undo | 'Undo (Ctrl+Z)' | Toolbar button |
redo | 'Redo (Ctrl+Y)' | Toolbar button |
exportAsSvg | 'Export as SVG' | Toolbar button (SVG format) |
exportAsPng | 'Export as PNG' | Toolbar button (PNG format) |
exportAsPdf | 'Export as PDF' | Toolbar button (PDF format) |
quickFilterPlaceholder | 'Search tasks…' | Quick-filter search box |
filterButton | 'Filter' | Filter builder toolbar button |
filterHeading | 'Filter tasks' | Filter builder popover heading |
filterMatchLabel | 'Match' | Filter builder match-mode label |
filterMatchAll | 'All' | Filter builder match-all (AND) option |
filterMatchAny | 'Any' | Filter builder match-any (OR) option |
filterAddCondition | '+ Add condition' | Filter builder add-condition button |
filterApply | 'Apply' | Filter builder apply button |
filterClear | 'Clear' | Filter builder clear button |
filterRemoveCondition | 'Remove condition' | Filter builder remove-condition aria-label |
filterNoConditions | 'No conditions yet.' | Filter builder empty state |
filterOperatorLabel | (operator) => string | Human-readable label for a filter operator |
groupNone | '(None)' | Group header label for an empty group value |
groupCountLabel | (count) => '(' + count + ')' | Group header member-count label |
exportFailedNoChart | 'Export failed: Chart not found. Please refresh and try again.' | Export failure alert |
exportFailedGeneric | 'Export failed. Please check the console for details.' | Export failure alert |
editTask | 'Edit task' | Context menu |
addChildTask | 'Add child task' | Context menu |
addSiblingTask | 'Add sibling task' | Context menu |
indent | 'Indent' | Context menu |
outdent | 'Outdent' | Context menu |
deleteTask | 'Delete task' | Context menu (leaf) |
deleteTaskWithChildren | 'Delete (with children)' | Context menu (parent) |
formTaskName | 'Task Name' | Edit form label |
formStartDate | 'Start Date' | Edit form label |
formEndDate | 'End Date' | Edit form label |
formProgress | 'Progress (%)' | Edit form label |
formSubmit | 'Update' | Edit form button |
editTaskTitle | (name) => 'Edit Task: ' + name | Edit dialog title |
validationStartRequired | 'Start date is required' | Validation |
validationEndRequired | 'End date is required' | Validation |
validationEndAfterStart | 'End date must be after start date' | Validation |
validationNameRequired | 'Task name is required' | Validation |
validationProgressRequired | 'Progress is required' | Validation |
validationProgressRange | 'Progress must be between 0 and 100' | Validation |
addTaskRowLabel | '+ Add task' | Inline add-task row |
baselineLabel | 'Baseline:' | Baseline tooltip |
startLabel | 'Start:' | Baseline tooltip |
endLabel | 'End:' | Baseline tooltip |
summaryAriaLabel | (ctx) => string | Summary-bar aria-label builder. ctx: { name, canToggle, collapsed }, plus task since 3.20.0 |
barAriaLabel | (ctx) => string | Task-bar aria-label builder. ctx: { name, start, end, progress? }, plus task since 3.20.0 |
barAriaValueText | (ctx) => string | Task-bar aria-valuetext builder. ctx: { start, end, durationDays }, plus task since 3.20.0 |
progressAriaLabel | (name) => name + ' progress' | Progress-handle aria-label builder |
Since 3.22.0 the seven function keys also take a template string, so a dictionary of strings (JSON, or Blazor's Dictionary<string, string>) can set them. A function you pass is used as it is.
| Function key | Its template (English) | Params |
|---|---|---|
filterOperatorLabel | {operator} | operator is the operator's filterOperator* text, so setting those 15 keys is usually enough |
groupCountLabel | ({count}) | count |
editTaskTitle | Edit Task: {name} | name |
summaryAriaLabel | {name} (summary) | name; a summary bar that can toggle reads summaryAriaLabelExpand or summaryAriaLabelCollapse |
barAriaLabel | {name}: {start} to {end} | name, start, end; a read-only bar reads barAriaLabelWithProgress |
barAriaValueText | {start} to {end}, {durationDays} days | start, end, durationDays |
progressAriaLabel | {name} progress | name |
locale: {
tag: 'de',
messages: {
editTaskTitle: 'Aufgabe bearbeiten: {name}',
groupCountLabel: '({count, plural, one {# Aufgabe} other {# Aufgaben}})',
selectedCount: '{count, number} ausgewählt',
},
}
Since 3.20.0 the bar's aria-label and aria-valuetext are rebuilt from these builders after every accepted edit (drag, resize, progress drag, dialog, inline, updateTask()), not only after keyboard edits. The builder contexts carry a required task, so code that calls DEFAULT_GANTT_MESSAGES.barAriaLabel(...) directly must pass one.
The full English defaults are exported as DEFAULT_GANTT_MESSAGES (the resolved form, with functions for the seven function keys), so you can spread them as a base and override selectively:
import ApexGantt, { DEFAULT_GANTT_MESSAGES } from 'apexgantt'
const gantt = new ApexGantt(el, {
series: tasks,
locale: {
messages: { ...DEFAULT_GANTT_MESSAGES, addTask: 'Neue Aufgabe' },
},
})
Since 3.22.0 GanttMessages has 72 more required keys, so a complete GanttMessages literal written by hand no longer type-checks: spread DEFAULT_GANTT_MESSAGES into it, or type it as GanttMessagesInput. Options are unaffected, because locale.messages takes a partial set. Code that reads a function key back from your own options object needs a typeof check before calling it, since it may now hold a string. The messages the chart hands to a custom tooltip (context.messages) still hold functions.
Input methods and search
Since 3.22.0 the chart works with input method editors (IME), as used for Japanese, Chinese and Korean:
- The quick filter waits for a composition to end before filtering, on every chart, since filtering re-renders the chart and would end a conversion in progress. Some Android keyboards compose ordinary Latin words too, so there the list filters when a word is finished rather than on every letter. Desktop typing without an IME is unchanged.
- An Enter that confirms a conversion does not commit an inline edit, and an Escape that cancels one does not close the task dialog.
- The quick filter and the filter builder's text operators compare Unicode NFKC-folded text, so full-width and other compatibility forms match their plain forms (
ABCfindsabc,ガfindsガ). What is shown is unchanged.
Changing locale at runtime
update() merges locale settings shallowly:
gantt.update({
locale: {
direction: 'rtl',
dateLocale: localeAr,
messages: {
addTask: 'إضافة مهمة',
deleteSelected: 'حذف المحدد',
},
},
})
React example
import { useEffect, useState } from 'react'
import { ApexGanttChart } from 'react-apexgantt'
import type { GanttUserOptions } from 'react-apexgantt'
export default function LocalizedGantt() {
const [locale, setLocale] = useState<GanttUserOptions['locale']>({
direction: 'ltr',
})
const switchToArabic = async () => {
const localeAr = (await import('dayjs/locale/ar')).default
setLocale({ direction: 'rtl', dateLocale: localeAr })
}
return (
<div>
<button onClick={switchToArabic}>Switch to Arabic (RTL)</button>
<ApexGanttChart
tasks={tasks}
options={{ locale }}
height="500px"
/>
</div>
)
}
Vue example
<template>
<div>
<button @click="switchToArabic">Switch to Arabic (RTL)</button>
<ApexGanttChart :tasks="tasks" :options="ganttOptions" height="500px" />
</div>
</template>
<script setup lang="ts">
import { ref } from 'vue'
import type { GanttUserOptions } from 'vue-apexgantt'
const ganttOptions = ref<Partial<GanttUserOptions>>({
locale: { direction: 'ltr' },
})
const switchToArabic = async () => {
const localeAr = (await import('dayjs/locale/ar')).default
ganttOptions.value = {
locale: {
direction: 'rtl',
dateLocale: localeAr,
},
}
}
</script>