sveltekit-i18n

The sveltekit-i18n library provides several integration patterns depending on your application's architecture and SEO requirements. Choose the one that matches your needs:

Routing & Architecture

• multi-page (Recommended): The most frequent use-case for applications with multiple routes. Translations are loaded based on locale and routes, preventing duplicate translation loads on both server and client.
• one-page: Best for single-page applications (SPAs). Translations are loaded dynamically according to the current locale.
• single-load: Loads all translations for all language mutations during initialization. Useful only if you require all translations to be immediately available.
• locale-param: A multi-page approach where language is determined by a URL parameter (e.g., https://example.com/?lang=en).

SEO & Adapter Optimization

• locale-router-static: Uses locale-based routing (e.g., /en/about). Optimized for @sveltejs/adapter-static and great for SEO.
• locale-router: Uses locale-based routing. Optimized for non-static adapters like @sveltejs/adapter-node.
• locale-router-advanced: Similar to locale-router but optimized for non-static adapters where default locale routes do not have a language prefix in the path.

Component-Scoped Translations

• component-scoped-csr: Allows scoping translations to specific components. App translations load via SSR, but component translations are loaded via a component promise on the client side (CSR).
• component-scoped-ssr: Uses an exported init method to initialize language mutations within the parent page's load method, delegating props back to the component instance.

The sveltekit-i18n ecosystem is split into three main packages. Choosing the right one depends on whether you want a turnkey solution or maximum control over message interpolation.

1. sveltekit-i18n (The Complete Solution)

Use when: You want the quickest setup and are happy with the default parser syntax.

• Includes: Everything in @sveltekit-i18n/base plus @sveltekit-i18n/parser-default.
• Pros: Sensible defaults, simplified API, and no external dependencies.

2. @sveltekit-i18n/base (The Core Engine)

Use when: You need maximum flexibility or want to use custom parsers.

• Responsibilities: Managing translation state (Svelte stores), loading/caching translations, route matching, and coordinating with parsers.
• Note: It does not include message interpolation or a default parser. You must provide one.

3. @sveltekit-i18n/parsers (Message Interpolation)

Use when: You need specific syntax for variables, formatting, or conditionals.

• @sveltekit-i18n/parser-default: Simple placeholder and modifier syntax.
• @sveltekit-i18n/parser-icu: Supports the ICU message format (requires intl-messageformat).
• Responsibilities: Interpolating variables, formatting numbers/dates/currencies, and handling plurals or gender-based conditional rendering.

The library operates through four distinct phases:

1. Configuration Phase: You initialize the i18n instance with a configuration object containing loaders. This registers loaders and initializes Svelte stores but does not execute the loaders yet.
2. Loading Phase: Triggered by calling loadTranslations(locale, route). The system matches the current locale and route against registered loaders, executes the loader() functions, preprocesses the data (e.g., flattening to dot notation), and stores the results in a central translations store.
3. Translation Phase: When you use the $t store in a Svelte component, the library looks up the key for the current locale and uses a parser to inject variables into the translation string.
4. Locale Switch: When locale.set(newLocale) is called, the library checks if translations for the new locale exist. If they are missing, it automatically triggers the Loading Phase for that locale before updating the stores and triggering UI reactivity.

import i18n from 'sveltekit-i18n';

const config = {
  loaders: [
    {
      locale: 'en',
      key: 'common',
      routes: ['/'],
      loader: async () => (await import('./en/common.json')).default,
    },
  ],
};

const { t, locale, loadTranslations } = new i18n(config);

To ensure scalability and ease of maintenance, organize your translation files in a directory structure that separates locales and uses namespaces (e.g., common.json, home.json).

Recommended Directory Structure

src/lib/translations/
├── index.js              # i18n configuration
├── en/
│   ├── common.json       # Shared UI, navigation
│   ├── home.json         # Homepage
│   ├── about.json        # About page
│   └── errors.json       # Error messages
├── cs/
│   ├── common.json
│   └── ...

Namespace Strategies

1. Common Namespace: Keep essential, frequently used translations (like navigation or buttons) in a common namespace that loads on every page. Keep this file small (< 5 KB).
2. Page-Specific Namespaces: Create separate namespaces for major routes to ensure translations load only when needed. Use the routes property in your config to target specific paths or regex patterns.
3. Feature-Based Organization: For large applications, group translations by functional features (e.g., auth.json, checkout.json) rather than by page. This allows multiple routes to share a single feature-based namespace.

const config = {
  loaders: [
    // Common (all pages)
    { locale: 'en', key: 'common', loader: async () => (await import('./en/common.json')).default },
    
    // Page-specific (route-based)
    { locale: 'en', key: 'home', routes: ['/'], loader: async () => (await import('./en/home.json')).default },
    { locale: 'en', key: 'about', routes: ['/about'], loader: async () => (await import('./en/about.json')).default },
    { locale: 'en', key: 'products', routes: [/^\/products/], loader: async () => (await import('./en/products.json')).default },
  ],
};