formatCutoff
Standalone function to truncate strings with locale-aware terminators
Overview
The standalone formatCutoff function truncates strings with appropriate locale-specific terminators without requiring a GT instance.
It provides locale-aware text truncation that respects different languages' conventions for ellipsis characters and spacing.
import { formatCutoff } from 'generaltranslation';
const formatted = formatCutoff('Hello, world!', {
locales: 'en-US',
maxChars: 8
});
// Returns: "Hello, w…"Reference
Parameters
| Name | Type | Description |
|---|---|---|
value | string | The string to truncate |
options | CutoffFormatOptions & { locales?: string | string[] } | Truncation configuration |
CutoffFormatOptions
| Name | Type | Description |
|---|---|---|
locales? | string | string[] | Locales for terminator selection |
maxChars? | number | Maximum characters to display. Undefined means no cutoff. Negative values slice from end |
style? | 'ellipsis' | 'none' | Terminator style. Defaults to 'ellipsis' |
terminator? | string | Custom terminator to override locale defaults |
separator? | string | Custom separator between terminator and text |
Returns
string - The truncated string with appropriate terminator applied.
Behavior
Character Limits
- Positive
maxChars: Truncates from start, appends terminator - Negative
maxChars: Slices from end, prepends terminator - Zero
maxChars: Returns empty string - Undefined
maxChars: No truncation applied
Locale-Specific Terminators
Different locales use different ellipsis conventions:
- French:
…with narrow non-breaking space (\u202F) - Chinese/Japanese: Double ellipsis
……with no separator - Default: Single ellipsis
…with no separator
Edge Cases
- If terminator + separator length exceeds
maxChars, returns empty string - Original string shorter than
maxCharsreturns unchanged 'none'style truncates without any terminator
Examples
Basic Usage
import { formatCutoff } from 'generaltranslation';
// Basic truncation
console.log(formatCutoff('Hello, world!', {
locales: 'en-US',
maxChars: 8
}));
// Output: "Hello, w…"
// No truncation needed
console.log(formatCutoff('Short', {
locales: 'en-US',
maxChars: 10
}));
// Output: "Short"Negative Character Limits
// Slice from end
console.log(formatCutoff('Hello, world!', {
locales: 'en-US',
maxChars: -3
}));
// Output: "…ld!"
// Larger negative slice
console.log(formatCutoff('JavaScript', {
locales: 'en-US',
maxChars: -6
}));
// Output: "…Script"Locale-Specific Terminators
// French formatting
console.log(formatCutoff('Bonjour le monde', {
locales: 'fr-FR',
maxChars: 10
}));
// Output: "Bonjour\u202F…" (narrow space before ellipsis)
// Chinese formatting
console.log(formatCutoff('你好世界', {
locales: 'zh-CN',
maxChars: 3
}));
// Output: "你好……"
// Japanese formatting
console.log(formatCutoff('こんにちは', {
locales: 'ja-JP',
maxChars: 4
}));
// Output: "こん……"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"Utility Functions
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 = {
'en': 50,
'de': 45, // German words tend to be longer
'zh': 30, // Chinese characters are more dense
};
return formatCutoff(text, {
locales: locale,
maxChars: limits[locale] || 50
});
}
console.log(displayText('This is a very long description', 15));
// Output: "This is a ve…"
console.log(truncateByLocale('Eine sehr lange deutsche Beschreibung', 'de'));
// Output: "Eine sehr lange deutsche Besch…"Notes
- Unlike the GT class method, the
localesparameter is optional and defaults to'en' - Results are cached internally for performance with repeated locale/options combinations
- Terminator length is accounted for in character limit calculations
- Custom terminators override locale-specific defaults
- Separators are ignored when no terminator is present
Next Steps
- Use GT class
formatCutofffor instance-based usage - Check out other formatting functions like
formatMessage - See
formatNumfor number formatting
How is this guide?