INDEX.md

Documentation Index

Complete documentation for the sveltekit-i18n ecosystem. Whether you're just getting started or need detailed API references, you'll find everything here.

🚀 Getting Started

New to sveltekit-i18n? Start here:

Getting Started Guide

Time to complete: 15 minutes

Step-by-step tutorial that walks you through:

• Installing the library
• Creating your first translations
• Loading translations in your app
• Using translations in components
• Switching between languages

Perfect for: First-time users, quick setup

---

📚 Core Documentation

Architecture Overview

Understanding how everything works

Learn about:

• Package relationships (base, lib, parsers)
• Data flow (configuration → loading → translation)
• Loading strategies (route-based, SSR/CSR)
• When to use each package
• Performance considerations

Perfect for: Understanding internals, making architecture decisions

API Documentation

Complete reference for sveltekit-i18n

Includes:

• All configuration options with examples
• Parser options (modifierDefaults, customModifiers)
• Instance properties and methods ($t, $locale, etc.)
• Message format syntax
• TypeScript usage

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

@sveltekit-i18n/base API Documentation

API reference for base package

Detailed documentation for:

• Core configuration options
• Loaders (local files, APIs, databases)
• Preprocessing strategies
• All stores and methods
• Advanced use cases

Perfect for: Using base package with custom parsers

---

✨ Best Practices

Best Practices Guide

Recommended patterns for production apps

Covers:

• Organization – File structure, naming conventions
• Performance – Lazy loading, caching, bundle optimization
• TypeScript – Typed configuration, custom type-safe patterns
• SSR/CSR – Server-side rendering considerations
• Component-scoped – Isolated translation contexts
• Dynamic routes – Locale-based routing patterns
• Content management – CMS and database integration
• Testing – Mocking translations, test strategies
• Production – Deployment, monitoring, error handling

Perfect for: Building production applications, scaling your i18n implementation

---

🔧 Troubleshooting

Troubleshooting & FAQ

Solutions to common problems

Includes:

• Common Issues with step-by-step solutions:
  • Translations not loading
  • Keys displayed instead of values
  • Flashing content (FOUC)
  • Route-based loading problems
  • Locale not changing
  • TypeScript errors
  • SSR errors
  • Performance issues
• Debugging tips – Inspect stores, test loaders, enable logging
• FAQ – 15+ frequently asked questions
• Known limitations – What to be aware of

Perfect for: Fixing issues, understanding limitations

---

🎨 Parser Documentation

Parsers Overview

Available parsers and creating custom ones

Learn about:

• Choosing between parsers
• Parser comparison
• Creating custom parsers
• Parser integration with base

@sveltekit-i18n/parser-default

Default parser with placeholders and modifiers

Features:

• Simple placeholder syntax: {{name}}
• Built-in modifiers: number, date, currency, ago
• Conditionals: {{count; 1:item; default:items;}}
• Comparison operators: eq, ne, lt, gt, lte, gte
• Custom modifiers
• No external dependencies

@sveltekit-i18n/parser-icu

ICU message format parser

Features:

• Industry-standard ICU syntax
• Advanced pluralization
• Select format (gender, etc.)
• Number/date/time formatting
• Comprehensive Intl support

---

💡 Examples

All Examples

Working code you can learn from

Browse examples by use case:

Basic Examples

• Single Load – Load all translations at once
• One Page – Simple one-page app
• Multi Page – Multiple routes (most common)

Routing Examples

• Locale Parameter – URL parameter (?lang=en)
• Locale Router – Path-based (/en/about)
• Locale Router Advanced – Default locale without prefix
• Locale Router Static – Static adapter optimized

Advanced Examples

• Component Scoped CSR – Client-side component translations
• Component Scoped SSR – Server-side component translations
• Fallback Locale – Handling missing translations

Parser Examples

• Parser Default – Default parser features
• Parser ICU – ICU message format

Configuration Examples

• Loaders – Different loader configurations
• Preprocess – Preprocessing strategies

Each example includes:

• Complete working code
• Live demo on Netlify
• README with explanations

---

📦 Package Documentation

Main Library

• sveltekit-i18n – Main library README
• Changelog – Version history

Core Package

• @sveltekit-i18n/base – Base package README
• Base Changelog – Version history

Parsers

• Parsers – Parsers overview
• parser-default – Default parser
• parser-icu – ICU parser
• Parser Changelogs – Version history

---

🎯 Quick Links by Task

I want to...

Learn the basics

→ Getting Started Guide

Understand how it works

→ Architecture Overview

Look up an API

→ API Documentation or Base API Documentation

Build a production app

→ Best Practices Guide

Fix an issue

→ Troubleshooting Guide

See working code

→ Examples

Use a different parser

→ Parsers Overview

Create locale-based URLs

→ Locale Router Example or Best Practices: Dynamic Routes

Optimize performance

→ Best Practices: Performance or Architecture: Performance

Add TypeScript

→ Best Practices: TypeScript or API Docs: TypeScript

Load from API/database

→ Best Practices: Content Management or Base API: Loaders

Test my translations

→ Best Practices: Testing

Deploy to production

→ Best Practices: Production

---

📖 Reading Order

For Beginners

1. Getting Started Guide – Learn by building
2. Examples – See more use cases
3. Best Practices – Level up your implementation

For Advanced Users

1. Architecture Overview – Understand the system
2. Base API Documentation – Deep dive into APIs
3. Parsers – Custom message formats

For Troubleshooting

1. Troubleshooting Guide – Find your issue
2. FAQ – Common questions
3. GitHub Issues – Get help

---

🤝 Contributing

Interested in contributing to sveltekit-i18n?

• GitHub Repository – Main library
• Issues – Report bugs, request features
• Discussions – Ask questions, share ideas

Note: We're currently looking for maintainers. If you're interested in helping maintain this project, please see this issue.

---

📄 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.