# General Translation Platform: formatDateTime
URL: https://generaltranslation.com/en-GB/docs/platform/core/reference/utility-functions/formatting/format-date-time.mdx
---

title: formatDateTime
description: Format dates and times without a GT instance. API reference for formatDateTime.

---

[`formatDateTime`](/docs/platform/core/reference/gt-class-methods/formatting/format-date-time) is a standalone utility function from General Translation's Core library that formats dates and times according to locale-specific conventions. It returns a locale-aware string for a `Date`.

## Overview [#overview]

Import `formatDateTime` directly from `generaltranslation` and call it with a `Date` and an options object. It does not require an API key or a [GT](/docs/platform/core/reference/gt-class/constructor) instance. For instance-based formatting that inherits the instance locale, use the [`formatDateTime`](/docs/platform/core/reference/gt-class-methods/formatting/format-date-time) method on a [`GT`](/docs/platform/core/reference/gt-class/constructor) instance instead.

```typescript
import { formatDateTime } from 'generaltranslation';

const formatted = formatDateTime(new Date(), {
  locales: 'de-DE',
  dateStyle: 'medium',
  timeStyle: 'short',
});
// Returns a locale-formatted string, e.g. "26.09.2025, 17:33"
```

Signature:

```typescript
formatDateTime(
  date: Date,
  options?: { locales?: string | string[] } & Intl.DateTimeFormatOptions
): string
```

## How it works [#how-it-works]

* **Underlying API.** Uses the same [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) as the GT class method, so all standard `Intl.DateTimeFormat` options are supported.
* **Locale resolution.** When `locales` is an array, locales are tried in order. When `locales` is omitted, it falls back to the library default locale, `en`.
* **Time zones.** Output respects the `timeZone` option when provided; otherwise, the runtime's local time zone is used. Different locales have different default date/time formats and 12-hour versus 24-hour preferences.
* **Caching.** Results are cached internally for performance across repeated locale and option combinations.

## Parameters [#parameters]

| Parameter             | Description                                                                                     | Type                                                            | Optional | Default |
| --------------------- | ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | -------- | ------- |
| [`date`](#date)       | The date object to format.                                                                      | `Date`                                                          | No       | —       |
| [`options`](#options) | Formatting configuration, including the target locale(s) and any `Intl.DateTimeFormat` options. | `{ locales?: string \| string[] } & Intl.DateTimeFormatOptions` | Yes      | `{}`    |

### `date` [#date]

**Type** `Date` · **Required**

The `Date` object to format.

### `options` [#options]

**Type** `{ locales?: string | string[] } & Intl.DateTimeFormatOptions` · **Optional** · **Default** `{}`

Formatting configuration. Any [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) option is accepted in addition to `locales`. Common fields:

| Property    | Description                                                       | Type                                                      | Optional | Default |
| ----------- | ----------------------------------------------------------------- | --------------------------------------------------------- | -------- | ------- |
| `locales`   | Locale(s) for formatting. Tried in order when an array is passed. | `string \| string[]`                                      | Yes      | `en`    |
| `dateStyle` | Overall date formatting style.                                    | `'full' \| 'long' \| 'medium' \| 'short'`                 | Yes      | —       |
| `timeStyle` | Overall time formatting style.                                    | `'full' \| 'long' \| 'medium' \| 'short'`                 | Yes      | —       |
| `weekday`   | Weekday representation.                                           | `'long' \| 'short' \| 'narrow'`                           | Yes      | —       |
| `year`      | Year representation.                                              | `'numeric' \| '2-digit'`                                  | Yes      | —       |
| `month`     | Month representation.                                             | `'numeric' \| '2-digit' \| 'long' \| 'short' \| 'narrow'` | Yes      | —       |
| `day`       | Day representation.                                               | `'numeric' \| '2-digit'`                                  | Yes      | —       |
| `hour`      | Hour representation.                                              | `'numeric' \| '2-digit'`                                  | Yes      | —       |
| `minute`    | Minute representation.                                            | `'numeric' \| '2-digit'`                                  | Yes      | —       |
| `second`    | Second representation.                                            | `'numeric' \| '2-digit'`                                  | Yes      | —       |
| `timeZone`  | IANA time zone identifier.                                        | `string`                                                  | Yes      | —       |
| `hour12`    | Whether to use the 12-hour time format.                           | `boolean`                                                 | Yes      | —       |

## Returns [#returns]

**Type** `string`

The date and time formatted according to locale conventions.

## Examples [#examples]

```typescript
import { formatDateTime } from 'generaltranslation';

const date = new Date('2024-03-14T14:30:45Z');

// Basic formatting with an explicit locale
console.log(formatDateTime(date, { locales: 'en-US', timeZone: 'UTC' }));
// Output: "3/14/2024"

// German formatting
console.log(formatDateTime(date, { locales: 'de-DE', timeZone: 'UTC' }));
// Output: "14.3.2024"

// Multiple locale fallbacks
console.log(formatDateTime(date, { locales: ['ja-JP', 'en-US'], timeZone: 'UTC' }));
// Output: "2024/3/14" (Japanese format)
```

```typescript
// Date and time styles
const date = new Date('2024-03-14T14:30:45Z');

// Full date style
console.log(formatDateTime(date, {
  locales: 'en-US',
  dateStyle: 'full',
  timeZone: 'UTC',
}));
// Output: "Thursday, March 14, 2024"

// Long date with short time
console.log(formatDateTime(date, {
  locales: 'fr-FR',
  dateStyle: 'long',
  timeStyle: 'short',
  timeZone: 'UTC',
}));
// Output: "14 mars 2024 à 14:30"
```

```typescript
// Time zone handling
const date = new Date('2024-03-14T14:30:45Z');

const timeZones = ['America/New_York', 'Europe/London', 'Asia/Tokyo'];

timeZones.forEach((timeZone) => {
  const formatted = formatDateTime(date, {
    locales: 'en-US',
    timeZone,
    dateStyle: 'medium',
    timeStyle: 'medium',
  });
  console.log(`${timeZone}: ${formatted}`);
});
// Output varies based on daylight saving time
```

## Notes [#notes]

* Uses the same underlying `Intl.DateTimeFormat` as the GT class method.
* Results are cached internally for performance with repeated locale/options combinations.
* All standard `Intl.DateTimeFormat` options are supported.
* Time zones are handled correctly when specified. Output without a fixed `timeZone` depends on the runtime environment.