# General Translation Platform: formatCurrency
URL: https://generaltranslation.com/en-US/docs/platform/core/reference/gt-class-methods/formatting/format-currency.mdx
---

title: formatCurrency
description: Format a currency value by locale on a GT instance. API reference for formatCurrency.

---

Formats a numeric value as a localized currency string on a [GT](/docs/platform/core/reference/gt-class/constructor) instance. General Translation uses the built-in `Intl.NumberFormat` API with the currency style, so amounts render with the correct symbol, grouping, and decimal conventions for each locale.

## Overview [#overview]

Call `formatCurrency` on a [`GT`](/docs/platform/core/reference/gt-class/constructor) instance with a numeric value, a currency code, and an optional options object. It returns the formatted currency string.

```typescript
const gt = new GT({ targetLocale: 'en-US' });

const price = gt.formatCurrency(1234.56, 'USD');
// "$1,234.56"
```

Signature:

```typescript
formatCurrency(
  value: number,
  currency: string,
  options?: { locales?: string | string[] } & Intl.NumberFormatOptions
): string
```

*Note: `formatCurrency` runs locally using `Intl.NumberFormat` and does not require an API key. By default it formats for the instance's target locale, falling back to the source locale and then the library default (`en`); pass `locales` to override. For formatting without a `GT` instance, see the standalone [`formatCurrency`](/docs/platform/core/reference/utility-functions/formatting/format-currency).*

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

- **Currency style.** Formatting is delegated to [`Intl.NumberFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) with `style: 'currency'` and the provided `currency` code.
- **Locale resolution.** By default the method formats for the instance's target locale, falling back to the source locale and then the library default (`en`) — not the `locales` config array. Pass `locales` in the options to override.
- **Symbol placement.** The currency symbol, grouping separators, and decimal format follow the resolved locale, not the currency's country.

## Parameters [#parameters]

| Parameter | Description | Type | Optional | Default |
| --- | --- | --- | --- | --- |
| [`value`](#value) | The numeric amount to format. | `number` | No | — |
| [`currency`](#currency) | The ISO 4217 currency code, such as `USD` or `EUR`. | `string` | No | — |
| [`options`](#options) | Formatting configuration, extending `Intl.NumberFormatOptions` with a `locales` override. | `object` | Yes | — |

### `value` [#value]

**Type** `number` · **Required**

The numeric amount to format.

### `currency` [#currency]

**Type** `string` · **Required**

The ISO 4217 currency code, such as `USD`, `EUR`, or `JPY`.

### `options` [#options]

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

Formatting configuration. Extends `Intl.NumberFormatOptions` with an additional `locales` field:

| Name | Description | Type | Optional | Default |
| --- | --- | --- | --- | --- |
| `locales` | Override locales for formatting. | `string \| string[]` | Yes | instance target locale |
| `style` | Number formatting style; defaults to currency formatting. | `string` | Yes | `'currency'` |

## Returns [#returns]

**Type** `string`

The value formatted as a localized currency string.

## Examples [#examples]

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

const gt = new GT({ targetLocale: 'en-US' });

// Default instance target locale
console.log(gt.formatCurrency(1234.56, 'USD'));
// Output: "$1,234.56"

// Override the locale per call
console.log(gt.formatCurrency(1234.56, 'EUR', { locales: ['de-DE'] }));
// Output: "1.234,56 €"

// No fractional digits
console.log(gt.formatCurrency(1234, 'JPY', { locales: ['ja-JP'] }));
// Output: "￥1,234"
```

## Notes [#notes]

- The method uses browser-native `Intl.NumberFormat` under the hood, so amounts follow the locale's conventions.
- Pass any `Intl.NumberFormatOptions` (for example, `minimumFractionDigits`) alongside `locales` to fine-tune the output.