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

title: formatCutoff
description: ロケールに応じた切り詰め文字と terminator を使ってテキストを切り詰めます。formatCutoff の API リファレンス。

---

[GT](/docs/platform/core/reference/gt-class/constructor) インスタンスで、対象ロケールに適した ellipsis 文字や空白を適用しながら、ロケールに応じた terminator を使って string を切り詰めます。General Translation ではこれを、途中で省略されたことの示し方に関する各言語の慣習に沿って UI テキストを切り詰めるために使用します。

## 概要 [#overview]

[`GT`](/docs/platform/core/reference/gt-class/constructor) インスタンスで `formatCutoff` を呼び出し、切り詰める文字列と `maxChars` を指定したオプションオブジェクトを渡します。戻り値は、terminator が適用された切り詰め後の文字列です。

```typescript
const gt = new GT({ sourceLocale: 'en', targetLocale: 'fr-FR' });

const formatted = gt.formatCutoff('Hello, world!', {
  maxChars: 8,
});
// "Hello,\u202F…" (フランス語では省略記号の前にナロー・ノーブレークスペースが入る)
```

シグネチャ:

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

*注: `formatCutoff` はローカルで実行されるため、APIキーは不要です。デフォルトではインスタンスの対象ロケールを使用し、対象ロケールがない場合はソースロケール、それもない場合はライブラリのデフォルト (`en`) が使用されます。これを上書きするには `locales` を渡してください。`GT` インスタンスを使わずにフォーマットする場合は、スタンドアロンの [`formatCutoff`](/docs/platform/core/reference/utility-functions/formatting/format-cutoff) を参照してください。*

*注: `terminator` と区切り文字は `maxChars` に含まれます。以下の出力例は現在のライブラリの挙動を反映しており、`terminator` を文字数に含めていなかった元ドキュメント中のいくつかの例 (たとえば `maxChars: 8` の場合、`"Hello, w…"` ではなく `"Hello, …"` になる) を修正しています。*

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

### ロケールの決定

* デフォルトではインスタンスの対象ロケールを使用し、見つからない場合はソースロケール、さらにライブラリのデフォルト (`en`) へとフォールバックします。
* 明示的に `locales` オプションを指定して上書きできます。

### 文字数制限の処理

* **正の `maxChars`:** 先頭側を残して切り詰め、末尾に terminator を追加します。
* **負の `maxChars`:** 末尾側から (`.slice()` と同じ挙動で) 切り出し、先頭に terminator を追加します。
* **ゼロの `maxChars`:** 空文字列を返します。
* **未定義の `maxChars`:** 切り詰めは行われず、元の文字列を返します。
* 切り詰めた結果が空文字列になる場合は、terminator は追加されません。

### ロケール固有の挙動

このメソッドは、言語に応じて適切な terminator を自動的に選択します。

* **French (`fr`):** 狭いノーブレークスペース (`\u202F`) 付きの `…`
* **Chinese (`zh`):** 区切りなしの二重省略記号 `……`
* **Japanese (`ja`):** 区切りなしの二重省略記号 `……`
* **Default:** 区切りなしの単一省略記号 `…`

## パラメータ [#parameters]

| パラメータ                 | 説明        | 型        | 任意  | デフォルト |
| --------------------- | --------- | -------- | --- | ----- |
| [`value`](#value)     | 切り詰める文字列。 | `string` | いいえ | —     |
| [`options`](#options) | 切り詰めの設定。  | `object` | はい  | —     |

### `value` [#value]

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

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

### `options` [#options]

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

切り詰め設定:

| Name         | Description                                             | Type                   | Optional | Default             |
| ------------ | ------------------------------------------------------- | ---------------------- | -------- | ------------------- |
| `locales`    | terminator の選択に使用するロケール (インスタンスのデフォルト設定を上書き) 。               | `string \| string[]`   | はい       | インスタンスのレンダリング時のロケール |
| `maxChars`   | 表示する最大文字数。未定義は切り詰めなしを意味します。負の値は末尾から切り出し、`0` は空文字列を返します。 | `number`               | はい       | —                   |
| `style`      | terminator のスタイル。                                            | `'ellipsis' \| 'none'` | はい       | `'ellipsis'`        |
| `terminator` | ロケールのデフォルトを上書きするカスタムの terminator。                            | `string`               | はい       | —                   |
| `separator`  | terminator とテキストの間に入れるカスタム区切り文字。terminator が指定されていない場合は無視されます。    | `string`               | はい       | —                   |

`CutoffFormatOptions` 型:

```typescript
interface CutoffFormatOptions {
  maxChars?: number;
  style?: 'ellipsis' | 'none';
  terminator?: string;
  separator?: string;
}
```

## 戻り値 [#returns]

**型** `string`

ロケールの慣習に従って適切な terminator を適用した、切り詰め後の文字列です。

## 例 [#examples]

```typescript
// インスタンスのロケールを使った基本的な使い方
const gt = new GT({ targetLocale: 'en-US' });

const truncated = gt.formatCutoff('Hello, world!', {
  maxChars: 8,
});
console.log(truncated); // "Hello, …"
```

```typescript
// ロケールの上書き
const gt = new GT({ targetLocale: 'en-US' });

const french = gt.formatCutoff('Bonjour le monde', {
  locales: 'fr-FR',
  maxChars: 10,
});
console.log(french); // "Bonjour \u202F…"
```

```typescript
// 負の文字数制限
const gt = new GT({ targetLocale: 'en-US' });

// 末尾からスライス
const fromEnd = gt.formatCutoff('JavaScript Framework', {
  maxChars: -9,
});
console.log(fromEnd); // "…ramework"

// より大きな負のスライス
const moreFromEnd = gt.formatCutoff('Hello, world!', {
  maxChars: -3,
});
console.log(moreFromEnd); // "…d!"
```

```typescript
// カスタムスタイルオプション
const gt = new GT({ targetLocale: 'en-US' });

// カスタムterminator
const custom = gt.formatCutoff('Long description text', {
  maxChars: 12,
  terminator: '...',
});
console.log(custom); // "Long desc..."

// 区切り文字付きカスタムterminator
const customSep = gt.formatCutoff('Another example', {
  maxChars: 10,
  terminator: '[...]',
  separator: ' ',
});
console.log(customSep); // "Anot [...]"

// terminatorなし
const none = gt.formatCutoff('Clean cut text', {
  maxChars: 5,
  style: 'none',
});
console.log(none); // "Clean"
```

```typescript
// 多言語アプリケーション
class UserInterface {
  private gt: GT;

  constructor(locale: string) {
    this.gt = new GT({ targetLocale: locale });
  }

  truncateTitle(title: string, maxLength = 20): string {
    return this.gt.formatCutoff(title, { maxChars: maxLength });
  }

  truncateDescription(description: string): string {
    return this.gt.formatCutoff(description, { maxChars: 100 });
  }
}

const englishUI = new UserInterface('en-US');
const chineseUI = new UserInterface('zh-CN');

console.log(englishUI.truncateTitle('Very Long English Title Here', 15));
// 出力: "Very Long Engl…"

console.log(chineseUI.truncateTitle('很长的中文标题在这里', 8));
// 出力: "很长的中文标……"
```

```typescript
// 動的ロケール処理
const gt = new GT({ sourceLocale: 'en', targetLocale: 'en' });

function adaptiveText(text: string, userLocale: string, context: 'title' | 'body') {
  const limits = {
    title: { en: 50, fr: 45, de: 40, zh: 25 },
    body: { en: 200, fr: 180, de: 160, zh: 100 },
  };

  const maxChars = limits[context][userLocale] || limits[context]['en'];

  return gt.formatCutoff(text, {
    locales: userLocale,
    maxChars,
  });
}

const userPrefs = [
  { locale: 'fr-FR', text: 'Une très longue description française' },
  { locale: 'zh-CN', text: '这是一个非常长的中文描述文本' },
  { locale: 'de-DE', text: 'Eine sehr lange deutsche Beschreibung' },
];

userPrefs.forEach(({ locale, text }) => {
  console.log(`${locale}: ${adaptiveText(text, locale, 'title')}`);
});
```

## メモ [#notes]

* このメソッドは、自動的なロケール検出に GT インスタンスの対象ロケールを使用し、見つからない場合はソースロケール、次にライブラリのデフォルト (`en`) へフォールバックします。
* 文字数上限の計算には、terminator と区切り文字の長さも含まれます。
* terminator と区切り文字の長さの合計が `maxChars` を超える場合、このメソッドは空の文字列を返します。
* カスタムの terminator は、ロケール固有のデフォルトを完全に上書きします。
* パフォーマンスは、formatter インスタンスの内部キャッシュによって最適化されています。