aymericzip/intlayer-skills/intlayer-lit

Intlayer Lit Usage

Core Philosophy

Intlayer promotes Component-Level Content Declaration. Instead of a massive global translation file, content is declared in *.content.ts files adjacent to the Lit elements that use them.

Workflow

To create a translated element, you need two files:

1. Declaration: A content file (e.g., myElement.content.ts) defining the dictionary.
2. Implementation: A LitElement (e.g., my-element.ts) using the useIntlayer controller.

Declare Content

Create a content file using t() for translations. File: src/components/myElement.content.ts

import { t, type Dictionary } from "intlayer";
const content = {
  // The 'key' must be unique and matches what you pass to useIntlayer()
  key: "my-element",
  content: {
    title: t({
      en: "Welcome",
      fr: "Bienvenue",
      es: "Hola",
    }),
  },
} satisfies Dictionary;
export default content;

Setup

• Vite and Lit

Call installIntlayer() from lit-intlayer before any custom element is registered (see the Vite and Lit guide).

useIntlayer Controller

[!IMPORTANT]

In Lit, useIntlayer takes the host element as first argument. It registers itself as a ReactiveController, so the element re-renders automatically when the locale changes.

import { LitElement, html } from "lit";
import { customElement } from "lit/decorators.js";
import { useIntlayer } from "lit-intlayer";
@customElement("my-element")
export class MyElement extends LitElement {
  private content = useIntlayer(this, "my-element");
  override render() {
    return html`
      <h1>${this.content.title}</h1>
      <!-- Return string (.value) for native attributes -->
      <img alt=${this.content.title.value} />
    `;
  }
}

useLocale Controller

import { useLocale } from "lit-intlayer";
// Inside a LitElement
private locale = useLocale(this);
// this.locale.locale, this.locale.availableLocales, this.locale.setLocale("fr")

Compiler

The Intlayer Compiler can extract all your content keys from your components, using one CLI command (npx intlayer extract) or automatically at app build.

References

• Website
• Doc

Environments

• Vite and Lit
• Astro and Lit

Concepts

• Variants
• Collections
• Compiler
• Formatters (number, currency, date, …)

Packages

• Intlayer Exports