Mastering Internationalization with Intl in TypeScript

Table of Contents#

1. Fundamental Concepts of Intl in TypeScript
2. Usage Methods
   • Date and Time Formatting
   • Number Formatting
   • String Comparison
3. Common Practices
   • Handling Multiple Locales
   • Using Plural Rules
4. Best Practices
   • Lazy Loading Translations
   • Error Handling
5. Conclusion
6. References

Fundamental Concepts of Intl in TypeScript#

The Intl object in JavaScript is a built-in object that provides language-sensitive string comparison, number formatting, and date and time formatting. In TypeScript, we can use these features while leveraging static typing to catch errors early.

The main components of the Intl API include:

• Intl.DateTimeFormat: Used for formatting dates and times according to the locale.
• Intl.NumberFormat: Used for formatting numbers, including currency, percentages, etc., based on the locale.
• Intl.Collator: Used for comparing strings according to the locale.

Usage Methods#

Date and Time Formatting#

The Intl.DateTimeFormat object allows us to format dates and times in a locale-specific way.

// Format a date in the user's locale
const date = new Date();
const formatter = new Intl.DateTimeFormat(undefined, {
    year: 'numeric',
    month: 'long',
    day: 'numeric'
});
const formattedDate = formatter.format(date);
console.log(formattedDate);

In the above example, the undefined argument for the locale means that it will use the user's default locale. We can also specify a particular locale, such as 'fr - FR' for French.

Number Formatting#

The Intl.NumberFormat object is used to format numbers according to the locale.

// Format a number as currency in the US locale
const amount = 1234.56;
const currencyFormatter = new Intl.NumberFormat('en - US', {
    style: 'currency',
    currency: 'USD'
});
const formattedAmount = currencyFormatter.format(amount);
console.log(formattedAmount);

String Comparison#

The Intl.Collator object is used to compare strings in a locale-sensitive way.

const strings = ['réservé', 'Premier', 'Cliché', 'communiqué'];
const collator = new Intl.Collator(undefined, { sensitivity: 'base' });
strings.sort(collator.compare);
console.log(strings);

Common Practices#

Handling Multiple Locales#

In a real-world application, we may need to support multiple locales. One common approach is to detect the user's locale and then use the appropriate formatter.

const supportedLocales = ['en - US', 'fr - FR'];
const userLocale = navigator.language;
const localeToUse = supportedLocales.find(locale => locale.startsWith(userLocale.split('-')[0])) || 'en - US';
 
const date = new Date();
const dateFormatter = new Intl.DateTimeFormat(localeToUse, {
    year: 'numeric',
    month: 'long',
    day: 'numeric'
});
const formattedDate = dateFormatter.format(date);
console.log(formattedDate);

Using Plural Rules#

The Intl.PluralRules object can be used to handle pluralization in different languages.

const pluralRules = new Intl.PluralRules('en - US');
const count = 2;
const pluralForm = pluralRules.select(count);
if (pluralForm === 'one') {
    console.log('You have 1 item');
} else {
    console.log(`You have ${count} items`);
}

Best Practices#

Lazy Loading Translations#

In large applications, loading all translations at once can be a performance bottleneck. We can use lazy loading to load translations only when they are needed.

// Assume we have a function to load translations asynchronously
async function loadTranslations(locale: string) {
    const response = await fetch(`/translations/${locale}.json`);
    return await response.json();
}
 
async function displayTranslation(key: string, locale: string) {
    const translations = await loadTranslations(locale);
    return translations[key];
}

Error Handling#

When working with the Intl API, it's important to handle errors gracefully. For example, if a locale is not supported, the API may throw an error.

try {
    const formatter = new Intl.DateTimeFormat('invalid - locale', {
        year: 'numeric',
        month: 'long',
        day: 'numeric'
    });
    const date = new Date();
    const formattedDate = formatter.format(date);
    console.log(formattedDate);
} catch (error) {
    console.error('Error formatting date:', error);
    // Fallback to a default locale
    const defaultFormatter = new Intl.DateTimeFormat('en - US', {
        year: 'numeric',
        month: 'long',
        day: 'numeric'
    });
    const defaultFormattedDate = defaultFormatter.format(new Date());
    console.log(defaultFormattedDate);
}

Conclusion#

The Intl API in TypeScript provides a powerful set of tools for internationalizing applications. By understanding the fundamental concepts, usage methods, common practices, and best practices, developers can build applications that are accessible and user-friendly for a global audience. Whether it's formatting dates, numbers, or handling string comparisons, the Intl API simplifies the process of adapting applications to different languages and cultures.

References#

• MDN Web Docs - Intl
• TypeScript Documentation