#Documentation Index

Complete documentation for the sveltekit-i18n ecosystem, covering 3.4: one reactive instance built on Svelte 5 runes, no stores, the parser wired in, and sveltekit-i18n/kit wiring it into SvelteKit — npm install sveltekit-i18n is the whole install.

Upgrading from v2? Go straight to Upgrading from v2 and the migration table. From an earlier 3.x? Read Upgrading from 3.3, Upgrading from 3.2, Upgrading from 3.1 and, from 3.0, Upgrading from 3.0.

#🚀 Getting Started

New to sveltekit-i18n? Start here:

#Getting Started Guide

A SvelteKit app from nothing to multilingual, in seven steps

• Requirements and installation – Svelte 5, Node 22 / Bun 1.2 / Deno 2, ESM-only
• Basic concepts – locales, keys, loaders, namespaces, the instance
• Your first multilingual app – translation files, the config and defineI18n, handle, load, use() and get()
• Route-based loading (split namespaces, route params), switching locales and locale-based routing
• Placeholders and modifiers, including parserOptions
• TypeScript, with a schema generated by typegen, and testing components

Perfect for: first-time users, quick setup

#📚 Core Documentation

#Architecture Overview

Understanding how everything works

• Package overview and relationships – core, parser, this package; composition rather than inheritance, and the parser extension
• The reactive engine – runes, and why the core ships its rune modules uncompiled
• Data flow – construction, loading, translation, locale switch
• Loading strategy – route matching, load records per loader and route params, deduplication, cache, invalidation and cache: false
• Instance lifetime – /kit's per-request and per-tab instances, the snapshot() / hydrate() hand-off, destroy()
• Core concepts, when to use each package, performance

Perfect for: understanding internals, making architecture decisions

#API Documentation

Complete reference for sveltekit-i18n

• Installation and packaging – ESM-only, one install, bundler requirements
• Configuration – loaders, translations, basePath, initLocale, fallbackLocale, fallbackValue, preprocess, sanitizeLocales, cache, log, schema, extensions
• Parser options – modifierDefaults, customModifiers, onReport, recognizeWrappers, onSuspectValue
• The instance – reactive properties, reactive functions, promise-returning methods (loadNamespace among them), synchronous methods (snapshot and hydrate among them)
• Message format, exported types, utilities
• TypeScript (and typegen), extensions – keys as members of t, markup in a message, the pipe order
• SvelteKit – sveltekit-i18n/kit: setup, which locale, data.i18n, pitfalls
• SSR by hand, testing
• Migrating from v2, upgrading from 3.3, upgrading from 3.2, upgrading from 3.1 and upgrading from 3.0

Perfect for: day-to-day development, looking up specific APIs

#@sveltekit-i18n/base API Documentation

The canonical reference for every member this package inherits

• Configuration and loaders
• Instance properties and methods
• SvelteKit and server-side rendering
• Upgrading from 3.2, from 3.1 and from 3.0 – every behaviour and type change
• The parser contract – for building on the core with a different parser
• TypeScript

Perfect for: member-level detail, or using the core with a custom parser

#✨ Best Practices

#Best Practices Guide

Recommended patterns for production apps

• Instance ownership – per-request instances, the module-level singleton hazard, destroy(), why value properties must not be destructured
• Awaiting loads – await the matching load instead of polling loading
• SSR and CSR – /kit, the hand-off, resolving the locale with preferredLocale, no flash of untranslated content
• Organization and key naming
• Performance – lazy loading, loadNamespace(), preloading with preload(), cache, cache: false and invalidate()
• TypeScript – schema and typegen, one payload type, locale completion, custom modifier props
• Extensions – the pipe, getting the $t surface back, keys as members of t, markup in a message, and the order they go in
• Component-scoped – isolated translation contexts
• Library authors – shipping translations with a package
• Dynamic routes – locale-based routing through preferredLocale, right-to-left locales
• Content management – CMS, API and database sources, remote query loaders
• Testing – a real instance instead of a mock
• Production – logging, parser reports, loader failures, monitoring

Perfect for: building production applications, scaling your i18n implementation

#🔧 Troubleshooting

#Troubleshooting & FAQ

Solutions to common problems

• Upgrading from v2 – $t is not a store, destructured values that never update, the removal of .get() / .set() / .subscribe() / toPromise() / getTranslationProps(), and instanceof
• Upgrading from 3.0 – a refetch after hydration, the key deprecation warning, a loader's redirect() or error()
• Setup and packaging – $state is not defined, two copies of the core, ERR_REQUIRE_ESM
• Common issues – translations not loading, keys instead of values, flashing content, route matching and basePath, locale not changing, stale translations, one visitor's locale in another's page, silent parser reports, TypeScript errors and typegen, tests, performance
• Debugging tips – inspect translations, enable debug logging, open the report channel, test a loader
• FAQ – common questions
• Known limitations – what to be aware of

Perfect for: fixing issues, understanding limitations

#🎨 Parser Documentation

Message interpolation lives in a parser. This package wires one; the core takes any parser that satisfies base's parser contract.

#@sveltekit-i18n/parser-curly

The parser wired into this package

• Placeholders {{name}}, default values, nested placeholders, escaping
• Modifiers (number, date, currency, ago, …), plural selection (plural, ordinal) and comparisons
• Custom modifiers, modifier defaults, the report channel and how payload values are read — all reachable here through parserOptions
• Implements the Curly Message Format

#@sveltekit-i18n/parser-icu

ICU message format

For an application that wants ICU syntax, built on @sveltekit-i18n/base directly — this package fills the parser slot itself and cannot take another parser.

#@sveltekit-i18n/parser-mf2

Unicode MessageFormat 2

The Unicode standard's successor to ICU MessageFormat, on the core directly in the same way.

#@sveltekit-i18n/parser-i18next

The i18next syntax

For translation files that already exist in i18next's syntax, interpolated by i18next's own engine — on the core directly in the same way.

#Parsers Overview

The parser monorepo, and writing your own

#💡 Examples

#All Examples

Working code you can learn from

Standalone applications on v3: locale routing (URL parameter, path prefix, static adapter, default locale unprefixed), per-request negotiation from a cookie and Accept-Language, component-scoped translations rendered on the client, and on the server handed over through snapshot() and hydrate(), t() inside Markdown routes, the $t store surface of extension-stores, the member keys of extension-typed-access, and the markup extension-html renders.

#📦 Package Documentation

#This Package

• sveltekit-i18n README – overview and quick start
• Contributing guide – repository layout, workflow, tests
• Releases – version history

#The Family

• @sveltekit-i18n/base – the core; state, loading, caching, route matching, preprocessing (releases)
• @sveltekit-i18n/parser-curly, @sveltekit-i18n/parser-icu, @sveltekit-i18n/parser-mf2 and @sveltekit-i18n/parser-i18next (releases)
• @sveltekit-i18n/typegen – the Vite plugin that generates the schema type from your translations (releases)
• @sveltekit-i18n/sv – the Svelte CLI add-on that sets sveltekit-i18n up in a SvelteKit project (npx sv add @sveltekit-i18n) (releases)
• Extensions – official adapters for the config.extensions pipe: @sveltekit-i18n/extension-stores (the $t / $locale / $loading surface), @sveltekit-i18n/extension-typed-access (keys as members of t) and @sveltekit-i18n/extension-html (markup in a message, rendered as elements and Svelte components) (releases)
• Curly Message Format – the message format specification

base, parsers, extensions and typegen release first; sveltekit-i18n after them, since it pins the core and the parser exactly; and @sveltekit-i18n/sv last, since it installs the others. Read a package's current version off npm.

#🎯 Quick Links by Task

#I want to...

#Learn the basics

→ Getting Started Guide

#Upgrade an app from v2

→ Upgrading from v2 and the migration table

#Get $t back

→ Best Practices: Extensions

#Use keys as members of t

→ API Docs: Keys as members of t or Best Practices: Keys as members of t

#Render markup in a message

→ API Docs: Markup in a message or Best Practices: Markup in a message

#Understand how it works

→ Architecture Overview

#Look up an API

→ API Documentation or base API Documentation

#Wire it into SvelteKit

→ API Docs: SvelteKit or Getting Started

#Render on the server without leaking a visitor's locale

→ API Docs: SvelteKit, API Docs: SSR by hand or Best Practices: Instance Ownership

#Upgrade an app from 3.3

→ API Docs: Upgrading from 3.3

#Upgrade an app from 3.2

→ API Docs: Upgrading from 3.2

#Upgrade an app from 3.1

→ API Docs: Upgrading from 3.1

#Upgrade an app from 3.0

→ API Docs: Upgrading from 3.0 and Troubleshooting: Upgrading from 3.0

#Serve the app under a base path

→ API Docs: basePath

#Load a namespace on demand

→ API Docs: loadNamespace()

#Build a production app

→ Best Practices Guide

#Fix an issue

→ Troubleshooting Guide

#See working code

→ Examples

#Write a custom modifier or open the report channel

→ API Docs: Parser options or parser-curly

#Use a different message format

→ Architecture: When to Use Each Package

#Create locale-based URLs

→ Best Practices: Dynamic Routes

#Optimize performance

→ Best Practices: Performance or Architecture: Performance

#Type my keys and payloads

→ API Docs: typegen, Best Practices: TypeScript or API Docs: TypeScript

#Load from an API or database

→ Best Practices: Content Management or base API: Loaders

#Test components that translate

→ Best Practices: Testing or Getting Started: Testing

#Deploy to production

→ Best Practices: Production

#📖 Reading Order

#For Beginners

1. Getting Started Guide – learn by building
2. API Documentation – the surface, member by member
3. Best Practices – level up your implementation

#For Upgraders

1. Upgrading from v2 – the first-day errors
2. Migrating from v2 – the old member, the new one
3. Upgrading from 3.3 – what 3.4 changes
4. Upgrading from 3.2 – what 3.3 changes
5. Upgrading from 3.1 – what 3.2 changes
6. Upgrading from 3.0 – what 3.1 changes
7. Best Practices: Instance Ownership – what per-request instances change

#For Advanced Users

1. Architecture Overview – understand the system
2. base API Documentation – deep dive
3. Parsers and Extensions – custom message formats and custom surfaces

#For Troubleshooting

1. Troubleshooting Guide – find your issue
2. FAQ – common questions
3. GitHub Issues – get help

#🤝 Contributing

Interested in contributing to sveltekit-i18n?

• Contributing Guide – setup, workflow, tests, PRs
• GitHub Repository – main library, and the shared issue tracker for the whole family
• Issues – report bugs, request features
• Discussions – ask questions, share ideas

#📄 License

MIT License – See individual repositories for details.

Can't find what you're looking for? Check the Troubleshooting Guide for how to get help.