@gasket/intl

@gasket/intl

Provides internationalization managers for translation files and locale handling.

Installation

npm i @gasket/intl @gasket/plugin-intl

See @gasket/plugin-intl for more information on how to configure the plugin.

Usage

With a intl.js built by @gasket/plugin-intl, you can use the IntlManager to get messages for locales.

Example messages for a Locale

import intlManager from '../path/to/intl.js';

// Get a locale handler for a specific locale
const localeHandler = intlManager.handleLocale('en-US');

// Get all loaded messages for the locale
const messages = localeHandler.getAllMessages();

Example resolving a supported locale

The IntlManager can also be used to resolve locale based on the supported locales that have been configured for @gasket/plugin-intl.

import intlManager from '../path/to/intl.js';

// Resolve a locale to a supported locale
const resolvedLocale = intlManager.resolveLocale('fr-CA');
// If fr-CA is not supported but fr is, resolvedLocale will be 'fr'
// If neither is supported, it will fall back to the default locale

To list all supported locales, you can use:

import intlManager from '../path/to/intl.js';

// Get all supported locales
const supportedLocales = intlManager.locales;

Advanced Usage

While the above examples cover the most common use cases, the @gasket/intl package also provides advanced features for managing locale files and their loading status. These are useful for scenarios where the React components from @gasket/react-intl are not available or when you need to manage locale files directly.

Loading Multiple Locale Files

import intlManager from '../path/to/intl.js';

const localeHandler = intlManager.handleLocale('en-US');

// Load multiple locale files
await localeHandler.load(
  'locales/common',
  'locales/homepage',
  'locales/user-profile'
);

// Get all loaded messages
const messages = localeHandler.getAllMessages();

Checking Loading Status

import intlManager from '../path/to/intl.js';
import { LocaleFileStatus } from '@gasket/intl';

const localeHandler = intlManager.handleLocale('en-US');

// Start loading a locale file
localeHandler.load('locales/common');

// Check the status
const status = localeHandler.getStatus('locales/common');

if (status === LocaleFileStatus.loading) {
  console.log('Locale file is still loading...');
} else if (status === LocaleFileStatus.loaded) {
  console.log('Locale file has been loaded successfully!');
} else if (status === LocaleFileStatus.error) {
  console.error('Failed to load locale file');
}

Using Static Locale File Paths

The staticLocaleFilePaths configuration in @gasket/plugin-intl allows you to specify which locale files should be preloaded for server-side rendering (SSR) and available immediately when the app starts.

Configuration

Configure staticLocaleFilePaths in your gasket.js:

// gasket.js
export default makeGasket({
  intl: {
    locales: ['en-US', 'fr-FR'],
    staticLocaleFilePaths: [
      'locales/common',
      'locales/navigation', 
      'locales/errors'
    ]
  }
});

Server-Side Rendering

import intlManager from '../path/to/intl.js';

const localeHandler = intlManager.handleLocale('en-US');

// Load all configured static locale files
await localeHandler.loadStatics();

// Or load specific static files
await localeHandler.loadStatics('locales/common', 'locales/navigation');

// Get the static messages register for SSR
const staticsRegister = localeHandler.getStaticsRegister();

// Pass this to the client for hydration

License

MIT