i18next

SvelteKit Translation with i18next

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

TransLocale documentation · Updated September 17, 2026 · Markdown quick start

New to TransLocale? Follow the screenshot walkthrough to create a project, add keys and translations, review wording, and get credentials. Use this guide’s message format and catalog names for your app. Your project ID is under Project settings → Credentials.

1. Install

Run this from your application directory.

npm install @translocale/svelte i18next

2. Connect your project

Create a cloud project and replace PROJECT_UUID with its ID. The source and target languages must match your local configuration. Adjust the example locales to your project.

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

Approve translation access in the browser:

npx translocale-svelte login --scope translate

Sign-in is shared with your other TransLocale tools for this project. Keep credentials in developer tooling or CI. Your deployed app reads its own translation files.

3. Wire up your app

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.

4. Translate, review, and download

Inspect the plan before running translate. The example caps the job at 1,000 source characters across its target languages. Waiting stops after two minutes; a timeout leaves the job running.

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

Replace JOB_UUID with the completed job ID. Before pulling revision 1, save that revision in the dashboard and review its wording. Choose the exact saved revision you want to ship, then repeat pull for each target locale. Revision 0 is the original generated output.

Normal application builds use saved catalogs and make no paid translation requests.

Already have translations?

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.

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

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

locales/fr/common.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

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

<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

<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

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.

Current limits

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.

The service accepts up to 100 KB and 200 messages per source document. Expanded target messages must also fit the adapter's limits. Read the file compatibility guide.

Check a file before connecting

Try the free source file checker to inspect message structure without an account. For assistant setup and read-only catalog checks, follow the MCP localization guide.