Reference

FluentProvider

The FluentProvider component provides context for all other components and stores of svelte-fluent.

Typically there is only a single instance of FluentProvider wrapping the top level of the application (e.g. in a __layout.svelte file in SvelteKit or similar). For specialized needs it’s possible to nest multiple FluentProvider instances.

The mandatory bundles argument takes a list of FluentBundle instances. When resolving a translation each of the provided bundles will be tried in sequence until the translation message is found making it possible to split your translations across several files and use different bundle configurations (like attached functions) for each of them.

The FluentBundle component also emits error events whenever a translation message fails to parse or render.

Example

<script>
	import { FluentProvider, Localized } from '@nubolab-ffwd/svelte-fluent';

	export let bundles;
</script>

<FluentProvider {bundles}>
	<Localized id="hello" />
</FluentProvider>
Result:
Hello, world!

Props

Name Type Default Description
bundles Iterable<FluentBundle> undefined A list (or iterable) of FluentBundle instances

Slots

Name Prop Type Description
default - - Child components of this slot use the configured bundles for translations

Events

Name Type of event details Description
error string Emitted whenever a translation message fails to parse or render

Localized

The Localized component renders a translation message and outputs it as plain text. The output can be customized by overriding the default slot of the component.

Static text example

<script>
	import { Localized } from '@nubolab-ffwd/svelte-fluent';
</script>

<Localized id="hello" />
en.ftl 
hello = Hello, world!
Result:
Hello, world!

Dynamic text with variables example

<script>
	import { Localized } from '@nubolab-ffwd/svelte-fluent';
	export let unreadEmails = 10;
</script>

<Localized id="emails" args={{ unreadEmails }} />
en.ftl 
emails =
  { $unreadEmails ->
    [one] You have one unread email.
    *[other] You have { $unreadEmails } unread emails.
  }
Result:
You have ⁨10⁩ unread emails.

Attributes example

<script>
	import { Localized } from '@nubolab-ffwd/svelte-fluent';
</script>

<Localized id="confirm" let:text let:attrs>
	<div>{text}</div>
	<div>
		<button on:click={() => alert('OK clicked')}>{attrs.ok}</button>
		<button on:click={() => alert('Cancel clicked')}>{attrs.cancel}</button>
	</div>
</Localized>
en.ftl 
confirm = Please confirm the action.
  .ok     = Ok
  .cancel = Cancel
Result:
Please confirm the action.

Attributes with variables example

<script>
	import { Localized } from '@nubolab-ffwd/svelte-fluent';
</script>

<Localized id="confirm" args={{ count: 20 }} let:text let:attrs>
	<div>{text}</div>
	<div>
		<button on:click={() => alert('OK clicked')}>{attrs.ok}</button>
		<button on:click={() => alert('Cancel clicked')}>{attrs.cancel}</button>
	</div>
</Localized>
en.ftl 
confirm = Please confirm the action for { $count } items.
  .ok     = Yes, perform action for { $count } items
  .cancel = Cancel
Result:
Please confirm the action for ⁨20⁩ items.

Props

Name Type Default Description
id string undefined Unique identifier for the translation
args Record<string, FluentVariable> undefined Arguments for interpolation

Slots & Slot props

Name Prop Type Description
default text string Translated message
default attrs Record<string, string> Attributes of the translation

Overlay (experimental)

The experimental Overlay component uses fluent.js DOM Overlays to render translation messages that contain HTML markup.

DOM overlays provide a safe mechanism for translators to use text-level markup. They also allow developers to provide functional elements that can be used in translations.

Please check the fluent.js documentation for DOM Overlays if you want to learn more.

Due to the way DOM Overlays are currently implemented in svelte-fluent there are some additional limitations to the limitations listed in the @fluent/dom wiki:

  • Updates to <Overlay/> component props and children cause a high overhead and should be minimized
  • Svelte actions (<tag use:someaction/>) won’t work correctly for children of the <Overlay/> component
  • Svelte transitions/animations (<tag transition:fade />) won’t work correctly for children of the <Overlay/> component
  • Svelte bindings (<tag bind:clientWidth={something} />) won’t work correctly for children of the <Overlay/> component
  • Event handlers (<tag on:click={handleClick} />) bound on children of the <Overlay/> component will not fire

Static text example

<script>
	import { Overlay } from '@nubolab-ffwd/svelte-fluent';
</script>

<Overlay id="info">
	<a data-l10n-name="link" href="https://example.com/">
		<!-- text from FTL file gets inserted here -->
	</a>
</Overlay>
en.ftl 
info = Read the <a data-l10n-name="link">documentation</a> for more information.
Result:

Dynamic text with variables example

<script>
	import { Overlay } from '@nubolab-ffwd/svelte-fluent';
	export let productName = 'Example Product';
</script>

<Overlay id="info" args={{ productName }}>
	<a data-l10n-name="release-notes" href="https://example.com/" target="_blank" rel="noreferrer">
		<!-- text from FTL file gets inserted here -->
	</a>
</Overlay>
en.ftl 
info =
  You can download "{ $productName }" by clicking
  on the <strong>Download</strong> button or read
  the <a data-l10n-name='release-notes'>release notes</a> to learn more.
Result:

Props

Name Type Default Description
id string undefined Unique identifier for the translation
args Record<string, FluentVariable> undefined Arguments for interpolation

Slots & Slot props

Name Prop Type Description
default text string Translated message
default attrs Record<string, string> Attributes of the translation

$localize

The $localize store allows you to use localizations in component scripts. This can be useful when interacting with browser APIs or third-party libraries.

Using the Localized and Overlay components is the preferred way to localize your application with svelte-fluent. The $localize store provides additional flexibility in situations where using the components would not be feasible.

Arguments

Name Type Default Description
id string undefined Unique identifier for the translation
args Record<string, FluentVariable> undefined Arguments for interpolation

Static text example

<script>
	import { localize } from '@nubolab-ffwd/svelte-fluent';
</script>

<button on:click={() => window.alert($localize('hello'))}>Say hello</button>
en.ftl 
hello = Hello, world!
Result:

Dynamic text with variables example

<script>
	import { localize } from '@nubolab-ffwd/svelte-fluent';
	const name = 'World';
</script>

<button on:click={() => window.alert($localize('hello', { name }))}>Say hello</button>
en.ftl 
hello = Hello, {$name}!
Result:

Attributes example

You can reference attributes of a translation message by calling $localize with both identifiers joined with a period.

In the example below this is done for the .default attribute of the prompt message by calling $localize with 'prompt.default' as the message identifier.

<script>
	import { localize } from '@nubolab-ffwd/svelte-fluent';
</script>

<button on:click={() => window.prompt($localize('prompt'), $localize('prompt.default'))}>
	Show prompt
</button>
en.ftl 
prompt = Please enter your name
	.default = Your name goes here
Result: