Svelte: i18n Context

lingui-for-svelte uses Svelte’s built-in component context API to pass the active i18n instance through the component tree without props.

If you only need one rule, use setLinguiContext once near the root of the tree before translated markup renders.

For the full I18n instance API, including loadAndActivate, activate, load, and _, see the official @lingui/core reference.

Initialize in the root layout

In a SvelteKit app, the root layout is the default place to install context. All pages and child components inherit it automatically.

src/routes/+layout.svelte

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

  let { data, children } = $props();

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

{@render children()}

Note

catalog here is a locale-keyed object ({ en: ..., ja: ... }) from a shared setup file. See Load Compiled Catalogs for how to create it and for alternative loading strategies.

Internally, setLinguiContext wraps Svelte’s setContext. Every descendant component in the same tree can read the active i18n instance without prop drilling.

Avoid calling setLinguiContext in deeply nested components unless you need an isolated subtree with a different locale or catalog.

Same-component initialization

This is supported. A component can install context and use $t or other reactive macros in the same file.

The reason it works is that the compiler inserts a deferred accessor (createLinguiAccessors). Context is resolved lazily, so it is ready by the time compiled markup runs.

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

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

<p>{$t`Hello`}</p>

Svelte islands inside Astro

A Svelte island is a separate component tree. It does not share context with the surrounding Astro page. Each island must call setLinguiContext itself.

src/components/MyIsland.svelte

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

  const { locale = "en" } = $props();

  // Islands run in isolation. Initialize their own context.
  // untrack prevents Svelte from treating this setup code as a reactive
  // dependency: if `locale` later changes as a prop, the island should
  // re-activate the existing i18n instance (e.g. via $effect), not re-run
  // the entire initialization block.
  const i18n = setupI18n({
    locale: untrack(() => locale),
    messages: catalog,
  });
  setLinguiContext(i18n);
</script>

<p>{$t`Hello from an island`}</p>

Note

Pass locale from the Astro page as a prop so the island uses the same locale as the surrounding page. See Astro: Using Islands for the broader pattern.

Switching locale

setLinguiContext installs the instance once. To switch locale later, call activate or loadAndActivate on that same instance. Reactive macros pick up the change automatically.

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

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

  function switchLocale(next: SupportedLocale) {
    i18n.activate(next);
    // All $t, $plural, etc. in this tree re-render automatically.
  }
</script>

See Reactive Macros for how activate and loadAndActivate trigger re-rendering of macros like $t and $plural.

For how to resolve the initial locale from URL params, cookies, and browser headers, and how to pass it into the layout, see Locale Resolution.

Function reference

setLinguiContext

import { setLinguiContext } from "lingui-for-svelte";

function setLinguiContext(instance: I18n): LinguiContext;

Installs the Lingui instance into Svelte component context for the current subtree. Must be called inside a Svelte component. All descendant components inherit the context without prop drilling.

Returns the created LinguiContext value. The return value is rarely needed; the context is accessible to descendant components automatically.

getLinguiContext

import { getLinguiContext } from "lingui-for-svelte";

function getLinguiContext(): LinguiContext;

Reads the active Lingui context from the current Svelte component tree. Throws if no context has been set.

Compiled macro output calls this internally. You only need it when you want the raw i18n instance, for example to call i18n.activate() in a locale switcher that is not the same component that called setLinguiContext.

LinguiContext

import type { LinguiContext } from "lingui-for-svelte";

type LinguiContext = {
  i18n: I18n;
  // other fields are internal
};

The value returned by both functions. Access .i18n to use the raw Lingui instance for imperative calls. Other fields on this type are used by compiled macro output and are not part of the public API.