fdu logo@pyyupsk/fdu - Faster Date-Time Utility
API ReferenceLocale

locale()

Master the global locale() function to set the default language for all date instances. Learn how to switch locales, build multi-language applications, detect browser language preferences, manage user locale settings, and implement temporary locale changes with best practices for internationalized applications.

Gets or sets the global locale used by default for all new date instances.

Syntax

Get Global Locale

locale(): string

Returns: string - Current global locale name

Set Global Locale

locale(name: string): string

Parameters:

  • name: string - Locale identifier to set as global

Returns: string - The new global locale name

Examples

Get Current Global Locale

import { locale } from "@pyyupsk/fdu";

console.log(locale()); // 'en' (default)

Set Global Locale

import { fdu, locale } from "@pyyupsk/fdu";

// Set global locale to Spanish
locale("es");

// All new instances use Spanish
const date = fdu("2024-01-15");
date.format("MMMM"); // 'enero'

Change Global Locale

import { fdu, locale } from "@pyyupsk/fdu";

// Initially English
locale(); // 'en'

const date1 = fdu("2024-01-15");
date1.format("MMMM"); // 'January'

// Change to Spanish
locale("es");

const date2 = fdu("2024-01-15");
date2.format("MMMM"); // 'enero'

// Previous instances unchanged
date1.format("MMMM"); // 'January' (still English)

Common Patterns

Multi-language Application

import { locale, registerLocale } from "@pyyupsk/fdu";
import { es } from "@pyyupsk/fdu/locale/es";
import { fr } from "@pyyupsk/fdu/locale/fr";

// Register all supported locales at startup
registerLocale("es", es);
registerLocale("fr", fr);

// Switch based on user preference
function setUserLanguage(lang: string) {
  locale(lang);
}

// User selects Spanish
setUserLanguage("es");

// All new dates use Spanish
const date = fdu();
date.format("dddd, MMMM D"); // 'lunes, enero 15'

Language Switcher

function switchLanguage(newLocale: string) {
  const previousLocale = locale();
  locale(newLocale);

  console.log(`Switched from ${previousLocale} to ${newLocale}`);
  return previousLocale;
}

switchLanguage("es"); // 'Switched from en to es'

Application Initialization

// app-init.ts
import { locale, registerLocale } from "@pyyupsk/fdu";
import { es } from "@pyyupsk/fdu/locale/es";
import { fr } from "@pyyupsk/fdu/locale/fr";
import { de } from "@pyyupsk/fdu/locale/de";

export function initializeLocales(userLocale: string = "en") {
  // Register all locales
  registerLocale("es", es);
  registerLocale("fr", fr);
  registerLocale("de", de);

  // Set user's preferred locale
  locale(userLocale);
}

// In your app entry point
initializeLocales(getUserPreferredLanguage());

Browser Language Detection

import { locale, registerLocale } from "@pyyupsk/fdu";
import { es } from "@pyyupsk/fdu/locale/es";
import { fr } from "@pyyupsk/fdu/locale/fr";

// Register locales
registerLocale("es", es);
registerLocale("fr", fr);

// Detect browser language
const browserLang = navigator.language.split("-")[0]; // 'en', 'es', 'fr', etc.

// Set global locale based on browser
if (["es", "fr", "de"].includes(browserLang)) {
  locale(browserLang);
}

Temporary Locale Change

function withLocale<T>(localeName: string, fn: () => T): T {
  const previousLocale = locale();
  locale(localeName);

  try {
    return fn();
  } finally {
    locale(previousLocale);
  }
}

// Usage
const spanishDate = withLocale("es", () => {
  return fdu("2024-01-15").format("MMMM D, YYYY");
});
// 'enero 15, 2024'

// Global locale restored after function
locale(); // back to previous locale

Best Practices

Set Early in Application

// ✅ Good - set at application start
// main.ts
import { locale } from "@pyyupsk/fdu";

locale("es"); // Set once at startup

// ❌ Avoid - setting repeatedly
function formatDate(date: FduInstance) {
  locale("es"); // Don't do this on every call
  return date.format("YYYY-MM-DD");
}

Handle Missing Locales

import { locale, registerLocale } from "@pyyupsk/fdu";
import { es } from "@pyyupsk/fdu/locale/es";

function setAppLocale(localeName: string) {
  // Ensure locale is registered
  if (localeName === "es") {
    registerLocale("es", es);
  }

  locale(localeName);
}

If you try to use an unregistered locale, @pyyupsk/fdu will log a warning and fall back to English ('en').

See Also

On this page