# General Translation Platform: formatCutoff
URL: https://generaltranslation.com/en-GB/docs/platform/core/reference/utility-functions/formatting/format-cutoff.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Truncate text with locale-aware cut-off characters without a GT instance. API reference for formatCutoff.

[`formatCutoff`](/docs/platform/core/reference/gt-class-methods/formatting/format-cutoff) is a standalone utility function from General Translation's Core library that truncates strings with locale-aware terminators. It respects each language's conventions for ellipsis characters and spacing.

## Overview [#overview]

Import `formatCutoff` directly from `generaltranslation` and call it with a string and an options object. It does not require an API key or a [GT](/docs/platform/core/reference/gt-class/constructor) instance. For instance-based truncation that inherits the instance locale, use the [`formatCutoff`](/docs/platform/core/reference/gt-class-methods/formatting/format-cutoff) method on a [`GT`](/docs/platform/core/reference/gt-class/constructor) instance instead.

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

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

Signature:

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

## How it works [#how-it-works]

The terminator and separator count towards `maxChars`. That is, the returned string (including the terminator) is at most `maxChars` characters long.

### Character limits

* **Positive `maxChars`:** truncates from the start and appends the terminator.
* **Negative `maxChars`:** slices from the end (following `Array.prototype.slice` behaviour) and prepends the terminator.
* **Zero `maxChars`:** returns an empty string.
* **Undefined `maxChars`:** no truncation is applied.

### Locale-specific terminators

Different locales use different ellipsis conventions:

* **French:** `…` with a narrow non-breaking space (`\u202F`) separator.
* **Chinese/Japanese:** double ellipsis `……` with no separator.
* **Default:** single ellipsis `…` with no separator.

### Edge cases

* If the terminator plus separator length exceeds `maxChars`, the result is an empty string.
* A string shorter than `maxChars` is returned unchanged.
* The `'none'` style truncates without any terminator.
* When `locales` is omitted, it falls back to the library default locale, `en`.

## Parameters [#parameters]

| Parameter             | Description                                               | Type                                                     | Optional | Default |
| --------------------- | --------------------------------------------------------- | -------------------------------------------------------- | -------- | ------- |
| [`value`](#value)     | The string to truncate.                                   | `string`                                                 | No       | —       |
| [`options`](#options) | Truncation configuration, including the target locale(s). | `{ locales?: string \| string[] } & CutoffFormatOptions` | Yes      | `{}`    |

### `value` [#value]

**Type** `string` · **Required**

The string to truncate.

### `options` [#options]

**Type** `{ locales?: string | string[] } & CutoffFormatOptions` · **Optional** · **Default** `{}`

Truncation configuration:

| Property     | Description                                                                                                                        | Type                   | Optional | Default      |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | -------- | ------------ |
| `locales`    | Locale(s) used to select the terminator.                                                                                           | `string \| string[]`   | Yes      | `en`         |
| `maxChars`   | Maximum number of characters to display (including the terminator). Undefined means no cutoff; negative values slice from the end. | `number`               | Yes      | —            |
| `style`      | Terminator style.                                                                                                                  | `'ellipsis' \| 'none'` | Yes      | `'ellipsis'` |
| `terminator` | Custom terminator that overrides locale defaults.                                                                                  | `string`               | Yes      | —            |
| `separator`  | Custom separator between the terminator and the text. Ignored when there is no terminator.                                         | `string`               | Yes      | —            |

## Returns [#returns]

**Type** `string`

The truncated string with the appropriate terminator applied.

## Examples [#examples]

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

// Basic truncation (the ellipsis counts towards maxChars)
console.log(formatCutoff('Hello, world!', {
  locales: 'en-US',
  maxChars: 8,
}));
// Output: "Hello, …"

// No truncation needed
console.log(formatCutoff('Short', {
  locales: 'en-US',
  maxChars: 10,
}));
// Output: "Short"
```

```typescript
// Negative character limits slice from the end

// Slice from end
console.log(formatCutoff('Hello, world!', {
  locales: 'en-US',
  maxChars: -3,
}));
// Output: "…d!"

// Larger negative slice
console.log(formatCutoff('JavaScript', {
  locales: 'en-US',
  maxChars: -6,
}));
// Output: "…cript"
```

```typescript
// Locale-specific terminators

// French formatting (narrow non-breaking space before the ellipsis)
console.log(formatCutoff('Bonjour le monde', {
  locales: 'fr-FR',
  maxChars: 10,
}));
// Output: "Bonjour \u202F…"

// Chinese formatting (double ellipsis, no separator)
console.log(formatCutoff('你好世界', {
  locales: 'zh-CN',
  maxChars: 3,
}));
// Output: "你……"

// Japanese formatting
console.log(formatCutoff('こんにちは', {
  locales: 'ja-JP',
  maxChars: 4,
}));
// Output: "こん……"
```

```typescript
// Custom terminators

// Custom terminator
console.log(formatCutoff('Long text here', {
  locales: 'en-US',
  maxChars: 10,
  terminator: '...',
}));
// Output: "Long te..."

// Custom terminator with separator
console.log(formatCutoff('Another example', {
  locales: 'en-US',
  maxChars: 12,
  terminator: '[more]',
  separator: ' ',
}));
// Output: "Anoth [more]"

// No terminator
console.log(formatCutoff('Clean cut', {
  locales: 'en-US',
  maxChars: 5,
  style: 'none',
}));
// Output: "Clean"
```

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

// Truncate for UI display
function displayText(text: string, maxLength: number, locale = 'en-US') {
  return formatCutoff(text, {
    locales: locale,
    maxChars: maxLength,
  });
}

// Multi-locale truncation
function truncateByLocale(text: string, locale: string) {
  const limits: Record<string, number> = {
    en: 50,
    de: 45, // German words tend to be longer
    zh: 30, // Chinese characters are denser
  };

  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 [#notes]

* Unlike the GT class method, `locales` is optional and defaults to `en`.
* Results are cached internally for performance with repeated locale/options combinations.
* The terminator (and separator) length is accounted for in the character limit calculation.
* Custom terminators override locale-specific defaults.
* Separators are ignored when no terminator is present.

## Sitemap

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