# SvelteKit localization with TransLocale

Connect native i18next catalogs to SvelteKit with translation state scoped to each rendered component tree.

Canonical page: https://translocale.io/integrations/sveltekit

## Install

@translocale/svelte 0.1.9. Node.js 22.16+ · Svelte 5. Message format: Native i18next JSON v4.

```bash
npm install @translocale/svelte i18next
```

## Connect and configure

Create a cloud project under Projects → New project. Copy PROJECT_UUID from Project settings → Credentials, and match the project languages to your catalogs. Browser login stores authoring access outside the app. For CI, create a credential under Project settings → Credentials and put it in the TRANSLOCALE_TOKEN secret. App delivery uses a separate read-only credential under Releases → App delivery.

```bash
npx translocale-svelte init --api https://translocale.io --project PROJECT_UUID --source en --locales en,fr,ar --namespaces common,checkout
```

```bash
npx translocale-svelte login --scope translate
```

Setup generates src/lib/translocale-resources.ts. Call provideTranslations from @translocale/svelte/runtime inside your locale layout's component script, then useTranslations in descendants. Update the provider when the route language changes. The included README shows the layout code, and the consumer example sets the document language and direction for server rendering and browser navigation. Add translocale-svelte check before vite build.

## Translate and review

Inspect the plan before translating. The translate example starts a job capped at 1,000 source characters across target languages. Replace JOB_UUID with its returned ID. Save and review revision 1 before pulling it, or choose the exact revision you want to ship. Repeat pull for each target language. Normal builds do not start translation jobs.

```bash
npx translocale-svelte plan
npx translocale-svelte translate --max-characters 1000 --wait
npx translocale-svelte pull --job JOB_UUID --locale fr --revision 1
npx translocale-svelte check
```

Run npx translocale-svelte discover --source en to find locale and namespace directories. Initialize from a reviewed candidate using the included discovery guide. Sync compares incoming revisions with local edits and a recorded baseline, then requires an explicit plan hash before writing.

## Project setup and credentials

The screenshot walkthrough covers project creation, catalog import, keys, review, releases, and credentials. Use this framework’s message format and catalog identities. Authoring tokens belong in developer tools and CI; app delivery credentials only read published wording. Flutter’s flutter-connect writes DELIVERY_* build settings, while the dashboard download uses projectId, channel, schemaHash, deliveryToken, and apiBaseUrl.

- [Follow the illustrated first-project guide](https://translocale.io/docs/getting-started)

## SvelteKit localization with a locale layout

This integration uses Svelte 5 and i18next JSON v4. For an en/fr example, configure locales as [en, fr], namespaces as [common], and defaultNamespace as common. Setup generates src/lib/translocale-resources.ts from your local files.

locales/en/common.json:

```json
{
  "welcome": "Hello, {{name}}"
}
```

locales/fr/common.json:

```json
{
  "welcome": "Bonjour, {{name}}"
}
```

Validate the URL language in the locale layout's load function. Importing the generated bundle makes the accepted URL languages match its configured locales; an unsupported language returns 404.

src/routes/[locale]/+layout.ts:

```text
import {error} from '@sveltejs/kit';
import type {LayoutLoad} from './$types';
import bundle from '$lib/translocale-resources';

export const load: LayoutLoad = ({params}) => {
  if (!bundle.locales.includes(params.locale)) {
    error(404, 'Language not supported');
  }
  return {locale: params.locale};
};
```

Create the translation provider inside the layout component. This example uses legacy component syntax supported by Svelte 5. The reactive setLocale call updates the existing store when navigation changes data.locale.

src/routes/[locale]/+layout.svelte:

```text
<script lang="ts">
import bundle from '$lib/translocale-resources';
import {provideTranslations} from '@translocale/svelte/runtime';
export let data: {locale: string};
const translations = provideTranslations(bundle, data.locale);
$: translations.setLocale(data.locale);
</script>

<div lang={$translations.locale} dir={$translations.direction}>
  <slot />
</div>
```

src/routes/[locale]/+page.svelte:

```text
<script>
import {useTranslations} from '@translocale/svelte/runtime';
const translations = useTranslations();
</script>

<p>{$translations.t('common:welcome', {name: 'Sam'})}</p>
```

The page renders “Hello, Sam” under /en and “Bonjour, Sam” under /fr. The wrapper sets language and direction for its descendants. Set the document's html language and direction separately in your server hook and client navigation handling.

## Fix stale languages and missing translation context

If the language stays unchanged after navigation, keep the reactive setLocale line: SvelteKit can reuse the layout instance. If useTranslations reports a missing provider, move the provider into a parent layout so the page is its descendant.

Each provider creates its own i18next instance and catalog copy. Initialize it per component tree, including each server request. A shared mutable module-level translation store can mix request languages.

Generated imports need every configured namespace file for every locale. Supply missing catalogs and rerun the check before building. The runtime reads bundled resources and does not fetch cloud translations or authoring credentials.

Check configured i18next catalogs:

```bash
npx translocale-svelte check
```

Render translations through Svelte text expressions as shown above. Svelte escapes the output; this package does not supply rich-component rendering. Use the i18next guide for plural suffixes and language-specific target forms.

- [SvelteKit state and component reuse](https://svelte.dev/docs/kit/state-management)
- [i18next plural examples](https://translocale.io/integrations/i18next#pluralization)
- [Check an i18next source file](https://translocale.io/app)

## Compatibility and further setup

Uses native i18next JSON v4 with default separators. svelte-i18n and Paraglide catalogs, translated URL slugs, and rich-component rendering are not supported.

The package uses Svelte 5's supported legacy component syntax. Local Cloudflare server rendering and browser hydration are tested; hosted consumer deployment and lazy catalog loading remain pending.

- [Complete framework guide, including runtime examples](https://translocale.io/integrations/sveltekit)
- [MCP guide](https://translocale.io/docs/mcp)
- [Free source file checker](https://translocale.io/app)