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(): stringReturns: string - Current global locale name
Set Global Locale
locale(name: string): stringParameters:
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 localeBest 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
- .locale() - Instance locale method
- registerLocale() - Register locales
- Internationalization - Full i18n guide
.locale()
Learn how to get or set the locale for individual date instances using the immutable .locale() method. Switch between languages temporarily, create multi-language displays, preserve locale through operations, and implement conditional locale formatting with comprehensive chaining examples.
registerLocale()
Learn how to register locale configurations using registerLocale() for built-in and custom locales. Master application initialization, lazy loading locales, dynamic registration, creating custom locale configurations with months, weekdays, ordinal functions, and meridiem formatters with comprehensive examples and best practices.