# generaltranslation: General Translation Core SDK: formatCutoff
URL: https://generaltranslation.com/ja/docs/core/functions/formatting/format-cutoff.mdx
---
title: formatCutoff
description: ロケールに応じた終端文字を使って文字列を切り詰める単体関数
---

## 概要

スタンドアロンの`formatCutoff`関数は、GTインスタンスがなくても、ロケールごとに適切な終端記号を使って文字列を切り詰めます。
この関数は、三点リーダーや空白の扱いに関する言語ごとの慣習を踏まえた、ロケール対応のテキスト切り詰め機能を提供します。

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

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


## リファレンス

### パラメータ

| Name      | Type                                                     | Description |
| --------- | -------------------------------------------------------- | ----------- |
| `value`   | `string`                                                 | 切り詰める対象の文字列 |
| `options` | `CutoffFormatOptions & { locales?: string \| string[] }` | 切り詰めの設定     |

### CutoffFormatOptions

| Name          | Type                   | Description                                           |
| ------------- | ---------------------- | ----------------------------------------------------- |
| `locales?`    | `string \| string[]`   | 終端文字列の選択に使用するロケール                                     |
| `maxChars?`   | `number`               | 表示する最大文字数。Undefined は切り詰めなしを意味します。負の値を指定すると末尾から切り取ります |
| `style?`      | `'ellipsis' \| 'none'` | 終端文字列のスタイル。デフォルトは `'ellipsis'` です                     |
| `terminator?` | `string`               | ロケールのデフォルトを上書きするカスタム終端文字列                             |
| `separator?`  | `string`               | 終端文字列とテキストの間に挿入するカスタム区切り文字                            |

### 戻り値

`string` - 適切な終端文字列が付いた切り詰め後の文字列。

***

## 挙動

### 文字数制限

* **正の `maxChars`**: 先頭側を残して切り詰め、末尾に終端文字列を追加
* **負の `maxChars`**: 末尾側を残して切り詰め、先頭に終端文字列を追加
* **ゼロの `maxChars`**: 空文字列を返す
* **未定義の `maxChars`**: 切り詰めは行われない

### ロケールごとの終端文字列

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

* **French**: 細いノーブレークスペース (`\u202F`) を伴う `…`
* **Chinese/Japanese**: 区切りなしの二重省略記号 `……`
* **Default**: 区切りなしの単一省略記号 `…`

### エッジケース

* terminator と separator の合計長が `maxChars` を超える場合は、空文字列を返します
* 元の文字列が `maxChars` より短い場合は、そのまま返します
* `'none'` スタイルでは、terminator を付けずに切り詰めます

***

## 例

### 基本的な使い方

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

// 基本的な切り詰め
console.log(formatCutoff('Hello, world!', {
  locales: 'en-US',
  maxChars: 8
}));
// 出力: "Hello, w…"

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


### マイナスの文字数上限

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

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


### ロケールごとの終端文字列

```typescript
// フランス語のフォーマット
console.log(formatCutoff('Bonjour le monde', {
  locales: 'fr-FR',
  maxChars: 10
}));
// 出力: "Bonjour\u202F…" (省略記号の前にナロースペース)

// 中国語のフォーマット
console.log(formatCutoff('你好世界', {
  locales: 'zh-CN',
  maxChars: 3
}));
// 出力: "你好……"

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


### 独自の終端子

```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 = {
    '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));
// 出力: "This is a ve…"

console.log(truncateByLocale('Eine sehr lange deutsche Beschreibung', 'de'));
// 出力: "Eine sehr lange deutsche Besch…"
```

***


## 注意事項

* GT クラスのメソッドとは異なり、`locales` パラメータは省略可能で、デフォルトは `'en'` です
* パフォーマンス向上のため、同じロケールとオプションの組み合わせでは、結果が内部的にキャッシュされます
* 終端文字列の長さは文字数制限の計算に含まれます
* カスタムの終端文字列は、ロケール固有のデフォルト値を上書きします
* 終端文字列がない場合、区切り文字は無視されます

## 次のステップ

* インスタンスベースで使用する場合は、GT クラスの [`formatCutoff`](/docs/core/class/methods/formatting/format-cutoff) を使用してください
* [`formatMessage`](/docs/core/functions/formatting/format-message) など、ほかの書式設定関数も確認してください
* 数値の書式設定については [`formatNum`](/docs/core/functions/formatting/format-num) を参照してください