# General Translation Platform: formatNum
URL: https://generaltranslation.com/ja/docs/platform/core/reference/utility-functions/formatting/format-num.mdx
---

title: formatNum
description: GT インスタンスなしで数値、通貨、パーセンテージなどの値をフォーマットします。formatNum の API リファレンス。

---

[`formatNum`](/docs/platform/core/reference/gt-class-methods/formatting/format-num) は、General Translation のコアライブラリにあるスタンドアロンのユーティリティ関数で、ロケールごとの規則に従って数値をフォーマットします。小数、通貨、パーセンテージ、単位を、ロケールに応じた文字列として返します。

## 概要 [#overview]

`generaltranslation` から `formatNum` を直接インポートし、フォーマットする数値と options object を渡して呼び出します。APIキーや [GT](/docs/platform/core/reference/gt-class/constructor) インスタンスは不要なため、その場限りの数値フォーマットが必要な場面であればどこでも使えます。インスタンスのロケールを引き継いでフォーマットする場合は、代わりに [`GT`](/docs/platform/core/reference/gt-class/constructor) インスタンスの [`formatNum`](/docs/platform/core/reference/gt-class-methods/formatting/format-num) メソッドを使用してください。

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

const formatted = formatNum(1234.56, {
  locales: 'de-DE',
  style: 'currency',
  currency: 'EUR',
});
// 戻り値: "1.234,56 €"
```

シグネチャ:

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

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

* **基盤となる API。** GT class メソッドと同じ [`Intl.NumberFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) を使用しているため、標準の `Intl.NumberFormat` オプションをすべてサポートしています。
* **ロケールの決定。** `locales` が配列の場合、ロケールを順に試し、最初にサポートされているロケールを使用します。`locales` を省略した場合は、ライブラリのデフォルトロケールである `en` にフォールバックします。
* **キャッシュ。** パフォーマンス向上のため、同じロケールとオプションの組み合わせでの結果は内部的にキャッシュされます。

## パラメータ [#parameters]

| パラメータ                 | 説明                                                  | 型                                                             | 任意  | デフォルト |
| --------------------- | --------------------------------------------------- | ------------------------------------------------------------- | --- | ----- |
| [`number`](#number)   | 書式設定する数値です。                                         | `number`                                                      | いいえ | —     |
| [`options`](#options) | 対象のロケールと `Intl.NumberFormat` の各種オプションを含む、書式設定の構成です。 | `{ locales?: string \| string[] } & Intl.NumberFormatOptions` | はい  | `{}`  |

### `number` [#number]

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

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

### `options` [#options]

**Type** `{ locales?: string | string[] } & Intl.NumberFormatOptions` · **任意** · **デフォルト** `{}`

書式設定オプションです。`locales` に加えて、[`Intl.NumberFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) の任意のオプションを指定できます。よく使われる主なフィールドは次のとおりです。

| Property                | Description                             | Type                                                       | Optional | Default      |
| ----------------------- | --------------------------------------- | ---------------------------------------------------------- | -------- | ------------ |
| `locales`               | 書式設定に使用するロケールです。配列が渡された場合は先頭から順に試されます。  | `string \| string[]`                                       | Yes      | `en`         |
| `style`                 | 数値の書式設定スタイルです。                          | `'decimal' \| 'currency' \| 'percent' \| 'unit'`           | Yes      | `'decimal'`  |
| `currency`              | 通貨コード (`style` が `'currency'` の場合は必須) 。 | `string`                                                   | Yes      | —            |
| `minimumIntegerDigits`  | 整数部の最小桁数 (1–21) 。                       | `number`                                                   | Yes      | —            |
| `minimumFractionDigits` | 小数部の最小桁数 (0–20) 。                       | `number`                                                   | Yes      | —            |
| `maximumFractionDigits` | 小数部の最大桁数 (0–20) 。                       | `number`                                                   | Yes      | —            |
| `useGrouping`           | 桁区切りを使用するかどうか。                          | `boolean \| 'always' \| 'auto' \| 'min2'`                  | Yes      | `'auto'`     |
| `notation`              | 数値表記の形式です。                              | `'standard' \| 'scientific' \| 'engineering' \| 'compact'` | Yes      | `'standard'` |

## 戻り値 [#returns]

**型** `string`

ロケールの規則に従って書式化された数値です。

## 例 [#examples]

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

// 基本的な数値フォーマット
console.log(formatNum(1234.567, { locales: 'en-US' }));
// 出力: "1,234.567"

// ドイツ語フォーマット
console.log(formatNum(1234.567, { locales: 'de-DE' }));
// 出力: "1.234,567"
```

```typescript
// 通貨のフォーマット

// 米ドル
console.log(formatNum(1234.56, {
  locales: 'en-US',
  style: 'currency',
  currency: 'USD',
}));
// 出力: "$1,234.56"

// ドイツロケールのユーロ
console.log(formatNum(1234.56, {
  locales: 'de-DE',
  style: 'currency',
  currency: 'EUR',
}));
// 出力: "1.234,56 €"

// 日本円
console.log(formatNum(1234.56, {
  locales: 'ja-JP',
  style: 'currency',
  currency: 'JPY',
}));
// 出力: "¥1,235"
```

## メモ [#notes]

* GT class method と同じ `Intl.NumberFormat` を基盤として使用します。
* パフォーマンス向上のため、同じロケールとオプションの組み合わせが繰り返される場合、結果は内部的にキャッシュされます。
* プライマリ ロケールがサポートされていない場合は、フォールバック ロケールが順に処理されます。
* 標準の `Intl.NumberFormat` オプションはすべてサポートされています。