Utility FunctionsFormatting

formatCutoff

Fonction autonome pour tronquer des chaînes avec des terminateurs adaptés au locale

Aperçu

La fonction autonome formatCutoff tronque les chaînes avec des marqueurs adaptés à chaque locale, sans nécessiter d’instance de GT. Elle effectue une troncature de texte tenant compte de la locale, en respectant les conventions propres à chaque langue pour les points de suspension et les espacements.

import { formatCutoff } from 'generaltranslation';

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

Référence

Paramètres

NomTypeDescription
valuestringChaîne à tronquer
optionsCutoffFormatOptions & { locales?: string | string[] }Configuration de la troncature

CutoffFormatOptions

NameTypeDescription
locales?string | string[]Locales utilisées pour la sélection du terminateur
maxChars?numberNombre maximal de caractères à afficher. Non défini : aucune troncature. Les valeurs négatives découpent à partir de la fin
style?'ellipsis' | 'none'Style du terminateur. Par défaut : 'ellipsis'
terminator?stringTerminateur personnalisé pour remplacer le terminateur par défaut de la locale
separator?stringSéparateur personnalisé entre le terminateur et le texte

Renvoie

string - Chaîne tronquée avec le caractère de terminaison approprié.


Comportement

Limites de caractères

  • maxChars positif : Tronque depuis le début, ajoute le terminateur
  • maxChars négatif : Tronque depuis la fin, préfixe le terminateur
  • maxChars égal à zéro : Renvoie une chaîne vide
  • maxChars non défini : Aucune troncature n’est appliquée

Terminaisons spécifiques à chaque locale

Différentes locales utilisent différentes conventions de points de suspension :

  • Français : avec une espace fine insécable (\u202F)
  • Chinois/Japonais : double point de suspension …… sans espace
  • Par défaut : point de suspension simple sans espace

Cas particuliers

  • Si la longueur combinée du terminateur et du séparateur dépasse maxChars, renvoie une chaîne vide
  • Une chaîne d’origine plus courte que maxChars est renvoyée telle quelle
  • Le style 'none' tronque sans aucun terminateur

Exemples

Utilisation de base

import { formatCutoff } from 'generaltranslation';

// Troncature de base
console.log(formatCutoff('Hello, world!', {
  locales: 'en-US',
  maxChars: 8
}));
// Résultat : "Hello, w…"

// Aucune troncature nécessaire
console.log(formatCutoff('Short', {
  locales: 'en-US', 
  maxChars: 10
}));
// Résultat : "Short"

Limites négatives de caractères

// Découpe depuis la fin
console.log(formatCutoff('Hello, world!', {
  locales: 'en-US',
  maxChars: -3
}));
// Résultat : "…ld!"

// Découpe négative plus large
console.log(formatCutoff('JavaScript', {
  locales: 'en-US',
  maxChars: -6
}));
// Résultat : "…Script"

Terminateurs spécifiques à un locale

// Formatage français
console.log(formatCutoff('Bonjour le monde', {
  locales: 'fr-FR',
  maxChars: 10
}));
// Résultat : "Bonjour\u202F…" (espace fine avant les points de suspension)

// Formatage chinois
console.log(formatCutoff('你好世界', {
  locales: 'zh-CN',
  maxChars: 3
}));
// Résultat : "你好……"

// Formatage japonais  
console.log(formatCutoff('こんにちは', {
  locales: 'ja-JP',
  maxChars: 4
}));
// Résultat : "こん……"

Terminators personnalisés

// Terminateur personnalisé
console.log(formatCutoff('Long text here', {
  locales: 'en-US',
  maxChars: 10,
  terminator: '...'
}));
// Résultat : "Long te..."

// Terminateur personnalisé avec séparateur
console.log(formatCutoff('Another example', {
  locales: 'en-US',
  maxChars: 12,
  terminator: '[more]',
  separator: ' '
}));
// Résultat : "Anoth [more]"

// Sans terminateur
console.log(formatCutoff('Clean cut', {
  locales: 'en-US',
  maxChars: 5,
  style: 'none'
}));
// Résultat : "Clean"

Fonctions utilitaires

import { formatCutoff } from 'generaltranslation';

// Tronquer pour l'affichage de l'interface
function displayText(text: string, maxLength: number, locale = 'en-US') {
  return formatCutoff(text, {
    locales: locale,
    maxChars: maxLength
  });
}

// Troncature multi-locales
function truncateByLocale(text: string, locale: string) {
  const limits = {
    'en': 50,
    'de': 45, // Les mots allemands sont généralement plus longs
    'zh': 30, // Les caractères chinois sont plus compacts
  };
  
  return formatCutoff(text, {
    locales: locale,
    maxChars: limits[locale] || 50
  });
}

console.log(displayText('This is a very long description', 15));
// Résultat : "This is a ve…"

console.log(truncateByLocale('Eine sehr lange deutsche Beschreibung', 'de'));
// Résultat : "Eine sehr lange deutsche Besch…"

Notes

  • Contrairement à la méthode de la classe GT, le paramètre locales est facultatif et a pour valeur par défaut 'en'
  • Les résultats sont mis en cache en interne pour optimiser les performances avec des combinaisons répétées de locale/options
  • La longueur du terminateur est prise en compte dans le calcul de la limite de caractères
  • Les terminateurs personnalisés remplacent les valeurs par défaut propres à chaque locale
  • Les séparateurs sont ignorés lorsqu’aucun terminateur n’est présent

Prochaines étapes

  • Utilisez la GT class formatCutoff pour une utilisation par instance
  • Découvrez d’autres fonctions de formatage comme formatMessage
  • Consultez formatNum pour le formatage des nombres

Comment trouvez-vous ce guide ?