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

title: formatCutoff
description: GT インスタンスなしで、ロケールに応じた切り詰め記号を使ってテキストを切り詰めます。formatCutoff の API リファレンス。

---

[`formatCutoff`](/docs/platform/core/reference/gt-class-methods/formatting/format-cutoff) は、General Translation の Core ライブラリに含まれるスタンドアロンのユーティリティ関数で、ロケールに応じた切り詰め記号を使って文字列を切り詰めます。省略記号やその前後のスペースに関する各言語の慣習に従います。

## 概要 [#overview]

`generaltranslation` から `formatCutoff` を直接インポートし、文字列とオプションオブジェクトを渡して呼び出します。APIキーや [GT](/docs/platform/core/reference/gt-class/constructor) インスタンスは必要ありません。インスタンスのロケールを引き継いで切り詰める場合は、代わりに [`GT`](/docs/platform/core/reference/gt-class/constructor) インスタンスの [`formatCutoff`](/docs/platform/core/reference/gt-class-methods/formatting/format-cutoff) メソッドを使用してください。

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

const formatted = formatCutoff('Hello, world!', {
  locales: 'en-US',
  maxChars: 8,
});
// 戻り値: "Hello, …"
```

シグネチャ:

```typescript
formatCutoff(
  value: string,
  options?: { locales?: string | string[] } & CutoffFormatOptions
): string
```

## 動作の仕組み [#how-it-works]

terminator と separator も `maxChars` に含まれます。つまり、返される文字列 (terminator を含む) は最大でも `maxChars` 文字です。

### 文字数の上限

* **正の `maxChars`:** 先頭から切り詰め、末尾に terminator を追加します。
* **負の `maxChars`:** 末尾から切り出し (`Array.prototype.slice` の挙動に従います) 、先頭に terminator を追加します。
* **`maxChars` が 0 の場合:** 空文字列を返します。
* **`maxChars` が未定義の場合:** 切り詰めは行われません。

### ロケールごとの省略記号

ロケールによって、省略記号の慣習は異なります。

* **フランス語:** 狭い非改行スペース (`\u202F`) で区切った `…`。
* **中国語/日本語:** 区切りなしの二重省略記号 `……`。
* **デフォルト:** 区切りなしの単一省略記号 `…`。

### エッジケース

* terminator と区切り文字を合わせた長さが `maxChars` を超える場合、結果は空文字列になります。
* `maxChars` より短い文字列は、そのまま返されます。
* `'none'` スタイルでは、terminator を付けずに切り詰めます。
* `locales` を省略した場合は、ライブラリのデフォルトロケールである `en` が使用されます。

## パラメータ [#parameters]

| パラメータ                 | 説明                      | 型                                                        | 任意  | デフォルト |
| --------------------- | ----------------------- | -------------------------------------------------------- | --- | ----- |
| [`value`](#value)     | 切り詰める文字列。               | `string`                                                 | いいえ | —     |
| [`options`](#options) | 対象ロケールを含む、切り詰めの設定オプション。 | `{ locales?: string \| string[] } & CutoffFormatOptions` | はい  | `{}`  |

### `value` [#value]

**型** `string` · **必須**

切り詰める対象の文字列。

### `options` [#options]

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

切り詰め設定:

| Property     | Description                                                         | Type                   | Optional | Default      |
| ------------ | ------------------------------------------------------------------- | ---------------------- | -------- | ------------ |
| `locales`    | 切り詰め記号の選択に使用するロケール。                                                 | `string \| string[]`   | はい       | `en`         |
| `maxChars`   | 表示する最大文字数 (切り詰め記号を含む) 。Undefined は切り詰めなしを意味します。負の値を指定すると末尾から切り出します。 | `number`               | はい       | —            |
| `style`      | 切り詰め記号のスタイル。                                                        | `'ellipsis' \| 'none'` | はい       | `'ellipsis'` |
| `terminator` | ロケールのデフォルト設定より優先されるカスタムの切り詰め記号。                                     | `string`               | はい       | —            |
| `separator`  | 切り詰め記号とテキストの間に挿入するカスタム区切り文字。切り詰め記号がない場合は無視されます。                     | `string`               | はい       | —            |

## 戻り値 [#returns]

**型** `string`

適切なターミネータが適用された切り詰め済みの文字列。

## 例 [#examples]

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

// 基本的な切り捨て（ellipsisはmaxCharsにカウントされます）
console.log(formatCutoff('Hello, world!', {
  locales: 'en-US',
  maxChars: 8,
}));
// 出力: "Hello, …"

// 切り捨て不要
console.log(formatCutoff('Short', {
  locales: 'en-US',
  maxChars: 10,
}));
// 出力: "Short"
```

```typescript
// 負の文字数制限は末尾からスライスする

// 末尾からスライス
console.log(formatCutoff('Hello, world!', {
  locales: 'en-US',
  maxChars: -3,
}));
// 出力: "…d!"

// より大きな負のスライス
console.log(formatCutoff('JavaScript', {
  locales: 'en-US',
  maxChars: -6,
}));
// 出力: "…cript"
```

```typescript
// ロケール固有のターミネーター

// フランス語のフォーマット（省略記号の前にナロー・ノーブレークスペース）
console.log(formatCutoff('Bonjour le monde', {
  locales: 'fr-FR',
  maxChars: 10,
}));
// Output: "Bonjour \u202F…"

// 中国語のフォーマット（二重省略記号、区切り文字なし）
console.log(formatCutoff('你好世界', {
  locales: 'zh-CN',
  maxChars: 3,
}));
// Output: "你……"

// 日本語のフォーマット
console.log(formatCutoff('こんにちは', {
  locales: 'ja-JP',
  maxChars: 4,
}));
// Output: "こん……"
```

```typescript
// カスタムターミネーター

// カスタムターミネーター
console.log(formatCutoff('Long text here', {
  locales: 'en-US',
  maxChars: 10,
  terminator: '...',
}));
// 出力: "Long te..."

// セパレーター付きカスタムターミネーター
console.log(formatCutoff('Another example', {
  locales: 'en-US',
  maxChars: 12,
  terminator: '[more]',
  separator: ' ',
}));
// 出力: "Anoth [more]"

// ターミネーターなし
console.log(formatCutoff('Clean cut', {
  locales: 'en-US',
  maxChars: 5,
  style: 'none',
}));
// 出力: "Clean"
```

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

// UI表示用に切り詰める
function displayText(text: string, maxLength: number, locale = 'en-US') {
  return formatCutoff(text, {
    locales: locale,
    maxChars: maxLength,
  });
}

// 複数ロケールの切り詰め
function truncateByLocale(text: string, locale: string) {
  const limits: Record<string, number> = {
    en: 50,
    de: 45, // ドイツ語の単語は長くなりがち
    zh: 30, // 中国語の文字は情報密度が高い
  };

  return formatCutoff(text, {
    locales: locale,
    maxChars: limits[locale] || 50,
  });
}

console.log(displayText('This is a very long description', 15));
// Output: "This is a very…"

console.log(truncateByLocale('Eine sehr lange deutsche Beschreibung mit vielen Wörtern', 'de'));
// Output: "Eine sehr lange deutsche Beschreibung mit vi…"
```

## メモ [#notes]

* GT class method と異なり、`locales` は省略可能で、デフォルトは `en` です。
* パフォーマンス向上のため、同じロケールとオプションの組み合わせが繰り返される場合、結果は内部的にキャッシュされます。
* 文字数上限の計算には、terminator (および separator) の長さも含まれます。
* カスタム terminator は、ロケール固有のデフォルトより優先されます。
* terminator がない場合、separator は無視されます。