# General Translation Platform: formatCutoff
URL: https://generaltranslation.com/ru/docs/platform/core/reference/utility-functions/formatting/format-cutoff.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Обрезает текст с использованием локализованных символов усечения без экземпляра GT. Справочник API для formatCutoff.

[`formatCutoff`](/docs/platform/core/reference/gt-class-methods/formatting/format-cutoff) — это автономная служебная функция из основной библиотеки General Translation, которая обрезает строки с помощью локализованных маркеров усечения. Она учитывает принятые в каждом языке правила использования многоточия и пробелов.

## Обзор [#overview]

Импортируйте `formatCutoff` напрямую из `generaltranslation` и вызовите его, передав строку и объект параметров. Для этого не нужны API-ключ или экземпляр [GT](/docs/platform/core/reference/gt-class/constructor). Если вам нужно усечение через экземпляр с наследованием его локали, используйте вместо этого метод [`formatCutoff`](/docs/platform/core/reference/gt-class-methods/formatting/format-cutoff) у экземпляра [`GT`](/docs/platform/core/reference/gt-class/constructor).

```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]

Маркер усечения и разделитель учитываются в `maxChars`. То есть длина возвращаемой строки (включая маркер усечения) не превышает `maxChars` символов.

### Ограничения по числу символов

* **Положительный `maxChars`:** обрезает строку с начала и добавляет в конец маркер сокращения.
* **Отрицательный `maxChars`:** обрезает строку с конца (в соответствии с поведением `Array.prototype.slice`) и добавляет маркер сокращения в начало.
* **Нулевой `maxChars`:** возвращает пустую строку.
* **Неопределённый `maxChars`:** обрезка не применяется.

### Маркеры усечения, зависящие от локали

В разных локалях многоточие оформляется по-разному:

* **Французский:** `…` с узким неразрывным пробелом (`\u202F`) в качестве разделителя.
* **Китайский/японский:** двойное многоточие `……` без разделителя.
* **По умолчанию:** одно многоточие `…` без разделителя.

### Особые случаи

* Если суммарная длина terminator и separator превышает `maxChars`, результатом будет пустая строка.
* Строка короче `maxChars` возвращается без изменений.
* Стиль `'none'` выполняет усечение без terminator.
* Если `locales` не указан, используется локаль библиотеки по умолчанию — `en`.

## Параметры [#parameters]

| Параметр              | Описание                                      | Тип                                                      | Необязателен | По умолчанию |
| --------------------- | --------------------------------------------- | -------------------------------------------------------- | ------------ | ------------ |
| [`value`](#value)     | Строка, которую нужно обрезать.               | `string`                                                 | Нет          | —            |
| [`options`](#options) | Конфигурация обрезки, включая целевые локали. | `{ locales?: string \| string[] } & CutoffFormatOptions` | Да           | `{}`         |

### `value` [#value]

**Тип** `string` · **Обязательно**

Строка, которую нужно обрезать.

### `options` [#options]

**Тип** `{ locales?: string | string[] } & CutoffFormatOptions` · **Необязательно** · **По умолчанию** `{}`

Конфигурация усечения:

| Свойство     | Описание                                                                                                                                                     | Тип                    | Необязательно | По умолчанию |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- | ------------- | ------------ |
| `locales`    | Локаль(и) для выбора терминатора.                                                                                                                            | `string \| string[]`   | Да            | `en`         |
| `maxChars`   | Максимальное количество отображаемых символов (включая терминатор). `Undefined` означает отсутствие усечения; отрицательные значения обрезают текст с конца. | `number`               | Да            | —            |
| `style`      | Стиль терминатора.                                                                                                                                           | `'ellipsis' \| 'none'` | Да            | `'ellipsis'` |
| `terminator` | Пользовательский терминатор, который переопределяет значения по умолчанию для локали.                                                                        | `string`               | Да            | —            |
| `separator`  | Пользовательский разделитель между терминатором и текстом. Игнорируется, если терминатор отсутствует.                                                        | `string`               | Да            | —            |

## Возвращает [#returns]

**Тип** `string`

Усечённая строка с добавленным соответствующим маркером усечения.

## Примеры [#examples]

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

// Базовое усечение (многоточие учитывается в 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';

// Усечение для отображения в интерфейсе
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, `locales` — необязательный параметр со значением по умолчанию `en`.
* Для повышения производительности результаты кэшируются внутри при повторном использовании одних и тех же комбинаций локалей и параметров.
* При расчёте ограничения по количеству символов учитывается длина terminator (и separator).
* Пользовательские terminator переопределяют значения по умолчанию для конкретной локали.
* Separator игнорируются, если terminator отсутствует.

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.