# General Translation Platform: formatCurrency
URL: https://generaltranslation.com/ja/docs/platform/core/reference/gt-class-methods/formatting/format-currency.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: GT インスタンスでロケールに応じて通貨の値を整形します。formatCurrency の API リファレンス。

General Translation は、通貨スタイルを指定した組み込みの `Intl.NumberFormat` API を使用しているため、金額は各ロケールに応じた適切な記号、桁区切り、小数点の表記で表示されます。

## 概要 [#overview]

[`GT`](/docs/platform/core/reference/gt-class/constructor) インスタンスの `formatCurrency` に、数値、通貨コード、および任意のオプションオブジェクトを渡して呼び出します。整形された通貨文字列が返されます。

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

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

シグネチャ:

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

*注: `formatCurrency` は `Intl.NumberFormat` を使ってローカルで実行されるため、API キーは不要です。デフォルトではインスタンスの対象ロケール向けにフォーマットされ、対象ロケールが使えない場合はソースロケール、次に library のデフォルト (`en`) にフォールバックします。上書きするには `locales` を渡してください。`GT` インスタンスなしでフォーマットする場合は、スタンドアロンの [`formatCurrency`](/docs/platform/core/reference/utility-functions/formatting/format-currency) を参照してください。*

## 仕組み [#how-it-works]

* **Currency スタイル。** 書式設定は、`style: 'currency'` と指定された `currency` コードを使って [`Intl.NumberFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) に委ねられます。
* **ロケールの解決。** デフォルトでは、このメソッドはインスタンスの対象ロケールで書式設定を行い、次にソースロケール、最後にライブラリのデフォルト (`en`) へフォールバックします。`locales` 設定配列は参照されません。上書きするには、options で `locales` を渡してください。
* **記号の配置。** 通貨記号、桁区切り、小数の書式は、通貨の国ではなく、解決されたロケールに従います。

## パラメータ [#parameters]

| パラメータ                   | 説明                                                                   | 型        | 任意  | デフォルト |
| ----------------------- | -------------------------------------------------------------------- | -------- | --- | ----- |
| [`value`](#value)       | 書式設定する数値です。                                                          | `number` | いいえ | —     |
| [`currency`](#currency) | `USD` や `EUR` などの ISO 4217 通貨コードです。                                  | `string` | いいえ | —     |
| [`options`](#options)   | `locales` のオーバーライドを追加した `Intl.NumberFormatOptions` を拡張する、書式設定用の構成です。 | `object` | はい  | —     |

### `value` [#value]

**Type** `number` · **必須**

書式設定する数値の値です。

### `currency` [#currency]

**Type** `string` · **必須**

`USD`、`EUR`、`JPY` などの ISO 4217 の通貨コード。

### `options` [#options]

**型** `{ locales?: string | string[] } & Intl.NumberFormatOptions` · **任意**

フォーマットの構成です。この表には、公開されている Core 型で提供される一般的な通貨オプションと、その実効的な Core のデフォルト値を示します (補足的な標準仕様およびランタイム固有の詳細については、[`Intl.NumberFormat` コンストラクターのオプション](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#options)を参照してください) 。

| 名前                         | 説明                                                                                                         | 型                                                                                                                 | 任意 | デフォルト                                      |
| -------------------------- | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | -- | ------------------------------------------ |
| `locales`                  | フォーマットに使用するロケールを上書きします。                                                                                    | `string \| string[]`                                                                                                 | はい | `targetLocale` → `sourceLocale` → `en`     |
| `localeMatcher`            | ロケール照合アルゴリズム。                                                                                              | `'lookup' \| 'best fit'`                                                                                             | はい | `'best fit'`                               |
| `numberingSystem`          | `latn` や `arab` などの数字体系。                                                                                   | `string`                                                                                                             | はい | `'latn'`                                   |
| `style`                    | 数値フォーマットのスタイル。上書きしない限り、`formatCurrency` が通貨スタイルを指定します。                                                     | `'decimal' \| 'currency' \| 'percent' \| 'unit'`                                                                     | はい | `'currency'`                               |
| `currency`                 | フォーマッタで使用する通貨コード。上書きしない限り、位置引数の `currency` がこの値を指定します。                                                     | `string`                                                                                                             | はい | 位置引数の `currency`                           |
| `currencyDisplay`          | 通貨の表示方法。                                                                                                   | `'symbol' \| 'narrowSymbol' \| 'code' \| 'name'`                                                                     | はい | `'symbol'`                                 |
| `currencySign`             | 使用する通貨記号。                                                                                                  | `'standard' \| 'accounting'`                                                                                         | はい | `'standard'`                               |
| `unit`                     | 単位識別子。`style` が `'unit'` の場合は必須です。                                                                         | `string`                                                                                                             | はい | —                                          |
| `unitDisplay`              | 単位の表示方法。                                                                                                   | `'short' \| 'narrow' \| 'long'`                                                                                      | はい | `'short'`                                  |
| `minimumFractionDigits`    | 最小小数桁数 (0～100) 。                                                                                           | `number`                                                                                                             | はい | 通貨の補助単位桁数。コンパクト表記のデフォルトでは `0`              |
| `maximumFractionDigits`    | 最大小数桁数 (0～100) 。`minimumFractionDigits` 以上である必要があります。                                                      | `number`                                                                                                             | はい | 通貨の補助単位桁数。コンパクト表記のデフォルトでは `0`              |
| `minimumSignificantDigits` | 有効桁数による丸めが有効な場合の最小有効桁数 (1～21) 。                                                                            | `number`                                                                                                             | はい | `1`                                        |
| `maximumSignificantDigits` | 有効桁数による丸めが有効な場合の最大有効桁数 (1～21) 。                                                                            | `number`                                                                                                             | はい | `21`。コンパクト表記のデフォルトでは `2`                   |
| `roundingPriority`         | 小数桁数と有効桁数の設定の優先方法。                                                                                         | `'auto' \| 'morePrecision' \| 'lessPrecision'`                                                                       | はい | `'auto'`。コンパクト表記のデフォルトでは `'morePrecision'` |
| `roundingMode`             | 丸めモード。                                                                                                     | `'ceil' \| 'floor' \| 'expand' \| 'trunc' \| 'halfCeil' \| 'halfFloor' \| 'halfExpand' \| 'halfTrunc' \| 'halfEven'` | はい | `'halfExpand'`                             |
| `roundingIncrement`        | 丸め増分。デフォルト以外の値を使用するには、有効な最小小数桁数と最大小数桁数が同じである必要があり、有効桁数による丸めや `'auto'` 以外の `roundingPriority` とは組み合わせられません。 | `1 \| 2 \| 5 \| 10 \| 20 \| 25 \| 50 \| 100 \| 200 \| 250 \| 500 \| 1000 \| 2000 \| 2500 \| 5000`                    | はい | `1`                                        |
| `useGrouping`              | 桁区切り文字を使用するか、および使用するタイミング。                                                                                 | `boolean \| 'always' \| 'auto' \| 'min2'`                                                                            | はい | `'auto'`。コンパクト表記のデフォルトでは `'min2'`          |
| `notation`                 | 数値表記形式。                                                                                                    | `'standard' \| 'scientific' \| 'engineering' \| 'compact'`                                                           | はい | `'standard'`                               |
| `compactDisplay`           | コンパクト表記の表示スタイル。                                                                                            | `'short' \| 'long'`                                                                                                  | はい | `'short'`                                  |
| `signDisplay`              | 符号を表示するタイミング。                                                                                              | `'auto' \| 'never' \| 'always' \| 'exceptZero' \| 'negative'`                                                        | はい | `'auto'`                                   |
| `trailingZeroDisplay`      | 末尾のゼロを表示するかどうか。                                                                                            | `'auto' \| 'stripIfInteger'`                                                                                         | はい | `'auto'`                                   |

小数桁数または有効桁数のオプションを指定せずに `notation: 'compact'` を設定した場合、実効的な桁数のデフォルト値は `minimumFractionDigits: 0`、`maximumFractionDigits: 0`、`minimumSignificantDigits: 1`、`maximumSignificantDigits: 2` です。この場合、`roundingPriority` のデフォルトは `'morePrecision'`、`useGrouping` のデフォルトは `'min2'` です。`style: 'unit'` を設定する場合は、有効な `unit` も指定する必要があります。

## 戻り値 [#returns]

**型** `string`

ローカライズされた通貨文字列として書式設定された値です。

## 例 [#examples]

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

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

// デフォルトのインスタンスtargetLocale
console.log(gt.formatCurrency(1234.56, 'USD'));
// 出力: "$1,234.56"

// 呼び出しごとにロケールを上書き
console.log(gt.formatCurrency(1234.56, 'EUR', { locales: ['de-DE'] }));
// 出力: "1.234,56 €"

// 小数部の桁なし
console.log(gt.formatCurrency(1234, 'JPY', { locales: ['ja-JP'] }));
// 出力: "￥1,234"
```

## メモ [#notes]

* このメソッドは内部でブラウザネイティブの `Intl.NumberFormat` を使用しているため、金額はロケールの慣例に従います。
* 出力を細かく調整するには、`Intl.NumberFormatOptions` (たとえば `minimumFractionDigits`) を `locales` とあわせて渡してください。

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.