# generaltranslation: General Translation Core SDK: formatCutoff
URL: https://generaltranslation.com/ja/docs/core/class/methods/formatting/format-cutoff.mdx
---
title: formatCutoff
description: GT の formatCutoff メソッドの API リファレンス
---

## 概要

`formatCutoff` メソッドは、ロケールに応じた終端記号を使って文字列を切り詰め、対象ロケールに合わせて適切な省略記号やスペースを適用します。

このメソッドは、途中で切れたテキストの示し方に関する各言語の慣習を踏まえて、UI テキストを切り詰める際に重要です。

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

const formatted = gt.formatCutoff('Hello, world!', {
  maxChars: 8
});
// 戻り値: "Hello, w\u202F…" (フランス語でのナロースペース付き)
```

***


## リファレンス

### パラメータ

<TypeTable
  type={{
  "value": {
    type: 'string',
    optional: false,
  },
  "options?": {
    type: 'object',
    optional: true,
  }
}}
/>

### オプションオブジェクト

| プロパティ        | 型                      | 任意 | 説明                                                    |
| ------------ | ---------------------- | -- | ----------------------------------------------------- |
| `locales`    | `string \| string[]`   | ✓  | 終端記号の選択に使用するロケール (インスタンスのデフォルト設定を上書き)                 |
| `maxChars`   | `number`               | ✓  | 表示する最大文字数。undefined は切り詰めなしを意味します。負の値を指定すると末尾から切り出します |
| `style`      | `'ellipsis' \| 'none'` | ✓  | 終端記号のスタイル。デフォルトは `'ellipsis'`                         |
| `terminator` | `string`               | ✓  | ロケールのデフォルトを上書きするカスタム終端記号                              |
| `separator`  | `string`               | ✓  | 終端記号とテキストの間に挿入するカスタム区切り文字                             |

### CutoffFormatOptions 型

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


### 戻り値

`string` - ロケールの慣例に従い、適切な終端記号を付けた切り詰め後の文字列。

***

## 挙動

### ロケールの決定

* デフォルトでは、インスタンスの`_renderingLocales`を使用します (`sourceLocale`、`targetLocale`、フォールバックを含む) 
* 明示的に`locales`オプションを指定して上書きできます
* 決定に失敗した場合は、ライブラリのデフォルトロケールにフォールバックします

### 字符制限の処理

* **正の `maxChars`**: 先頭から切り詰め、末尾に終端記号を追加
* **負の `maxChars`**: 末尾から切り出し、先頭に終端記号を追加
* **ゼロの `maxChars`**: 空文字列を返す
* **未定義の `maxChars`**: 切り詰めは行われず、元の文字列を返す

### ロケールごとの動作

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

* **フランス語 (`fr`)**: 狭いノーブレークスペース (`\u202F`) を挟んだ `…`
* **中国語 (`zh`)**: 区切りなしの二重省略記号 `……`
* **日本語 (`ja`)**: 区切りなしの二重省略記号 `……`
* **デフォルト**: 区切りなしの単一省略記号 `…`

***

## 例

### インスタンスのロケールを使った基本的な使い方

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

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


### ロケールのオーバーライド

```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); // "…Framework"

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


### カスタムスタイリングのオプション

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

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

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

// 終端記号なし
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')}`);
});
```

***


## 注記

* このメソッドは、ロケールを自動検出するために GT インスタンスの `_renderingLocales` を使用します
* 終端記号と区切り文字の長さは、文字数制限の計算に含まれます
* 終端記号と区切り文字の長さの合計が `maxChars` を超える場合は、空の文字列を返します
* カスタム終端記号を指定すると、ロケール固有のデフォルトは完全に上書きされます
* フォーマッタインスタンスを内部でキャッシュすることで、パフォーマンスを最適化しています

## 次のステップ

* GT インスタンスなしで使用する場合は、単体で使える [`formatCutoff`](/docs/core/functions/formatting/format-cutoff) を使用します
* [`formatMessage`](/docs/core/class/methods/formatting/format-message) でメッセージをフォーマットします
* [`formatNum`](/docs/core/class/methods/formatting/format-num) で数値をフォーマットします
* [ロケールのプロパティ](/docs/core/class/methods/locales/get-locale-properties) について確認します