Universal Name Formatter

A locale-aware name formatting utility that handles international names with proper linguistic rules. Supports 17+ languages including Spanish, French, Italian, German, Dutch, Irish, and Scottish names.

Features

• Universal Linguistic Rules - Handles complex name patterns across languages
• Locale-Specific Formatting - French articles vs Italian surnames (d'Aubigny vs D'Amico)
• Zero Dependencies - Lightweight (11.5 kB compressed)
• TypeScript Support - Full type safety
• Legacy Compatible - CommonJS + ESM support

Installation

npm install universal-name-formatter

Quick Start

import { formatName } from 'universal-name-formatter';

// Universal formatting
formatName('josé maría de la cruz');         // "José María de la Cruz"
formatName('jean-claude van damme');         // "Jean-Claude van Damme"
formatName('leonardo da vinci');             // "Leonardo da Vinci"

// Locale-specific precision
formatName('marie d\'aubigny', { locale: 'fr' });  // "Marie d'Aubigny"
formatName('giovanni d\'amico', { locale: 'it' }); // "Giovanni D'Amico"

Supported Languages

| Language | Example | Output | |----------|---------|--------| | Spanish | josé maría de la cruz | José María de la Cruz | | French | jean-claude de la fontaine | Jean-Claude de la Fontaine | | German | hans von neumann | Hans von Neumann | | Dutch | jan van der waals | Jan van der Waals | | Italian | leonardo da vinci | Leonardo da Vinci | | Irish | patrick o'malley | Patrick O'Malley | | Scottish | donald mcdonald | Donald McDonald |

Plus: Catalan, Swedish, Norwegian, Danish, Welsh, Galician, Polish, Czech, Romanian

API

formatName(name, options?)

Parameters:

• name (string): The name to format
• options (object, optional):
  • locale (string): Language code (e.g., 'fr', 'it', 'es')
  • trim (boolean): Trim whitespace (default: true)
  • normalizeSpaces (boolean): Normalize spaces (default: true)

Returns: Formatted name string

Locale Examples

// French - keeps articles lowercase
formatName("marie d'aubigny", { locale: "fr" });     // "Marie d'Aubigny"

// Italian - capitalizes surnames  
formatName("giovanni d'amico", { locale: "it" });    // "Giovanni D'Amico"

// Spanish - handles prepositions
formatName("maría de la cruz", { locale: "es" });    // "María de la Cruz"

// German - von/zu prefixes
formatName("ludwig van beethoven", { locale: "de" }); // "Ludwig van Beethoven"

Advanced Usage

// Handle mixed origins
formatName('maría von habsburg');        // "María von Habsburg"
formatName('jean-claude mcdonald');      // "Jean-Claude McDonald"

// Custom options
formatName('  marie d\'aubigny  ', {
  locale: 'fr',
  trim: true,
  normalizeSpaces: true
});

TypeScript

import { formatName, type NameFormatterOptions } from 'universal-name-formatter';

const options: NameFormatterOptions = {
  locale: 'fr',
  trim: true
};

const formatted: string = formatName('marie d\'aubigny', options);

License

MIT - see LICENSE file for details.