From ed6ce65638bb913eee923aafffafe9c80524a591 Mon Sep 17 00:00:00 2001
From: Jarda Svoboda <20700514+jarda-svoboda@users.noreply.github.com>
Date: Sun, 30 Nov 2025 16:21:45 +0100
Subject: [PATCH 1/3] Improve docs
---
CONTRIBUTING.md | 450 +++++++++++++++++++
README.md | 260 +++++++----
docs/ARCHITECTURE.md | 545 +++++++++++++++++++++++
docs/BEST_PRACTICES.md | 904 ++++++++++++++++++++++++++++++++++++++
docs/GETTING_STARTED.md | 530 ++++++++++++++++++++++
docs/INDEX.md | 279 ++++++++++++
docs/README.md | 747 ++++++++++++++++++++++++++++---
docs/TROUBLESHOOTING.md | 946 ++++++++++++++++++++++++++++++++++++++++
8 files changed, 4533 insertions(+), 128 deletions(-)
create mode 100644 CONTRIBUTING.md
create mode 100644 docs/ARCHITECTURE.md
create mode 100644 docs/BEST_PRACTICES.md
create mode 100644 docs/GETTING_STARTED.md
create mode 100644 docs/INDEX.md
create mode 100644 docs/TROUBLESHOOTING.md
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..49d6b0f
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,450 @@
+# Contributing to sveltekit-i18n
+
+Thank you for your interest in contributing to `sveltekit-i18n`! We welcome contributions from the community.
+
+> **Note:** We're currently looking for maintainers to help with the project. If you're interested, please see [this issue](https://github.com/sveltekit-i18n/lib/issues/197).
+
+## Table of Contents
+
+- [Ecosystem Overview](#ecosystem-overview)
+- [Repository Structure](#repository-structure)
+- [Getting Started](#getting-started)
+- [Git Workflow](#git-workflow)
+- [Commit Guidelines](#commit-guidelines)
+- [Making Changes](#making-changes)
+- [Testing](#testing)
+- [Pull Request Process](#pull-request-process)
+- [Code Standards](#code-standards)
+- [Release Process](#release-process-maintainers-only)
+- [Getting Help](#getting-help)
+
+## Ecosystem Overview
+
+The `sveltekit-i18n` ecosystem consists of three separate repositories:
+
+- **[sveltekit-i18n/lib](https://github.com/sveltekit-i18n/lib)** (this repository) – Main user-facing package that combines base with default parser
+- **[@sveltekit-i18n/base](https://github.com/sveltekit-i18n/base)** – Core i18n functionality with parser support
+- **[@sveltekit-i18n/parsers](https://github.com/sveltekit-i18n/parsers)** – Message parsers (parser-default, parser-icu)
+
+This repository (`lib`) is what most users install and is the main entry point for contributions.
+
+## Repository Structure
+
+```
+lib/
+├── src/ # Source code (TypeScript)
+│ ├── index.ts # Main entry point
+│ └── types.ts # Type definitions
+├── tests/ # Test files (Jest)
+│ ├── specs/ # Test specifications
+│ └── data/ # Test data and fixtures
+├── examples/ # Working SvelteKit example apps
+├── docs/ # User documentation
+│ ├── INDEX.md
+│ ├── GETTING_STARTED.md
+│ ├── ARCHITECTURE.md
+│ ├── BEST_PRACTICES.md
+│ └── TROUBLESHOOTING.md
+├── dist/ # Built files (git-ignored)
+└── package.json
+```
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js 18+ (or current LTS version)
+- npm or pnpm
+- Git
+
+### Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/sveltekit-i18n/lib.git
+cd lib
+
+# Install dependencies
+npm install
+```
+
+### Development Commands
+
+```bash
+npm run dev # Watch mode with auto-rebuild
+npm run build # Production build
+npm test # Run tests
+npm run lint # Check code style (runs automatically on commit)
+```
+
+## Git Workflow
+
+We use a **rebase-based workflow** to maintain a linear, clean git history.
+
+### Branch Strategy
+
+- `master` – Stable, production-ready code
+- Use descriptive branch names for your work
+
+### Workflow
+
+```bash
+# Create a feature branch (use any descriptive name)
+git checkout -b my-descriptive-branch-name
+
+# Make changes and commit atomically
+git add .
+git commit -m "Add feature X"
+
+# Keep your branch updated (rebase, NOT merge)
+git fetch origin
+git rebase origin/master
+
+# Push (use force-with-lease after rebase)
+git push origin my-descriptive-branch-name --force-with-lease
+```
+
+### Important Guidelines
+
+- **Use rebase**, not merge commits
+- **Keep linear history** – no merge commits in the history
+- **Force-push with `--force-with-lease`** (safer than `--force`)
+- Rebase your branch on `master` before creating a PR
+
+## Commit Guidelines
+
+### Atomic Commits
+
+Each commit must be **self-contained and meaningful**:
+
+- ✅ Works independently (can be cherry-picked)
+- ✅ Has a single, clear purpose
+- ✅ Passes tests on its own
+- ✅ Has a descriptive commit message
+
+### Commit Message Format
+
+```
+Brief description in imperative mood (max 72 characters)
+
+Optional longer explanation if needed. Explain WHAT and WHY,
+not HOW (the code shows how).
+
+Reference related issues if applicable:
+Fixes #123
+Relates to #456
+```
+
+### Good Commit Examples
+
+```
+Add locale switcher component
+Fix translation loading race condition
+Update API docs with TypeScript examples
+Refactor loader matching logic for clarity
+Add tests for route-based translation loading
+```
+
+### Bad Commit Examples
+
+```
+WIP
+fixes
+Update stuff
+Changed some files
+lots of changes
+```
+
+## Making Changes
+
+### Code Changes
+
+- All source code is in `src/`
+- TypeScript strict mode is enforced
+- ESLint runs automatically on commit (pre-commit hook)
+- **No `any` types** – use proper typing or `unknown` if necessary
+
+### Documentation Changes
+
+- User documentation is in `docs/`
+- All code comments must be in **English**
+- Update relevant documentation when changing APIs
+- Add examples for new features
+
+### Adding Examples
+
+- Examples are in `examples/`
+- Each example should be a complete, working SvelteKit application
+- Include a README explaining the use case and how it works
+
+## Testing
+
+### Running Tests
+
+```bash
+# Run all tests
+npm test
+
+# Watch mode
+npm test -- --watch
+
+# Run specific test file
+npm test -- path/to/test.spec.ts
+```
+
+### Writing Tests
+
+- Place tests in `tests/specs/`
+- Test data and fixtures in `tests/data/`
+- Use Jest with TypeScript
+- Test both functionality and TypeScript types
+- Aim for high coverage on core functionality
+
+### Test Structure
+
+```typescript
+describe('feature name', () => {
+ it('should do something specific', () => {
+ // Arrange - set up test data
+ const input = { locale: 'en', key: 'test' };
+
+ // Act - execute the code
+ const result = someFunction(input);
+
+ // Assert - verify the result
+ expect(result).toBe(expected);
+ });
+});
+```
+
+## Pull Request Process
+
+### Before Creating a PR
+
+1. **Rebase on latest master:** `git rebase origin/master`
+2. **Run tests:** `npm test` (all tests must pass)
+3. **Run linter:** `npm run lint` (no errors)
+4. **Build successfully:** `npm run build`
+5. **Update documentation** if you changed APIs
+
+### PR Title
+
+- Descriptive and concise
+- Use imperative mood: "Add feature" not "Added feature"
+- Examples: "Add locale switching support", "Fix memory leak in loader cache"
+
+### PR Description Template
+
+```markdown
+## What
+Brief description of the changes made.
+
+## Why
+Explanation of why this change is needed. Link to related issues.
+
+## How
+How you implemented it (if the approach is complex or non-obvious).
+
+## Testing
+How you tested the changes. Include test scenarios.
+
+## Checklist
+- [ ] Tests pass locally
+- [ ] Linter passes
+- [ ] Documentation updated (if needed)
+- [ ] All commits are atomic and well-described
+- [ ] Branch rebased on latest master
+```
+
+### Review Process
+
+1. A maintainer will review your PR
+2. Feedback may be requested – discussion is encouraged
+3. Make requested changes in new commits
+4. Once approved, maintainer will merge using rebase
+
+### Updating Your PR
+
+```bash
+# Make requested changes
+git add .
+git commit -m "Address review feedback"
+
+# Rebase and clean up commits if needed
+git rebase -i origin/master
+
+# Force push with updated commits
+git push origin my-branch-name --force-with-lease
+```
+
+## Code Standards
+
+### TypeScript
+
+- **Strict mode enabled** – all strict checks enforced
+- **No `any` types** – use proper types or `unknown` if type is truly unknown
+- **Proper type definitions** for all exports
+- Use `const` assertions where appropriate
+- Leverage TypeScript's inference when possible
+
+### ESLint
+
+- Airbnb TypeScript configuration
+- Auto-fixes run on commit (pre-commit hook)
+- Follow existing code style in the repository
+- Don't disable rules without good reason (and explanation)
+
+### Code Comments
+
+- **English only** – all comments and documentation in English
+- Use JSDoc for public APIs
+- Explain **WHY**, not WHAT (code shows what)
+- Add comments for non-obvious logic
+
+**Example:**
+
+```typescript
+// ✅ Good - explains why
+// Use WeakMap to avoid memory leaks when components are destroyed
+const cache = new WeakMap();
+
+// ❌ Bad - just describes what code does
+// Create a new WeakMap
+const cache = new WeakMap();
+```
+
+## Architecture Overview
+
+For developers working on the codebase, here's a brief technical overview:
+
+### Package Structure
+
+This package extends `@sveltekit-i18n/base` and pre-configures it with `@sveltekit-i18n/parser-default`:
+
+```typescript
+import Base from '@sveltekit-i18n/base';
+import parser from '@sveltekit-i18n/parser-default';
+
+class I18n extends Base {
+ constructor(config) {
+ // Normalize config to include default parser
+ super({
+ ...config,
+ parser: parser(config.parserOptions)
+ });
+ }
+}
+```
+
+### Key Concepts
+
+- **Loaders** – Define how and when translations load
+- **Routes** – Match loaders to specific routes
+- **Parser** – Handles message interpolation
+- **Preprocessing** – Transforms translation data after loading
+
+### For Detailed Architecture
+
+See the [Architecture Documentation](./docs/ARCHITECTURE.md) for in-depth explanation of how everything works.
+
+## Related Repositories
+
+### Contributing to Other Parts of the Ecosystem
+
+**Core functionality (@sveltekit-i18n/base):**
+- Repository: https://github.com/sveltekit-i18n/base
+- Contribute here for: Core i18n logic, store management, loader system
+
+**Parsers (@sveltekit-i18n/parsers):**
+- Repository: https://github.com/sveltekit-i18n/parsers
+- Contribute here for: Parser syntax changes, new parsers, modifier logic
+
+Each repository has its own issues and contribution guidelines.
+
+## Release Process (Maintainers Only)
+
+This section is for maintainers with publish access.
+
+### Version Bump
+
+```bash
+# Patch release (bug fixes)
+npm version patch
+
+# Minor release (new features, backwards compatible)
+npm version minor
+
+# Major release (breaking changes)
+npm version major
+```
+
+### Publishing
+
+```bash
+# Build the package
+npm run build
+
+# Publish to npm
+npm publish
+
+# Push tags to GitHub
+git push origin master --tags
+```
+
+### Changelog
+
+- Update `CHANGELOG.md` before releasing
+- Follow [Semantic Versioning](https://semver.org/)
+- Group changes by type: Features, Bug Fixes, Breaking Changes
+
+## Getting Help
+
+### Questions
+
+- **GitHub Discussions:** https://github.com/sveltekit-i18n/lib/discussions
+- **Issues:** https://github.com/sveltekit-i18n/lib/issues
+
+### Reporting Bugs
+
+When reporting a bug, include:
+
+- `sveltekit-i18n` version
+- `SvelteKit` version
+- Node.js version
+- Minimal reproduction (CodeSandbox, StackBlitz, or GitHub repo)
+- Expected behavior vs. actual behavior
+- Error messages and stack traces
+
+### Feature Requests
+
+When requesting a feature, include:
+
+- **Use case description** – What are you trying to achieve?
+- **Proposed API** (if you have ideas)
+- **Why current features don't work** – Have you tried existing approaches?
+- **Alternatives considered** – What other solutions did you consider?
+
+### Discussions
+
+For general questions, ideas, or showcasing what you've built, use [GitHub Discussions](https://github.com/sveltekit-i18n/lib/discussions).
+
+## Maintainer Opportunity
+
+We're actively looking for maintainers to help with:
+
+- Reviewing pull requests
+- Triaging issues
+- Maintaining documentation
+- Planning future direction
+
+If you're interested:
+
+1. Review the [maintainer opportunity issue](https://github.com/sveltekit-i18n/lib/issues/197)
+2. Make consistent, quality contributions
+3. Demonstrate understanding of the codebase and architecture
+4. Reach out to express your interest
+
+---
+
+Thank you for contributing to `sveltekit-i18n`! Your efforts help make internationalization easier for the SvelteKit community. 🌍
+
diff --git a/README.md b/README.md
index 69c24c1..88c06f6 100644
--- a/README.md
+++ b/README.md
@@ -7,126 +7,232 @@
# sveltekit-i18n
-`sveltekit-i18n` is a tiny library with no external dependencies, built for [Svelte](https://github.com/sveltejs/svelte) and [SvelteKit](https://github.com/sveltejs/kit). It glues [@sveltekit-i18n/base](https://github.com/sveltekit-i18n/base) and [@sveltekit-i18n/parser-default](https://github.com/sveltekit-i18n/parsers/tree/master/parser-default) together to provide you the most straightforward `sveltekit-i18n` solution.
-## Key features
+A lightweight, powerful internationalization (i18n) library designed specifically for [SvelteKit](https://github.com/sveltejs/kit). This package combines [@sveltekit-i18n/base](https://github.com/sveltekit-i18n/base) with [@sveltekit-i18n/parser-default](https://github.com/sveltekit-i18n/parsers/tree/master/parser-default) to provide the quickest way to add multilingual support to your SvelteKit applications.
-✅ SvelteKit ready\
-✅ SSR support\
-✅ Custom data sources – no matter if you are using local files or remote API to get your translations\
-✅ Module-based – your translations are loaded for visited pages only (and only once!)\
-✅ Component-scoped translations – you can create multiple instances with custom definitions\
-✅ Custom modifiers – you can modify the input data the way you really need\
-✅ TS support\
-✅ No external dependencies
+## Why sveltekit-i18n?
-## Usage
+- 🚀 **SvelteKit-optimized** – Built specifically for SvelteKit with full SSR support
+- 📦 **Minimal dependencies** – Only ecosystem packages (base + parser-default)
+- ⚡ **Smart loading** – Translations load only for visited pages (lazy loading)
+- 🎯 **Route-based** – Automatic translation loading based on your routes
+- 🔧 **Flexible** – Support for custom data sources (local files, APIs, databases)
+- 🌐 **Multiple parsers** – Choose the syntax that fits your needs
+- 📝 **TypeScript** – Complete type definitions and typed API
+- 🎨 **Component-scoped** – Create multiple translation instances for different parts of your app
+
+## Installation
+
+```bash
+npm install sveltekit-i18n
+```
+
+## Quick Start
+
+### 1. Create your translation files
+
+```json
+// src/lib/translations/en/common.json
+{
+ "greeting": "Hello, {{name}}!",
+ "nav.home": "Home",
+ "nav.about": "About"
+}
+```
+
+```json
+// src/lib/translations/cs/common.json
+{
+ "greeting": "Ahoj, {{name}}!",
+ "nav.home": "Domů",
+ "nav.about": "O nás"
+}
+```
+
+### 2. Setup i18n configuration
-Setup `translations.js` in your lib folder...
```javascript
+// src/lib/translations/index.js
import i18n from 'sveltekit-i18n';
/** @type {import('sveltekit-i18n').Config} */
-const config = ({
+const config = {
loaders: [
{
locale: 'en',
key: 'common',
- loader: async () => (
- await import('./en/common.json')
- ).default,
- },
- {
- locale: 'en',
- key: 'home',
- routes: ['/'], // you can use regexes as well!
- loader: async () => (
- await import('./en/home.json')
- ).default,
- },
- {
- locale: 'en',
- key: 'about',
- routes: ['/about'],
- loader: async () => (
- await import('./en/about.json')
- ).default,
+ loader: async () => (await import('./en/common.json')).default,
},
{
locale: 'cs',
key: 'common',
- loader: async () => (
- await import('./cs/common.json')
- ).default,
- },
- {
- locale: 'cs',
- key: 'home',
- routes: ['/'],
- loader: async () => (
- await import('./cs/home.json')
- ).default,
- },
- {
- locale: 'cs',
- key: 'about',
- routes: ['/about'],
- loader: async () => (
- await import('./cs/about.json')
- ).default,
+ loader: async () => (await import('./cs/common.json')).default,
},
],
-});
+};
export const { t, locale, locales, loading, loadTranslations } = new i18n(config);
```
-...load your translations in `+layout.js`...
+### 3. Load translations in your layout
```javascript
+// src/routes/+layout.js
import { loadTranslations } from '$lib/translations';
-/** @type {import('@sveltejs/kit').Load} */
+/** @type {import('./$types').LayoutLoad} */
export const load = async ({ url }) => {
const { pathname } = url;
+
+ const initLocale = 'en'; // determine from cookie, user preference, etc.
+
+ await loadTranslations(initLocale, pathname);
+
+ return {};
+};
+```
+
+### 4. Use translations in your components
- const initLocale = 'en'; // get from cookie, user session, ...
+```svelte
+
+
- await loadTranslations(initLocale, pathname); // keep this just before the `return`
+
{$t('common.greeting', { name: 'World' })}
- return {};
-}
+
```
-...and include your translations within pages and components.
+## Key Features
+
+### Route-based Loading
+
+Load translations only for specific routes to optimize performance:
+
+```javascript
+const config = {
+ loaders: [
+ {
+ locale: 'en',
+ key: 'home',
+ routes: ['/'], // Load only on homepage
+ loader: async () => (await import('./en/home.json')).default,
+ },
+ {
+ locale: 'en',
+ key: 'about',
+ routes: ['/about'], // Load only on about page
+ loader: async () => (await import('./en/about.json')).default,
+ },
+ ],
+};
+```
+
+### Placeholders and Modifiers
+
+Use dynamic values in your translations:
+
+```json
+{
+ "welcome": "Welcome, {{name}}!",
+ "items": "You have {{count:number;}} {{count; 1:item; default:items;}}."
+}
+```
```svelte
-
-
-
{$t('common.page', { pageName })}
-
{$t('home.content')}
-
+
{$t('welcome', { name: 'Alice' })}
+
{$t('items', { count: 5 })}
```
-## More info
-[Docs](https://github.com/sveltekit-i18n/lib/tree/master/docs/README.md)\
-[Examples](https://github.com/sveltekit-i18n/lib/tree/master/examples)\
-[Changelog](https://github.com/sveltekit-i18n/lib/releases)
+## Documentation
+
+**📖 [Complete Documentation Index](./docs/INDEX.md)** – Find everything in one place
+
+### Quick Links
+
+- 🚀 [Getting Started Guide](./docs/GETTING_STARTED.md) – 15-minute tutorial
+- 🏗️ [Architecture Overview](./docs/ARCHITECTURE.md) – How everything works
+- 📚 [API Documentation](./docs/README.md) – Complete reference
+- ✨ [Best Practices](./docs/BEST_PRACTICES.md) – Production-ready patterns
+- 🔧 [Troubleshooting](./docs/TROUBLESHOOTING.md) – Common issues & FAQ
+
+## Examples
+
+Explore working examples for different use cases:
+
+- [Multi-page app](./examples/multi-page) – Most common setup
+- [Locale-based routing](./examples/locale-router) – SEO-friendly URLs (e.g., `/en/about`)
+- [Component-scoped translations](./examples/component-scoped-ssr) – Isolated translation contexts
+- [Custom parsers](./examples/parser-icu) – Using ICU message format
+- [All examples](./examples) – Complete list of examples
+
+## Advanced Usage
+
+### Need a different parser?
+
+This library uses `@sveltekit-i18n/parser-default`. If you need ICU message format or want to create your own parser, use [@sveltekit-i18n/base](https://github.com/sveltekit-i18n/base) directly:
+
+```javascript
+import i18n from '@sveltekit-i18n/base';
+import parser from '@sveltekit-i18n/parser-icu';
+
+const config = {
+ parser: parser(),
+ // ... rest of config
+};
+```
+
+Learn more about [parsers](https://github.com/sveltekit-i18n/parsers).
+
+## TypeScript Support
+
+Full TypeScript support with complete type definitions for configuration and API:
+
+```typescript
+import i18n, { type Config } from 'sveltekit-i18n';
+
+const config: Config = {
+ loaders: [
+ // ... your loaders
+ ],
+};
+
+export const { t, locale, locales, loading, loadTranslations } = new i18n(config);
+```
+
+**Note:** The library provides type definitions but does not automatically infer translation keys from your JSON files. You can create custom type-safe wrappers if needed (see [Best Practices](./docs/BEST_PRACTICES.md#typescript-patterns)).
+
+## Contributing
+
+We welcome contributions! Please read our [Contributing Guide](./CONTRIBUTING.md) for details on:
+
+- Development setup and workflow
+- Git workflow (rebase-based, linear history)
+- Commit guidelines (atomic commits)
+- Pull request process
+- Code standards and testing
+
+**Note:** We're currently looking for maintainers. If you're interested in helping maintain this project, please reach out via [this issue](https://github.com/sveltekit-i18n/lib/issues/197).
+
+## Changelog
-## Roadmap
+See [Releases](https://github.com/sveltekit-i18n/lib/releases) for version history.
-### Q4 2025
+## Related Packages
-[ ] - Update the examples
-[ ] - Stabalise build & tests
-[ ] - Consolidate issues
+- [@sveltekit-i18n/base](https://github.com/sveltekit-i18n/base) – Core functionality with custom parser support
+- [@sveltekit-i18n/parser-default](https://github.com/sveltekit-i18n/parsers/tree/master/parser-default) – Default message parser
+- [@sveltekit-i18n/parser-icu](https://github.com/sveltekit-i18n/parsers/tree/master/parser-icu) – ICU message format parser
-### Q1 2026
+## License
-[ ] - Storage + State management overhall
\ No newline at end of file
+MIT
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
new file mode 100644
index 0000000..c09f94c
--- /dev/null
+++ b/docs/ARCHITECTURE.md
@@ -0,0 +1,545 @@
+# Architecture Overview
+
+This document explains how `sveltekit-i18n` works internally and how the three packages interact with each other. Understanding the architecture will help you make informed decisions about which package to use and how to configure it for your needs.
+
+## Table of Contents
+
+- [Package Overview](#package-overview)
+- [Package Relationships](#package-relationships)
+- [Data Flow](#data-flow)
+- [Loading Strategy](#loading-strategy)
+- [When to Use Each Package](#when-to-use-each-package)
+- [Core Concepts](#core-concepts)
+
+## Package Overview
+
+The `sveltekit-i18n` ecosystem consists of three main packages:
+
+### 1. @sveltekit-i18n/base
+
+**Role:** Core i18n functionality
+
+**Responsibilities:**
+- Managing translation state (Svelte stores)
+- Loading and caching translations
+- Route matching logic
+- Preprocessing translations
+- Coordinating with parsers
+
+**What it doesn't include:**
+- Message interpolation (delegates to parsers)
+- Default parser
+
+**Use when:** You need custom parsers or maximum flexibility
+
+### 2. sveltekit-i18n (lib)
+
+**Role:** Complete solution with sensible defaults
+
+**Responsibilities:**
+- Everything from `@sveltekit-i18n/base`
+- Pre-configured with `@sveltekit-i18n/parser-default`
+- Simplified API
+
+**Dependencies:** `@sveltekit-i18n/base` + `@sveltekit-i18n/parser-default` (no external dependencies)
+
+**Use when:** You want the quickest setup and are happy with default parser syntax
+
+### 3. @sveltekit-i18n/parsers
+
+**Role:** Message interpolation
+
+**Packages:**
+- `@sveltekit-i18n/parser-default` – Simple placeholder/modifier syntax
+- `@sveltekit-i18n/parser-icu` – ICU message format
+
+**Responsibilities:**
+- Interpolating variables into translation strings
+- Formatting (numbers, dates, currencies)
+- Conditional rendering (plurals, gender, etc.)
+
+**Use when:** You need specific message syntax (included automatically with `sveltekit-i18n` or `@sveltekit-i18n/base`)
+
+## Package Relationships
+
+Here's how the packages relate to each other:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ Your SvelteKit App │
+├─────────────────────────────────────────────────────────────┤
+│ │
+│ Option 1: Use Complete Solution │
+│ ┌──────────────────────────────────────────────┐ │
+│ │ sveltekit-i18n (lib) │ │
+│ │ ┌────────────────────────────────────────┐ │ │
+│ │ │ @sveltekit-i18n/base │ │ │
+│ │ │ (core functionality) │ │ │
+│ │ └────────────────────────────────────────┘ │ │
+│ │ ┌────────────────────────────────────────┐ │ │
+│ │ │ @sveltekit-i18n/parser-default │ │ │
+│ │ │ (included) │ │ │
+│ │ └────────────────────────────────────────┘ │ │
+│ └──────────────────────────────────────────────┘ │
+│ │
+│ Option 2: Use Base with Custom Parser │
+│ ┌──────────────────────────────────────────────┐ │
+│ │ @sveltekit-i18n/base │ │
+│ │ (you provide the parser) │ │
+│ └──────────────────────────────────────────────┘ │
+│ ┌──────────────────────────────────────────────┐ │
+│ │ @sveltekit-i18n/parser-icu │ │
+│ │ or your custom parser │ │
+│ └──────────────────────────────────────────────┘ │
+│ │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Dependency Tree
+
+```
+sveltekit-i18n
+├── @sveltekit-i18n/base
+└── @sveltekit-i18n/parser-default
+
+@sveltekit-i18n/base
+└── (no dependencies)
+
+@sveltekit-i18n/parser-default
+└── (no dependencies)
+
+@sveltekit-i18n/parser-icu
+└── intl-messageformat
+```
+
+## Data Flow
+
+Here's how translations flow through the system:
+
+### 1. Configuration Phase
+
+```javascript
+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);
+```
+
+**What happens:**
+1. i18n instance is created
+2. Loaders are registered (not executed yet)
+3. Svelte stores are initialized
+4. Parser is configured
+
+### 2. Loading Phase
+
+```javascript
+// In +layout.js
+await loadTranslations('en', '/');
+```
+
+**Flow:**
+
+```
+┌─────────────────────────────────────────────────────┐
+│ 1. loadTranslations('en', '/') │
+└────────────────┬────────────────────────────────────┘
+ │
+ ▼
+┌─────────────────────────────────────────────────────┐
+│ 2. Match loaders │
+│ - locale === 'en' │
+│ - routes includes '/' OR routes is undefined │
+└────────────────┬────────────────────────────────────┘
+ │
+ ▼
+┌─────────────────────────────────────────────────────┐
+│ 3. Execute loader functions │
+│ loader() → returns translation data │
+└────────────────┬────────────────────────────────────┘
+ │
+ ▼
+┌─────────────────────────────────────────────────────┐
+│ 4. Preprocess translations │
+│ - 'full': flatten to dot notation │
+│ - 'preserveArrays': flatten but keep arrays │
+│ - 'none': no changes │
+│ - custom function: your logic │
+└────────────────┬────────────────────────────────────┘
+ │
+ ▼
+┌─────────────────────────────────────────────────────┐
+│ 5. Store in translations store │
+│ { en: { 'common.greeting': 'Hello' } } │
+└────────────────┬────────────────────────────────────┘
+ │
+ ▼
+┌─────────────────────────────────────────────────────┐
+│ 6. Set locale │
+│ locale.set('en') │
+└─────────────────────────────────────────────────────┘
+```
+
+**Caching:** Each loader runs only once per locale. Results are cached in memory.
+
+### 3. Translation Phase
+
+```svelte
+
{$t('common.greeting', { name: 'Alice' })}
+```
+
+**Flow:**
+
+```
+┌─────────────────────────────────────────────────────┐
+│ 1. $t('common.greeting', { name: 'Alice' }) │
+└────────────────┬────────────────────────────────────┘
+ │
+ ▼
+┌─────────────────────────────────────────────────────┐
+│ 2. Get current locale │
+│ locale.get() → 'en' │
+└────────────────┬────────────────────────────────────┘
+ │
+ ▼
+┌─────────────────────────────────────────────────────┐
+│ 3. Lookup translation │
+│ translations['en']['common.greeting'] │
+│ → 'Hello, {{name}}!' │
+└────────────────┬────────────────────────────────────┘
+ │
+ ▼
+┌─────────────────────────────────────────────────────┐
+│ 4. Parser.parse() │
+│ parse('Hello, {{name}}!', [{ name: 'Alice' }]) │
+│ → 'Hello, Alice!' │
+└────────────────┬────────────────────────────────────┘
+ │
+ ▼
+┌─────────────────────────────────────────────────────┐
+│ 5. Return result │
+│ 'Hello, Alice!' │
+└─────────────────────────────────────────────────────┘
+```
+
+### 4. Locale Switch
+
+```javascript
+locale.set('cs');
+```
+
+**Flow:**
+
+```
+┌─────────────────────────────────────────────────────┐
+│ 1. locale.set('cs') │
+└────────────────┬────────────────────────────────────┘
+ │
+ ▼
+┌─────────────────────────────────────────────────────┐
+│ 2. Check if translations exist │
+│ translations['cs'] ? │
+└────────────────┬────────────────────────────────────┘
+ │
+ ┌───────┴────────┐
+ │ │
+ ▼ ▼
+ ┌─────────┐ ┌──────────┐
+ │ Exists │ │ Missing │
+ └────┬────┘ └────┬─────┘
+ │ │
+ │ ▼
+ │ ┌─────────────────────┐
+ │ │ Load translations │
+ │ │ (matching loaders) │
+ │ └────┬────────────────┘
+ │ │
+ └─────────┴────────┐
+ ▼
+ ┌───────────────────────────┐
+ │ 3. Update locale store │
+ │ triggers reactivity │
+ └───────────┬───────────────┘
+ │
+ ▼
+ ┌───────────────────────────┐
+ │ 4. All $t() re-evaluate │
+ │ UI updates │
+ └───────────────────────────┘
+```
+
+## Loading Strategy
+
+### Route-based Loading
+
+The library uses SvelteKit's routing to determine which translations to load:
+
+```javascript
+const config = {
+ loaders: [
+ // No routes specified → loads on every page
+ {
+ locale: 'en',
+ key: 'common',
+ loader: async () => (await import('./en/common.json')).default,
+ },
+
+ // Exact match → loads only on '/'
+ {
+ locale: 'en',
+ key: 'home',
+ routes: ['/'],
+ loader: async () => (await import('./en/home.json')).default,
+ },
+
+ // Regex → loads on matching routes
+ {
+ locale: 'en',
+ key: 'products',
+ routes: [/^\/products/],
+ loader: async () => (await import('./en/products.json')).default,
+ },
+ ],
+};
+```
+
+**Matching algorithm:**
+
+```javascript
+function shouldLoadTranslation(loader, currentRoute) {
+ // No routes specified → always load
+ if (!loader.routes || loader.routes.length === 0) {
+ return true;
+ }
+
+ // Check each route pattern
+ for (const route of loader.routes) {
+ if (typeof route === 'string') {
+ // Exact string match
+ if (currentRoute === route) return true;
+ } else if (route instanceof RegExp) {
+ // Regex match
+ if (route.test(currentRoute)) return true;
+ }
+ }
+
+ return false;
+}
+```
+
+### Server vs Client Loading
+
+**Server-Side (SSR):**
+- Translations load during `+layout.js` or `+page.js` load
+- Data is serialized and sent to client
+- Hydration picks up from there
+
+**Client-Side:**
+- When locale changes, new translations load on client
+- When navigating, route-specific translations load
+- Loading state available via `$loading` store
+
+### Caching Strategy
+
+**In-Memory Cache:**
+```javascript
+{
+ 'en': {
+ 'common': { /* translations */ },
+ 'home': { /* translations */ },
+ },
+ 'cs': {
+ 'common': { /* translations */ },
+ },
+}
+```
+
+**Cache Refresh:**
+- Client: Never refreshes (single session)
+- Server: Configurable via `cache` option (default: 24 hours)
+
+```javascript
+const config = {
+ cache: 86400000, // 24 hours in milliseconds
+ // or: Number.POSITIVE_INFINITY (never refresh)
+};
+```
+
+## When to Use Each Package
+
+### Use `sveltekit-i18n` (lib)
+
+```javascript
+import i18n from 'sveltekit-i18n';
+```
+
+**When:**
+- ✅ You want the quickest setup
+- ✅ Default parser syntax is sufficient
+- ✅ You don't need custom parsers
+- ✅ You want zero dependencies
+
+**Best for:** Most projects, rapid prototyping, simple to medium complexity
+
+### Use `@sveltekit-i18n/base`
+
+```javascript
+import i18n from '@sveltekit-i18n/base';
+import parser from '@sveltekit-i18n/parser-icu';
+```
+
+**When:**
+- ✅ You need ICU message format
+- ✅ You want to create a custom parser
+- ✅ You're migrating from another i18n library
+- ✅ You need specific message syntax
+
+**Best for:** Complex projects, enterprise applications, specific requirements
+
+## Core Concepts
+
+### Svelte Stores
+
+The library uses Svelte stores for reactivity:
+
+```javascript
+// Readable stores (read-only)
+$t // Translation function
+$locales // Available locales
+$loading // Loading state
+$initialized // Initialization state
+
+// Writable stores (can be updated)
+$locale // Current locale
+```
+
+**Reactivity:** When stores update, all components using them re-render automatically.
+
+### Preprocessing
+
+Transforms nested objects into flat dot notation:
+
+**Input:**
+```json
+{
+ "user": {
+ "profile": {
+ "name": "Name",
+ "email": "Email"
+ }
+ }
+}
+```
+
+**Output (preprocess: 'full'):**
+```json
+{
+ "user.profile.name": "Name",
+ "user.profile.email": "Email"
+}
+```
+
+**Why?** Enables efficient lookups and simpler translation keys in code.
+
+### Parser Interface
+
+All parsers implement this interface:
+
+```typescript
+interface Parser {
+ parse(
+ value: any, // Translation value
+ params: any[], // Parameters from $t()
+ locale: string, // Current locale
+ key: string // Translation key
+ ): string;
+}
+```
+
+**Example implementation:**
+
+```javascript
+const simpleParser = () => ({
+ parse: (value, params) => {
+ const vars = params[0] || {};
+ return String(value).replace(
+ /\{(\w+)\}/g,
+ (_, key) => vars[key] ?? key
+ );
+ },
+});
+```
+
+### Namespaces
+
+Namespaces organize translations into logical groups:
+
+```
+common → Shared UI, navigation, errors
+home → Homepage content
+products → Product-related text
+checkout → Checkout flow
+```
+
+**Benefits:**
+- Easier to manage
+- Enables lazy loading
+- Better code organization
+- Multiple teams can work independently
+
+## Performance Considerations
+
+### Bundle Size
+
+**sveltekit-i18n:**
+- Core: ~5KB (minified)
+- Includes: base + parser-default
+- No external dependencies
+
+**@sveltekit-i18n/base + parser-icu:**
+- Base: ~5KB (zero dependencies)
+- Parser-ICU: ~15KB + intl-messageformat dependency
+
+### Loading Performance
+
+**Best practices:**
+1. Use route-based loading (don't load everything at once)
+2. Keep common translations small
+3. Use code splitting (dynamic imports)
+4. Enable server-side caching
+
+### Runtime Performance
+
+- Translation lookup: O(1) (object property access)
+- Parser execution: Varies by complexity
+- Store updates: Svelte's efficient reactivity
+
+## Summary
+
+The `sveltekit-i18n` architecture is designed to be:
+
+- **Modular** – Use only what you need
+- **Flexible** – Customize with parsers and config
+- **Performant** – Lazy loading and efficient caching
+- **TypeScript** – Complete type definitions
+- **Developer-friendly** – Simple API, clear concepts
+
+Choose the right package for your needs and leverage the loading strategies to build efficient, multilingual SvelteKit applications.
+
+## See Also
+
+- [Getting Started](./GETTING_STARTED.md) – Learn by building
+- [API Documentation](./README.md) – Complete reference
+- [Best Practices](./BEST_PRACTICES.md) – Recommended patterns
+- [Parsers](https://github.com/sveltekit-i18n/parsers) – Parser details
+
diff --git a/docs/BEST_PRACTICES.md b/docs/BEST_PRACTICES.md
new file mode 100644
index 0000000..8c91a4e
--- /dev/null
+++ b/docs/BEST_PRACTICES.md
@@ -0,0 +1,904 @@
+# Best Practices
+
+This guide covers recommended patterns, conventions, and tips for using `sveltekit-i18n` effectively in production applications.
+
+## Table of Contents
+
+- [Translation File Organization](#translation-file-organization)
+- [Key Naming Conventions](#key-naming-conventions)
+- [Performance Optimization](#performance-optimization)
+- [TypeScript Patterns](#typescript-patterns)
+- [SSR and CSR Considerations](#ssr-and-csr-considerations)
+- [Component-Scoped Translations](#component-scoped-translations)
+- [Dynamic Routes and Locales](#dynamic-routes-and-locales)
+- [Content Management](#content-management)
+- [Testing](#testing)
+- [Production Deployment](#production-deployment)
+
+## Translation File Organization
+
+### Directory Structure
+
+Organize translations by locale and namespace:
+
+```
+src/lib/translations/
+├── index.js # i18n configuration
+├── en/
+│ ├── common.json # Shared UI, navigation
+│ ├── home.json # Homepage
+│ ├── about.json # About page
+│ ├── products.json # Product pages
+│ └── errors.json # Error messages
+├── cs/
+│ ├── common.json
+│ ├── home.json
+│ ├── about.json
+│ ├── products.json
+│ └── errors.json
+└── de/
+ ├── common.json
+ └── ...
+```
+
+**✅ Benefits:**
+- Easy to find translations
+- Clear separation by locale
+- Scalable structure
+
+### Namespace Strategy
+
+#### Common Namespace
+
+Keep frequently used translations in a `common` namespace loaded on every page:
+
+```json
+// common.json
+{
+ "app.name": "My App",
+ "nav.home": "Home",
+ "nav.about": "About",
+ "nav.products": "Products",
+ "button.save": "Save",
+ "button.cancel": "Cancel",
+ "button.delete": "Delete",
+ "error.required": "This field is required",
+ "error.invalid": "Invalid input"
+}
+```
+
+**Keep it small** – Only essentials that appear across multiple pages.
+
+#### Page-Specific Namespaces
+
+Create separate namespaces for each major page or section:
+
+```javascript
+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 },
+ ],
+};
+```
+
+**✅ Benefits:**
+- Translations load only when needed
+- Smaller initial bundle
+- Easier to manage
+
+#### Feature-Based Organization
+
+For large apps, organize by feature instead of page:
+
+```
+translations/
+├── en/
+│ ├── common.json
+│ ├── auth.json # Login, register, password reset
+│ ├── checkout.json # Cart, payment, confirmation
+│ ├── profile.json # User profile, settings
+│ └── admin.json # Admin panel
+```
+
+```javascript
+const config = {
+ loaders: [
+ { locale: 'en', key: 'auth', routes: ['/login', '/register', '/reset-password'], loader: async () => (await import('./en/auth.json')).default },
+ { locale: 'en', key: 'checkout', routes: [/^\/cart/, /^\/checkout/], loader: async () => (await import('./en/checkout.json')).default },
+ ],
+};
+```
+
+### File Size Guidelines
+
+**Target sizes:**
+- `common.json`: < 5 KB (essential shared content)
+- Page-specific: < 20 KB per file
+- If larger, consider splitting into sub-namespaces
+
+**Example split:**
+
+```
+products/
+├── list.json # Product listing page
+├── detail.json # Product detail page
+├── compare.json # Product comparison
+└── reviews.json # Product reviews
+```
+
+## Key Naming Conventions
+
+### Use Dot Notation
+
+Organize keys hierarchically with dots:
+
+```json
+{
+ "user.profile.name": "Name",
+ "user.profile.email": "Email",
+ "user.settings.privacy": "Privacy",
+ "user.settings.notifications": "Notifications"
+}
+```
+
+**✅ Clear structure, easy to find related translations**
+
+### Descriptive Names
+
+Use clear, descriptive key names:
+
+```json
+// ❌ Bad
+{
+ "t1": "Welcome",
+ "btn": "Click",
+ "txt": "Hello"
+}
+
+// ✅ Good
+{
+ "home.welcome.title": "Welcome",
+ "common.button.submit": "Submit",
+ "greeting.message": "Hello"
+}
+```
+
+### Consistency Patterns
+
+Establish naming patterns and stick to them:
+
+```json
+{
+ // Pages
+ "home.title": "Home",
+ "about.title": "About",
+ "contact.title": "Contact",
+
+ // Forms
+ "form.label.name": "Name",
+ "form.label.email": "Email",
+ "form.placeholder.search": "Search...",
+ "form.error.required": "Required",
+
+ // Buttons
+ "button.submit": "Submit",
+ "button.cancel": "Cancel",
+ "button.save": "Save",
+
+ // Messages
+ "message.success.saved": "Successfully saved",
+ "message.error.failed": "Operation failed"
+}
+```
+
+### Avoid Deep Nesting
+
+**❌ Too deep (harder to maintain):**
+
+```json
+{
+ "pages.user.profile.settings.privacy.options.visibility.public": "Public"
+}
+```
+
+**✅ Better (balanced):**
+
+```json
+{
+ "profile.privacy.public": "Public"
+}
+```
+
+**Rule of thumb:** Max 3-4 levels deep
+
+### Context in Keys
+
+Include context when the same word has different meanings:
+
+```json
+{
+ "common.button.close": "Close", // Button text
+ "common.adjective.close": "Near", // Adjective
+ "store.status.open": "Open", // Store is open
+ "action.open": "Open file", // Action to open
+ "navigation.home": "Home", // Nav link
+ "address.home": "Home address" // Address type
+}
+```
+
+## Performance Optimization
+
+### Lazy Loading
+
+Load translations only when needed using route-based loaders:
+
+```javascript
+const config = {
+ loaders: [
+ // Always load
+ { locale: 'en', key: 'common', loader: async () => (await import('./en/common.json')).default },
+
+ // Load on specific routes
+ { locale: 'en', key: 'admin', routes: [/^\/admin/], loader: async () => (await import('./en/admin.json')).default },
+ ],
+};
+```
+
+**✅ Impact:**
+- Reduces initial bundle size
+- Faster page loads
+- Better performance metrics
+
+### Preload Critical Routes
+
+Preload translations for likely next pages:
+
+```svelte
+
+
+
+```
+
+### Cache Configuration
+
+Set appropriate cache duration for your use case:
+
+```javascript
+// Production: Long cache (good performance)
+const config = {
+ cache: 86400000, // 24 hours
+};
+
+// With CMS: Short cache (content updates frequently)
+const config = {
+ cache: 300000, // 5 minutes
+};
+
+// Static content: Infinite cache
+const config = {
+ cache: Number.POSITIVE_INFINITY,
+};
+```
+
+### Bundle Splitting
+
+Use dynamic imports for large translation files:
+
+```javascript
+// ❌ Static import (always in bundle)
+import translations from './large-translations.json';
+
+// ✅ Dynamic import (lazy loaded)
+loader: async () => (await import('./large-translations.json')).default
+```
+
+### Avoid Fallback Locale (If Possible)
+
+`fallbackLocale` doubles translation loading:
+
+```javascript
+// ❌ Loads both 'cs' and 'en' translations
+const config = {
+ fallbackLocale: 'en',
+};
+
+// ✅ Complete all translations (no fallback needed)
+// Only loads current locale
+```
+
+Use fallback only during development or partial translations.
+
+## TypeScript Patterns
+
+### Type-Safe Configuration
+
+```typescript
+import i18n, { type Config } from 'sveltekit-i18n';
+
+const config: Config = {
+ loaders: [
+ {
+ locale: 'en',
+ key: 'common',
+ loader: async () => (await import('./en/common.json')).default,
+ },
+ ],
+};
+```
+
+### Translation Key Types (Custom Pattern)
+
+The library doesn't automatically infer types from translation files. If you need type-safe translation keys, you can manually define them:
+
+```typescript
+// translations.d.ts
+export interface TranslationKeys {
+ 'common.greeting': { name: string };
+ 'common.items': { count: number };
+ 'home.title': never; // No params
+}
+
+// translations.ts
+import type { TranslationKeys } from './translations.d';
+
+export const { t } = new i18n(config);
+
+// You'll need to create a typed wrapper for strict checking:
+// export function typedT(
+// key: K,
+// ...params: TranslationKeys[K] extends never ? [] : [TranslationKeys[K]]
+// ): string {
+// return t.get(key, ...(params as any));
+// }
+```
+
+**Note:** This requires manual maintenance. Consider generating types from your translation files using tools like `typesafe-i18n` if you need automatic type inference.
+
+### Typed Helpers
+
+Create typed helper functions:
+
+```typescript
+import { t } from '$lib/translations';
+
+export function formatPrice(amount: number, currency: string = 'USD'): string {
+ return t.get('common.price', { amount }, { currency });
+}
+
+export function pluralize(count: number, singular: string, plural: string): string {
+ return count === 1 ? singular : plural;
+}
+```
+
+### Module Augmentation
+
+Extend types for better IDE support:
+
+```typescript
+// app.d.ts
+declare module '$lib/translations' {
+ export const t: import('svelte/store').Readable<
+ (key: string, vars?: Record, props?: any) => string
+ > & {
+ get: (key: string, vars?: Record, props?: any) => string;
+ };
+
+ export const locale: import('svelte/store').Writable & {
+ get: () => string;
+ };
+
+ // ... other exports
+}
+```
+
+## SSR and CSR Considerations
+
+### Load in Layout
+
+Always load translations in `+layout.js` for SSR:
+
+```javascript
+// src/routes/+layout.js
+import { loadTranslations } from '$lib/translations';
+
+export const load = async ({ url }) => {
+ const { pathname } = url;
+ const initLocale = 'en'; // Determine from cookie, header, etc.
+
+ await loadTranslations(initLocale, pathname);
+
+ return {};
+};
+```
+
+**✅ Benefits:**
+- Translations ready on server
+- No flash of untranslated content (FOUC)
+- SEO-friendly
+
+### Handle Loading State
+
+Show proper loading indicators:
+
+```svelte
+
+
+{#if $loading}
+
+```
+
+### 3. Test Loaders Directly
+
+```javascript
+// Test in browser console or separate script
+const loader = async () => (await import('$lib/translations/en/common.json')).default;
+const data = await loader();
+console.log(data);
+```
+
+### 4. Enable Debug Logging
+
+```javascript
+const config = {
+ log: {
+ level: 'debug', // See all operations
+ },
+};
+```
+
+### 5. Check Available Locales
+
+```svelte
+
+
+
Available locales: {$locales.join(', ')}
+```
+
+### 6. Verify Route Matching
+
+```javascript
+// In +layout.js
+export const load = async ({ url }) => {
+ console.log('Current pathname:', url.pathname);
+ await loadTranslations('en', url.pathname);
+ return {};
+};
+```
+
+---
+
+## Frequently Asked Questions
+
+### Can I use this library without SvelteKit?
+
+`sveltekit-i18n` is designed specifically for SvelteKit. For plain Svelte apps, consider:
+- [svelte-i18n](https://github.com/kaisermann/svelte-i18n)
+- [svelte-intl-precompile](https://github.com/cibernox/svelte-intl-precompile)
+
+### Can I use HTML in translations?
+
+No, translations are rendered as text. For HTML content, use `@html`:
+
+```svelte
+
{@html $t('content.with.html')}
+```
+
+**⚠️ Security Warning:** Only use `@html` with trusted content. Never use it with user-generated content.
+
+### How do I handle plurals?
+
+Use the default parser's conditional syntax:
+
+```json
+{
+ "items": "You have {{count}} {{count; 1:item; default:items;}}."
+}
+```
+
+Or use ICU parser for advanced pluralization:
+
+```json
+{
+ "items": "You have {count, plural, =0 {no items} one {# item} other {# items}}."
+}
+```
+
+### Can I change parser after initialization?
+
+Not recommended. Create a new instance instead:
+
+```javascript
+const { t: tDefault } = new i18n(configWithDefaultParser);
+const { t: tICU } = new i18n(configWithICUParser);
+```
+
+### How do I handle right-to-left (RTL) languages?
+
+The library doesn't handle RTL directly. Manage it in your app:
+
+```svelte
+
+
+
+
{$t('content')}
+
+```
+
+### Can I nest translation calls?
+
+No, `$t()` returns a string, not a translation key. Pre-compose your translations:
+
+```javascript
+// ❌ Won't work
+$t($t('dynamic.key'))
+
+// ✅ Use variables
+const key = someCondition ? 'key1' : 'key2';
+$t(key)
+```
+
+### How do I translate dynamic content?
+
+Use placeholders:
+
+```json
+{
+ "welcome": "Welcome, {{name}}!",
+ "error": "{{field}} is required."
+}
+```
+
+```javascript
+$t('welcome', { name: userName })
+$t('error', { field: $t('form.field.email') })
+```
+
+### Can I load translations from a database?
+
+Yes! Use async loader:
+
+```javascript
+{
+ locale: 'en',
+ key: 'dynamic',
+ loader: async () => {
+ const res = await fetch('/api/translations/en');
+ return await res.json();
+ },
+}
+```
+
+### How do I handle missing translations during development?
+
+Use `fallbackLocale` temporarily:
+
+```javascript
+const config = {
+ fallbackLocale: 'en', // Fall back to English
+};
+```
+
+Or use a custom `fallbackValue`:
+
+```javascript
+const config = {
+ fallbackValue: '🚧', // Show construction emoji
+};
+```
+
+### Does this work with SvelteKit adapters?
+
+Yes! Works with all adapters:
+- `@sveltejs/adapter-auto`
+- `@sveltejs/adapter-node`
+- `@sveltejs/adapter-static`
+- `@sveltejs/adapter-vercel`
+- `@sveltejs/adapter-netlify`
+- And others
+
+### How do I translate meta tags (SEO)?
+
+In `+page.js` or `+page.server.js`:
+
+```javascript
+import { t } from '$lib/translations';
+
+export const load = async () => {
+ return {
+ meta: {
+ title: t.get('page.title'),
+ description: t.get('page.description'),
+ },
+ };
+};
+```
+
+In `+page.svelte`:
+
+```svelte
+
+
+
+ {data.meta.title}
+
+
+```
+
+---
+
+## Known Limitations
+
+### 1. Cannot use dots in namespace keys
+
+```javascript
+// ❌ Won't work correctly
+{ key: 'pages.home' }
+
+// ✅ Use different separator or remove
+{ key: 'pages_home' }
+{ key: 'home' }
+```
+
+### 2. Translation keys are case-sensitive
+
+```json
+{
+ "Greeting": "Hello"
+}
+```
+
+```javascript
+$t('greeting') // ❌ Won't find 'Greeting'
+$t('Greeting') // ✅ Correct
+```
+
+### 3. Locale identifiers must be lowercase
+
+```javascript
+locale.set('EN') // ❌ Converts to 'en'
+locale.set('en') // ✅ Correct
+```
+
+### 4. No automatic locale detection
+
+You must explicitly set the locale:
+
+```javascript
+// Detect from browser
+const browserLang = navigator.language.split('-')[0];
+
+// Detect from URL
+const urlLang = url.pathname.split('/')[1];
+
+// Set locale
+await loadTranslations(browserLang, url.pathname);
+```
+
+---
+
+## Getting Help
+
+### Before Asking for Help
+
+1. **Check this guide** – Most issues are covered here
+2. **Search existing issues** – Someone might have had the same problem
+3. **Enable debug logging** – `log: { level: 'debug' }`
+4. **Create a minimal reproduction** – Isolate the problem
+
+### Where to Get Help
+
+1. **[GitHub Issues](https://github.com/sveltekit-i18n/lib/issues)** – Bug reports and feature requests
+2. **[GitHub Discussions](https://github.com/sveltekit-i18n/lib/discussions)** – Questions and community help
+3. **[Examples](../examples)** – Working code you can reference
+
+### Creating a Good Issue
+
+Include:
+- **SvelteKit version** (`npm list @sveltejs/kit`)
+- **sveltekit-i18n version** (`npm list sveltekit-i18n`)
+- **Minimal reproduction** (CodeSandbox, StackBlitz, or GitHub repo)
+- **Expected behavior** vs **actual behavior**
+- **Error messages** (full stack trace)
+- **Configuration** (anonymized if needed)
+
+**Example:**
+
+```markdown
+## Bug Report
+
+### Environment
+- SvelteKit: 2.0.0
+- sveltekit-i18n: 2.4.2
+- Node: 20.10.0
+
+### Issue
+Translations flash on page load
+
+### Reproduction
+https://stackblitz.com/edit/...
+
+### Expected
+Translations should be ready on initial render
+
+### Actual
+Keys briefly visible before translations load
+
+### Configuration
+... paste your config ...
+```
+
+---
+
+## See Also
+
+- [Getting Started](./GETTING_STARTED.md) – Setup tutorial
+- [API Documentation](./README.md) – Complete API reference
+- [Best Practices](./BEST_PRACTICES.md) – Recommended patterns
+- [Architecture](./ARCHITECTURE.md) – How it works internally
+- [Examples](../examples) – Working code examples
+
From 4ff8c89a14f7631edbe8ae43e154c4de56f19b35 Mon Sep 17 00:00:00 2001
From: Jarda Svoboda <20700514+jarda-svoboda@users.noreply.github.com>
Date: Sun, 30 Nov 2025 16:21:57 +0100
Subject: [PATCH 2/3] Add PR template
---
.github/pull_request_template.md | 43 ++++++++++++++++++++++++++++++++
1 file changed, 43 insertions(+)
create mode 100644 .github/pull_request_template.md
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
new file mode 100644
index 0000000..91d9f0b
--- /dev/null
+++ b/.github/pull_request_template.md
@@ -0,0 +1,43 @@
+## What
+
+
+
+## Why
+
+
+
+Fixes #
+Relates to #
+
+## How
+
+
+
+## Testing
+
+
+
+## Checklist
+
+Before submitting this PR, please ensure:
+
+- [ ] **Tests pass locally** (`npm test`)
+- [ ] **Linter passes** (`npm run lint`)
+- [ ] **Build succeeds** (`npm run build`)
+- [ ] **All commits are atomic** (each commit works independently)
+- [ ] **Commits have clear messages** (imperative mood, descriptive)
+- [ ] **Branch rebased on latest master** (`git rebase origin/master`)
+- [ ] **Documentation updated** (if API or behavior changed)
+- [ ] **Examples updated** (if adding new features)
+
+## Additional Notes
+
+
+
+---
+
+
+
From 80fcd2a067c2ed225d8a1f0c2c9439ee02d98981 Mon Sep 17 00:00:00 2001
From: Jarda Svoboda <20700514+jarda-svoboda@users.noreply.github.com>
Date: Sun, 30 Nov 2025 17:07:06 +0100
Subject: [PATCH 3/3] Add issue templates
---
.github/ISSUE_TEMPLATE/bug_report.yml | 120 +++++++++++++++++++++
.github/ISSUE_TEMPLATE/config.yml | 15 +++
.github/ISSUE_TEMPLATE/documentation.yml | 69 ++++++++++++
.github/ISSUE_TEMPLATE/feature_request.yml | 92 ++++++++++++++++
4 files changed, 296 insertions(+)
create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml
create mode 100644 .github/ISSUE_TEMPLATE/config.yml
create mode 100644 .github/ISSUE_TEMPLATE/documentation.yml
create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
new file mode 100644
index 0000000..676b22c
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -0,0 +1,120 @@
+name: Bug Report
+description: Report a bug or unexpected behavior
+title: "[Bug]: "
+labels: ["bug"]
+body:
+ - type: markdown
+ attributes:
+ value: |
+ Thanks for taking the time to report a bug! Please fill out the information below to help us investigate.
+
+ - type: textarea
+ id: description
+ attributes:
+ label: Describe the bug
+ description: A clear and concise description of what the bug is.
+ placeholder: What went wrong?
+ validations:
+ required: true
+
+ - type: textarea
+ id: reproduction
+ attributes:
+ label: Reproduction
+ description: Steps to reproduce the behavior, or a link to a minimal reproduction (CodeSandbox, StackBlitz, GitHub repo).
+ placeholder: |
+ 1. Configure i18n with...
+ 2. Navigate to...
+ 3. See error...
+ validations:
+ required: true
+
+ - type: textarea
+ id: expected
+ attributes:
+ label: Expected behavior
+ description: What did you expect to happen?
+ placeholder: What should have happened?
+ validations:
+ required: true
+
+ - type: textarea
+ id: actual
+ attributes:
+ label: Actual behavior
+ description: What actually happened?
+ placeholder: What actually happened?
+ validations:
+ required: true
+
+ - type: input
+ id: sveltekit-i18n-version
+ attributes:
+ label: sveltekit-i18n version
+ description: What version of sveltekit-i18n are you using?
+ placeholder: "2.4.2"
+ validations:
+ required: true
+
+ - type: input
+ id: sveltekit-version
+ attributes:
+ label: SvelteKit version
+ description: What version of SvelteKit are you using?
+ placeholder: "2.0.0"
+ validations:
+ required: true
+
+ - type: input
+ id: node-version
+ attributes:
+ label: Node.js version
+ description: What version of Node.js are you using?
+ placeholder: "20.10.0"
+ validations:
+ required: true
+
+ - type: dropdown
+ id: adapter
+ attributes:
+ label: SvelteKit Adapter
+ description: Which SvelteKit adapter are you using?
+ options:
+ - "@sveltejs/adapter-auto"
+ - "@sveltejs/adapter-node"
+ - "@sveltejs/adapter-static"
+ - "@sveltejs/adapter-vercel"
+ - "@sveltejs/adapter-netlify"
+ - "@sveltejs/adapter-cloudflare"
+ - "Other (specify in additional context)"
+ validations:
+ required: true
+
+ - type: textarea
+ id: logs
+ attributes:
+ label: Error logs
+ description: Please paste any relevant error messages or console logs.
+ render: shell
+ placeholder: Paste error logs here
+
+ - type: textarea
+ id: additional
+ attributes:
+ label: Additional context
+ description: Add any other context about the problem here (browser, operating system, etc.).
+ placeholder: Any additional information that might help
+
+ - type: checkboxes
+ id: checklist
+ attributes:
+ label: Checklist
+ description: Please confirm the following
+ options:
+ - label: I have searched existing issues to avoid duplicates
+ required: true
+ - label: I have provided a minimal reproduction (if possible)
+ required: false
+ - label: I have checked the [Troubleshooting Guide](https://github.com/sveltekit-i18n/lib/blob/master/docs/TROUBLESHOOTING.md)
+ required: false
+
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
new file mode 100644
index 0000000..aebcf96
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,15 @@
+blank_issues_enabled: false
+contact_links:
+ - name: 💬 GitHub Discussions
+ url: https://github.com/sveltekit-i18n/lib/discussions
+ about: Ask questions, share ideas, or discuss the project
+ - name: 📖 Documentation
+ url: https://github.com/sveltekit-i18n/lib/tree/master/docs
+ about: Read the complete documentation
+ - name: 🔧 Troubleshooting Guide
+ url: https://github.com/sveltekit-i18n/lib/blob/master/docs/TROUBLESHOOTING.md
+ about: Common issues and solutions
+ - name: 💡 Examples
+ url: https://github.com/sveltekit-i18n/lib/tree/master/examples
+ about: Working example applications
+
diff --git a/.github/ISSUE_TEMPLATE/documentation.yml b/.github/ISSUE_TEMPLATE/documentation.yml
new file mode 100644
index 0000000..cf855fd
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/documentation.yml
@@ -0,0 +1,69 @@
+name: Documentation Issue
+description: Report an issue with documentation or suggest improvements
+title: "[Docs]: "
+labels: ["documentation"]
+body:
+ - type: markdown
+ attributes:
+ value: |
+ Thanks for helping improve our documentation!
+
+ - type: dropdown
+ id: doc-type
+ attributes:
+ label: Documentation type
+ description: What kind of documentation issue is this?
+ options:
+ - "Error or incorrect information"
+ - "Missing information"
+ - "Unclear or confusing explanation"
+ - "Broken link"
+ - "Typo or grammar"
+ - "Suggestion for improvement"
+ - "Other"
+ validations:
+ required: true
+
+ - type: input
+ id: location
+ attributes:
+ label: Documentation location
+ description: Which documentation page or file is this about?
+ placeholder: "docs/GETTING_STARTED.md, README.md, etc."
+ validations:
+ required: true
+
+ - type: textarea
+ id: current
+ attributes:
+ label: Current documentation
+ description: What does the current documentation say? (copy/paste or describe)
+ placeholder: The current docs say...
+ validations:
+ required: true
+
+ - type: textarea
+ id: issue
+ attributes:
+ label: What's the issue?
+ description: What's wrong or missing?
+ placeholder: The issue is...
+ validations:
+ required: true
+
+ - type: textarea
+ id: suggestion
+ attributes:
+ label: Suggested improvement
+ description: How should it be changed or what should be added?
+ placeholder: It should say... or Add section about...
+ validations:
+ required: true
+
+ - type: textarea
+ id: additional
+ attributes:
+ label: Additional context
+ description: Any other context that might help.
+ placeholder: Any additional information
+
diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml
new file mode 100644
index 0000000..a4ec7b3
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/feature_request.yml
@@ -0,0 +1,92 @@
+name: Feature Request
+description: Suggest a new feature or enhancement
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+ - type: markdown
+ attributes:
+ value: |
+ Thanks for suggesting a new feature! Please provide as much detail as possible.
+
+ - type: textarea
+ id: problem
+ attributes:
+ label: Problem statement
+ description: Is your feature request related to a problem? Please describe what you're trying to achieve.
+ placeholder: I'm trying to do X but can't because...
+ validations:
+ required: true
+
+ - type: textarea
+ id: solution
+ attributes:
+ label: Proposed solution
+ description: Describe the solution you'd like to see.
+ placeholder: I would like to be able to...
+ validations:
+ required: true
+
+ - type: textarea
+ id: api
+ attributes:
+ label: Proposed API (if applicable)
+ description: If you have ideas about how the API should look, share them here.
+ placeholder: |
+ ```javascript
+ const config = {
+ newFeature: { ... }
+ };
+ ```
+ render: markdown
+
+ - type: textarea
+ id: alternatives
+ attributes:
+ label: Alternatives considered
+ description: Have you tried any workarounds or alternative approaches?
+ placeholder: I tried X but it didn't work because...
+
+ - type: textarea
+ id: use-case
+ attributes:
+ label: Use case
+ description: Describe your use case. How would this feature benefit you and others?
+ placeholder: This would help with...
+ validations:
+ required: true
+
+ - type: dropdown
+ id: scope
+ attributes:
+ label: Which package?
+ description: Which package would this feature be for?
+ options:
+ - "sveltekit-i18n (main lib)"
+ - "@sveltekit-i18n/base"
+ - "@sveltekit-i18n/parser-default"
+ - "@sveltekit-i18n/parser-icu"
+ - "New parser"
+ - "Not sure"
+ validations:
+ required: true
+
+ - type: textarea
+ id: additional
+ attributes:
+ label: Additional context
+ description: Add any other context, screenshots, or examples about the feature request.
+ placeholder: Any additional information
+
+ - type: checkboxes
+ id: checklist
+ attributes:
+ label: Checklist
+ description: Please confirm the following
+ options:
+ - label: I have searched existing issues and discussions to avoid duplicates
+ required: true
+ - label: I have checked the [documentation](https://github.com/sveltekit-i18n/lib/tree/master/docs) and [examples](https://github.com/sveltekit-i18n/lib/tree/master/examples)
+ required: true
+ - label: This feature cannot be achieved with current functionality
+ required: true
+