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 gets lang="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 the filterOperator* keys), and the dayjs ja date names and formats as plain data (午前/午後, {n}日 ordinals).
  • Japanese header word order at every zoom: 2025年12月 over 12/29~, 1/5~ at week zoom, and 2026年 over 第1四半期 zoomed out (2026年度 once you set a fiscal year; see below).
  • YYYY/MM/DD dates in the task list and tooltips (YYYY/MM/DD HH:mm when inputDateFormat has time tokens). Editors keep inputDateFormat.
  • 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
SettingHighest to lowest
Messages, per keylocale.messages, then pack.messages, then English
Date localelocale.dateLocale, then pack.dateLocale, then none
Header format, per tier and rowlocale.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 startcalendar.weekStart, then pack.weekStart, then the date locale's weekStart, then Sunday
Fiscal year startcalendar.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)
Directionlocale.direction (when you set it), then pack.dir, then 'ltr'
Language taglocale.tag, then pack.tag, then none
Read-only date patternlocale.displayDateFormat, then the pack's displayDateTimeFormat (time-bearing inputDateFormat) or displayDateFormat, then inputDateFormat
Crosshair labelthe 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.fiscalYearStartMonthYear rowQuarter rowNarrow quarter
not set2026年 (January to December)第1四半期 (January to March)1Q
42026年度 (April 2026 to March 2027)第1四半期 (April to June)1Q
12026年度 (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:

LocaleImport path
Frenchdayjs/locale/fr
Germandayjs/locale/de
Spanishdayjs/locale/es
Japanesedayjs/locale/ja
Arabicdayjs/locale/ar
Hebrewdayjs/locale/he
Chinese (simplified)dayjs/locale/zh-cn
Portuguesedayjs/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 (a lang you set on the container comes back when the tag goes, and on destroy());
  • 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 50 is 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, tooltipDateLabel and tooltipDependsOnLabel, separate from the baseline tooltip's startLabel and endLabel;
  • the column titles (columnName, columnStartTime, columnEndTime, columnDuration and the rest; columnConfig[].title still wins);
  • durations (durationDays, '{count} d'; durationWorkingDays, durationHours, durationMinutes), progressValue ('{value}%') and listSeparator;
  • the dependency tooltip (tooltipDependencyValue, dependencyLag, dependencyTypeFS, dependencyTypeSS, dependencyTypeFF, dependencyTypeSF);
  • selectedCount ('{count} selected'), newTaskName ('New task') and exportFileName ('gantt-chart-{timestamp}');
  • the 15 filter operators (filterOperatorContains, filterOperatorGt and the rest), which filterOperatorLabel reads;
  • summaryAriaLabelExpand, summaryAriaLabelCollapse and barAriaLabelWithProgress, companions of the aria builders below;
  • 19 aria-label keys, from taskListAriaLabel ('Gantt task list') and timelineHeaderAriaLabel to 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:

KeyDefaultContext
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) => stringHuman-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: ' + nameEdit 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) => stringSummary-bar aria-label builder. ctx: { name, canToggle, collapsed }, plus task since 3.20.0
barAriaLabel(ctx) => stringTask-bar aria-label builder. ctx: { name, start, end, progress? }, plus task since 3.20.0
barAriaValueText(ctx) => stringTask-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 keyIts template (English)Params
filterOperatorLabel{operator}operator is the operator's filterOperator* text, so setting those 15 keys is usually enough
groupCountLabel({count})count
editTaskTitleEdit 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} daysstart, end, durationDays
progressAriaLabel{name} progressname
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.

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 (ABC finds abc, ガ 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>