Svelte: Getting Started

Install the packages

Vite+

vp add @lingui/core lingui-for-svelte
vp add -D @lingui/cli @lingui/conf unplugin-lingui-macro

npm

npm install @lingui/core lingui-for-svelte
npm install -D @lingui/cli @lingui/conf unplugin-lingui-macro

pnpm

pnpm add @lingui/core lingui-for-svelte
pnpm add -D @lingui/cli @lingui/conf unplugin-lingui-macro

yarn

yarn add @lingui/core lingui-for-svelte
yarn add -D @lingui/cli @lingui/conf unplugin-lingui-macro

Tip

unplugin-lingui-macro is only needed if you use Lingui macros in plain JavaScript or TypeScript files. If you only use macros in .svelte files, you can skip installing this package and adding its Vite plugin in the next section. See Plain JS/TS Setup for the full setup guide.

Configure Vite

vite.config.ts

import { defineConfig } from "vite";
import { sveltekit } from "@sveltejs/kit/vite";
import linguiForSvelte from "lingui-for-svelte/unplugin/vite";
import linguiMacro from "unplugin-lingui-macro/vite";

export default defineConfig({
  plugins: [linguiMacro(), linguiForSvelte(), sveltekit()],
});

Configure Lingui

lingui.config.ts

import babelExtractor from "@lingui/cli/api/extractors/babel";
import { defineConfig } from "lingui-for-svelte/config";
import { svelteExtractor } from "lingui-for-svelte/extractor";

export default defineConfig({
  locales: ["en", "ja"],
  sourceLocale: "en",
  catalogs: [{ path: "src/lib/i18n/locales/{locale}" }],
  extractors: [svelteExtractor, babelExtractor],
});

Tip

If you do not use Lingui macros in plain JavaScript or TypeScript files, you can omit babelExtractor from the extractors array and skip the import.

Use the optional framework.svelte field in this config when you need Svelte-specific options such as custom macro package names, whitespace handling, or runtime warning switches. See Framework Config for details.

Initialize Lingui

Call setLinguiContext near the root of the component tree, such as a layout, before any translated component renders.

src/routes/+layout.svelte

<script lang="ts">
  import { setupI18n } from "@lingui/core";
  import { setLinguiContext } from "lingui-for-svelte";
  import { catalog } from "$lib/i18n/catalog";

  const { children } = $props();

  const i18n = setupI18n({ locale: "en", messages: catalog });
  setLinguiContext(i18n);
</script>

{@render children()}

Tip

catalog is a locale-keyed object exported from a shared setup file. See Load Compiled Catalogs for how to create that file and choose between bundling all locales upfront or loading them on demand.

Use macros in .svelte

src/routes/+page.svelte

<script lang="ts">
  import { Trans, t } from "lingui-for-svelte/macro";

  let count = $state(1);
</script>

<h1>{$t`Hello from Svelte`}</h1>

<p><Trans>{count} item selected</Trans></p>

In Svelte, the reactive form is available as $t. When the locale changes, this expression will automatically re-evaluate. See Reactive Macros for when to use the $ prefix and how it works under the hood.

Next pages

• Read i18n Context for initialization patterns, island setup, and locale switching.
• Read Reactive Macros to understand how $t and friends work and when to use the $ prefix.
• Read Locale Resolution for how to resolve the initial locale from URL params, cookies, and browser headers in SvelteKit.
• Read Svelte caveats for edge cases and limitations.
• Use the macro reference when you need precise authoring rules.