@intlayer/docs 8.11.2 → 8.12.0-canary.0

package/docs/en-GB/intlayer_with_svelte_kit.md

@@ -1,8 +1,8 @@
 ---
 createdAt: 2025-11-20
-updatedAt: 2026-05-06
-title: SvelteKit i18n - How to translate an SvelteKit app in 2026
-description: Discover how to make your SvelteKit website multilingual. Follow the documentation to internationalise (i18n) and translate it using Server-Side Rendering (SSR).
+updatedAt: 2026-05-31
+title: "SvelteKit i18n - Complete guide to translate your app"
+description: "No more i18next. The 2026 guide to building a multilingual (i18n) SvelteKit app. Translate with AI agents and optimise bundle size, SEO and performances."
 keywords:
   - Internationalisation
   - Documentation
@@ -59,16 +59,54 @@ history:
 
 <TOC/>
 
-## What is Intlayer?
+## Why Intlayer over alternatives?
 
-**Intlayer** is an innovative, open-source internationalisation (i18n) library designed to simplify multilingual support in modern web applications. It works seamlessly with **SvelteKit's** Server-Side Rendering (SSR) capabilities.
+Compared to main solutions like `svelte-i18n` or `i18next`, Intlayer is a solution that comes with integrated optimizations such as:
 
-With Intlayer, you can:
+<AccordionGroup>
 
-- **Easily manage translations** using declarative dictionaries at the component level.
-- **Dynamically localise metadata**, routes, and content.
-- **Ensure TypeScript support** with autogenerated types.
-- **Leverage SvelteKit's SSR** for SEO-friendly internationalisation.
+<Accordion header="Full SvelteKit coverage">
+
+Intlayer is optimized to work perfectly with SvelteKit by offering **multilingual routing**, **SSR support**, and all the features needed for scaling internationalization (i18n).
+
+</Accordion>
+
+<Accordion header="Bundle size">
+
+Instead of loading massive JSON files into your pages, load only the necessary content. Intlayer helps **reduce your bundle and page sizes by up to 50%**.
+
+</Accordion>
+
+<Accordion header="Maintainability">
+
+Scoping your application's content **facilitates maintenance** for large-scale applications. You can duplicate or delete a single feature folder without the mental burden of reviewing your entire content codebase. Additionally, Intlayer is **fully typed** to ensure your content's accuracy.
+
+</Accordion>
+
+<Accordion header="AI Agent">
+
+Co-locating content **reduces the context needed** by Large Language Models (LLMs). Intlayer also comes with a suite of tools, such as a **CLI** to test for missing translations,**[LSP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/lsp.md)**, **[MCP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/mcp_server.md)**, and **[agent skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/agent_skills.md)**, to make the developer experience (DX) even smoother for AI agents.
+
+</Accordion>
+
+<Accordion header="Automation">
+
+Use automation to translate in your CI/CD pipeline using the LLM of your choice at the cost of your AI provider. Intlayer also offers a **compiler** to automate content extraction, as well as a [web platform](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md) to help **translate in the background**.
+
+</Accordion>
+
+<Accordion header="Performance">
+
+Connecting massive JSON files to components can lead to performance and reactivity issues. Intlayer optimizes your content loading at build time.
+
+</Accordion>
+
+<Accordion header="Scaling with none-dev">
+
+More than just an i18n solution, Intlayer provides an **self-hosted [visual editor](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_visual_editor.md)** and a **[full CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md)** to help you manage your multilingual content in **real-time**, making collaboration with translators, copywriters, and other team members seamless. Content can be stored locally and/or remotely.
+
+</Accordion>
+</AccordionGroup>
 
 ---
 
@@ -116,7 +154,9 @@ To get started, create a new SvelteKit project. Here is the final structure that
 └── vite.config.ts
 ```
 
-### Step 1: Install Dependencies
+<Steps>
+
+<Step number={1} title="Install Dependencies">
 
 Install the necessary packages using npm:
 
@@ -148,7 +188,9 @@ bun x intlayer init
 - **svelte-intlayer**: Provides context providers and stores for Svelte/SvelteKit.
 - **vite-intlayer**: The Vite plugin to integrate content declarations with the build process.
 
-### Step 2: Configuration of your project
+</Step>
+
+<Step number={2} title="Configuration of your project">
 
 Create a config file in your project root:
 
@@ -165,7 +207,9 @@ const config: IntlayerConfig = {
 export default config;
 ```
 
-### Step 3: Integrate Intlayer in Your Vite Configuration
+</Step>
+
+<Step number={3} title="Integrate Intlayer in Your Vite Configuration">
 
 Update your `vite.config.ts` to include the Intlayer plugin. This plugin manages the transpilation of your content files.
 
@@ -179,7 +223,9 @@ export default defineConfig({
 });
 ```
 
-### Step 4: Declare Your Content
+</Step>
+
+<Step number={4} title="Declare Your Content">
 
 Create your content declaration files anywhere in your `src` folder (e.g., `src/lib/content` or alongside your components). These files define the translatable content for your application using the `t()` function for each locale.
 
@@ -200,13 +246,15 @@ const heroContent = {
 export default heroContent;
 ```
 
-### Step 5: Utilise Intlayer in Your Components
+</Step>
+
+<Step number={5} title="Utilise Intlayer in Your Components">
 
 Now you can use the `useIntlayer` function in any Svelte component. It returns a reactive store that automatically updates when the locale changes. The function will automatically respect the current locale (both during SSR and client-side navigation).
 
 > **Note:** `useIntlayer` returns a Svelte store, so you need to use the `---
 > createdAt: 2025-11-20
-> updatedAt: 2026-05-06
+> updatedAt: 2026-05-31
 > title: How to translate an SvelteKit app – i18n guide 2026
 > description: Discover how to make your SvelteKit website multilingual. Follow the documentation to internationalise (i18n) and translate it using Server-Side Rendering (SSR).
 > keywords:
@@ -231,6 +279,10 @@ Now you can use the `useIntlayer` function in any Svelte component. It returns a
 
 # Translate your SvelteKit website using Intlayer | Internationalisation (i18n)
 
+</Step>
+
+</Steps>
+
 ## Table of Contents
 
 <TOC/>
@@ -292,7 +344,9 @@ To get started, create a new SvelteKit project. Here is the final structure that
 └── vite.config.ts
 ```
 
-### Step 1: Install Dependencies
+<Steps>
+
+<Step number={1} title="Install Dependencies">
 
 Install the necessary packages using npm:
 
@@ -324,7 +378,9 @@ bun x intlayer init
 - **svelte-intlayer**: Provides context providers and stores for Svelte/SvelteKit.
 - **vite-intlayer**: The Vite plugin to integrate content declarations with the build process.
 
-### Step 2: Configuration of your project
+</Step>
+
+<Step number={2} title="Configuration of your project">
 
 Create a config file in your project root:
 
@@ -341,7 +397,9 @@ const config: IntlayerConfig = {
 export default config;
 ```
 
-### Step 3: Integrate Intlayer in Your Vite Configuration
+</Step>
+
+<Step number={3} title="Integrate Intlayer in Your Vite Configuration">
 
 Update your `vite.config.ts` to include the Intlayer plugin. This plugin manages the transpilation of your content files.
 
@@ -355,7 +413,9 @@ export default defineConfig({
 });
 ```
 
-### Step 4: Declare Your Content
+</Step>
+
+<Step number={4} title="Declare Your Content">
 
 Create your content declaration files anywhere in your `src` folder (e.g., `src/lib/content` or alongside your components). These files define the translatable content for your application using the `t()` function for each locale.
 
@@ -376,7 +436,9 @@ const heroContent = {
 export default heroContent;
 ```
 
-### Step 5: Utilise Intlayer in Your Components
+</Step>
+
+<Step number={5} title="Utilise Intlayer in Your Components">
 
 prefix to access its reactive value (e.g., `$content.title`).
 
@@ -398,7 +460,9 @@ prefix to access its reactive value (e.g., `$content.title`).
 <div aria-label={String($content.title)}></div>
 ```
 
-### (Optional) Step 6: Set up routing
+</Step>
+
+<Step number={6} title="Set up routing" isOptional={true}>
 
 The following steps show how to set up locale-based routing in SvelteKit. This allows your URLs to include the locale prefix (e.g., `/en/about`, `/fr/about`) for better SEO and user experience.
 
@@ -423,7 +487,9 @@ The following steps show how to set up locale-based routing in SvelteKit. This a
         └── +layout.svelte         # Root layout for fonts and global styles
 ```
 
-### Step 7: Handle Server-Side Locale Detection (Hooks)
+</Step>
+
+<Step number={7} title="Handle Server-Side Locale Detection">
 
 In SvelteKit, the server needs to know the user's locale to render the correct content during SSR. We use `hooks.server.ts` to detect the locale from the URL or cookies.
 
@@ -637,7 +703,9 @@ export const prerender = true;
 </style>
 ```
 
-### (Optional) Step 8: Internationalised Links
+</Step>
+
+<Step number={8} title="Internationalised Links" isOptional={true}>
 
 For SEO, it is recommended to prefix your routes with the locale (e.g., `/en/about`, `/fr/about`). This component automatically prefixes any link with the current locale.
 
@@ -670,7 +738,9 @@ const localizedPath = getLocalizedUrl("/about", $locale);
 goto(localizedPath); // Navigates to /en/about or /fr/about depending on locale
 ```
 
-### (Optional) Step 9: Language Switcher
+</Step>
+
+<Step number={9} title="Language Switcher" isOptional={true}>
 
 To allow users to switch languages, update the URL.
 
@@ -711,7 +781,9 @@ To allow users to switch languages, update the URL.
 </style>
 ```
 
-### (Optional) Step 10: Add backend proxy
+</Step>
+
+<Step number={10} title="Add backend proxy" isOptional={true}>
 
 To add a backend proxy to your SvelteKit application, you can use the `intlayerProxy` function provided by the `vite-intlayer` plugin. This plugin will automatically detect the best locale for the user based on the URL, cookies, and browser language preferences.
 
@@ -730,7 +802,9 @@ export default defineConfig({
 });
 ```
 
-### (Optional) Step 11: Set up the intlayer editor / CMS
+</Step>
+
+<Step number={11} title="Set up the intlayer editor / CMS" isOptional={true}>
 
 To set up the intlayer editor, you must follow the [intlayer editor documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_visual_editor.md).
 
@@ -755,6 +829,10 @@ To be able to visualise the intlayer editor selector, you will have to use the c
 </div>
 ```
 
+</Step>
+
+</Steps>
+
 ### Git Configuration
 
 It is recommended to ignore the files generated by Intlayer.

package/docs/en-GB/intlayer_with_tanstack+solid.md

@@ -1,8 +1,8 @@
 ---
 createdAt: 2025-03-25
-updatedAt: 2026-05-06
-title: i18n Tanstack Start - How to translate a Tanstack Start App using Solid.js in 2026
-description: Learn how to add internationalisation (i18n) to your Tanstack Start application using Intlayer and Solid.js. Follow this comprehensive guide to make your app multi-lingual with locale-aware routing.
+updatedAt: 2026-05-31
+title: "TanStack Start + Solid i18n - Complete guide to translate your app"
+description: "No more i18next. The 2026 guide to building a multilingual (i18n) TanStack Start + Solid app. Translate with AI agents and optimise bundle size, SEO and performances."
 keywords:
   - Internationalisation
   - Documentation
@@ -37,17 +37,54 @@ history:
 
 This guide demonstrates how to integrate **Intlayer** for seamless internationalisation in Tanstack Start projects with Solid.js, locale-aware routing, TypeScript support, and modern development practices.
 
-## What is Intlayer?
+## Why Intlayer over alternatives?
 
-**Intlayer** is an innovative, open-source internationalisation (i18n) library designed to simplify multi-lingual support in modern web applications.
+Compared to main solutions like `react-i18next` or `i18next`, Intlayer is a solution that comes with integrated optimizations such as:
 
-With Intlayer, you can:
+<AccordionGroup>
 
-- **Manage translations easily** using declarative dictionaries at the component level.
-- **Localise metadata, routes, and content dynamically**.
-- **Ensure TypeScript support** with auto-generated types, improving autocompletion and error detection.
-- **Benefit from advanced features**, such as dynamic locale detection and switching.
-- **Enable locale-aware routing** with Tanstack Start's file-based routing system.
+<Accordion header="Full TanStack Start coverage">
+
+Intlayer is optimized to work perfectly with TanStack Start and Solid by offering **multilingual routing**, **sitemap**, and all the features needed for scaling internationalization (i18n).
+
+</Accordion>
+
+<Accordion header="Bundle size">
+
+Instead of loading massive JSON files into your pages, load only the necessary content. Intlayer helps **reduce your bundle and page sizes by up to 50%**.
+
+</Accordion>
+
+<Accordion header="Maintainability">
+
+Scoping your application's content **facilitates maintenance** for large-scale applications. You can duplicate or delete a single feature folder without the mental burden of reviewing your entire content codebase. Additionally, Intlayer is **fully typed** to ensure your content's accuracy.
+
+</Accordion>
+
+<Accordion header="AI Agent">
+
+Co-locating content **reduces the context needed** by Large Language Models (LLMs). Intlayer also comes with a suite of tools, such as a **CLI** to test for missing translations,**[LSP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/lsp.md)**, **[MCP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/mcp_server.md)**, and **[agent skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/agent_skills.md)**, to make the developer experience (DX) even smoother for AI agents.
+
+</Accordion>
+
+<Accordion header="Automation">
+
+Use automation to translate in your CI/CD pipeline using the LLM of your choice at the cost of your AI provider. Intlayer also offers a **compiler** to automate content extraction, as well as a [web platform](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md) to help **translate in the background**.
+
+</Accordion>
+
+<Accordion header="Performance">
+
+Connecting massive JSON files to components can lead to performance and reactivity issues. Intlayer optimizes your content loading at build time.
+
+</Accordion>
+
+<Accordion header="Scaling with none-dev">
+
+More than just an i18n solution, Intlayer provides an **self-hosted [visual editor](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_visual_editor.md)** and a **[full CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md)** to help you manage your multilingual content in **real-time**, making collaboration with translators, copywriters, and other team members seamless. Content can be stored locally and/or remotely.
+
+</Accordion>
+</AccordionGroup>
 
 ---
 
@@ -85,11 +122,15 @@ With Intlayer, you can:
 
 See the [Application Template](https://github.com/aymericzip/intlayer-tanstack-start-solid-template) on GitHub.
 
-### Step 1: Project Creation
+<Steps>
+
+<Step number={1} title="Project Creation">
 
 First, create a new TanStack Start project following the [Start New Project](https://tanstack.com/start/latest/docs/framework/solid/quick-start) guide on the TanStack Start website.
 
-### Step 2: Install Intlayer Packages
+</Step>
+
+<Step number={2} title="Install Intlayer Packages">
 
 Install the necessary packages using your preferred package manager:
 
@@ -127,7 +168,9 @@ bun x intlayer init
 - **vite-intlayer**
   Includes the Vite plugin to integrate Intlayer with the [Vite bundler](https://vite.dev/guide/why.html#why-bundle-for-production), as well as middleware to detect the user's preferred locale, manage cookies, and handle URL redirection.
 
-### Step 3: Configuration of your project
+</Step>
+
+<Step number={3} title="Configuration of your project">
 
 Create a configuration file to set up the languages of your application:
 
@@ -148,7 +191,9 @@ export default config;
 
 > Through this configuration file, you can configure localised URLs, middleware redirection, cookie names, the location and extension of your content declarations, disable Intlayer logs in the console, and more. For a complete list of available parameters, refer to the [configuration documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/configuration.md).
 
-### Step 4: Integrate Intlayer in your Vite Configuration
+</Step>
+
+<Step number={4} title="Integrate Intlayer in your Vite Configuration">
 
 Add the intlayer plugin in your configuration:
 
@@ -176,7 +221,9 @@ export default defineConfig({
 
 > The `intlayer()` Vite plugin is used to integrate Intlayer with Vite. It ensures the building of content declaration files and monitors them in development mode. It defines the Intlayer environment variables within the Vite application. Additionally, it provides aliases to reduce performance overhead.
 
-### Step 5: Create the Root Layout
+</Step>
+
+<Step number={5} title="Create the Root Layout">
 
 Configure your root layout to support internationalisation by using `useParams` to detect the current locale and setting the `lang` and `dir` attributes on the `html` tag.
 
@@ -217,7 +264,9 @@ const RootComponent: ParentComponent = (props) => {
 };
 ```
 
-### Step 6: Create the Locale Layout (Optional)
+</Step>
+
+<Step number={6} title="Create the Locale Layout">
 
 Create a layout that handles the locale prefix and performs validation. This layout will ensure only valid locales are processed.
 
@@ -252,7 +301,9 @@ export const Route = createFileRoute("/{-$locale}")({
 > For `'prefix-all'` mode, you might prefer switching the slot to `$locale`.
 > For `'no-prefix'` or `'search-params'` mode, you can remove the slot entirely.
 
-### Step 7: Declare Your Content
+</Step>
+
+<Step number={7} title="Declare Your Content">
 
 Create and manage your content declarations to store translations:
 
@@ -298,7 +349,9 @@ export default appContent;
 
 > For more details, refer to the [content declaration documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/dictionary/content_file.md).
 
-### Step 8: Utilise Locale-Aware Components and Hooks
+</Step>
+
+<Step number={8} title="Utilise Locale-Aware Components and Hooks">
 
 Create a `LocalizedLink` component for locale-aware navigation:
 
@@ -378,7 +431,9 @@ export const useLocalizedNavigate = () => {
 };
 ```
 
-### Step 9: Use Intlayer in Your Pages
+</Step>
+
+<Step number={9} title="Use Intlayer in Your Pages">
 
 Access your content dictionaries throughout your application:
 
@@ -421,7 +476,9 @@ function RouteComponent() {
 >
 > To learn more about the `useIntlayer` hook, refer to the [documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/packages/solid-intlayer/useIntlayer.md).
 
-### Step 10: Create a Locale Switcher Component
+</Step>
+
+<Step number={10} title="Create a Locale Switcher Component">
 
 Create a component to allow users to change languages:
 
@@ -465,7 +522,9 @@ export default LocaleSwitcher;
 >
 > To learn more about the `useLocale` hook, refer to the [documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/packages/solid-intlayer/useLocale.md).
 
-### Step 11: Management of HTML Attributes
+</Step>
+
+<Step number={11} title="Management of HTML Attributes">
 
 As seen in Step 5, you can manage the `lang` and `dir` attributes of the `html` tag by using `useParams` in your root component. This ensures that the correct attributes are set on both the server and client.
 
@@ -484,7 +543,9 @@ const RootComponent: ParentComponent = (props) => {
 
 ---
 
-### Step 12: Add Middleware (Optional)
+</Step>
+
+<Step number={12} title="Add Middleware">
 
 You can also use the `intlayerProxy` to add server-side routing to your application. This plugin will automatically detect the current locale based on the URL and set the appropriate locale cookie. If no locale is specified, the plugin will determine the most appropriate locale based on the user's browser language preferences. If no locale is detected, it will redirect to the default locale.
 
@@ -515,7 +576,9 @@ export default defineConfig({
 
 ---
 
-### Step 13: Internationalise Your Metadata (Optional)
+</Step>
+
+<Step number={13} title="Internationalise Your Metadata">
 
 You can also use the `getIntlayer` function to access your content dictionaries within the `head` loader for locale-aware metadata:
 
@@ -562,7 +625,9 @@ export const Route = createFileRoute("/{-$locale}/")({
 
 ---
 
-### Step 14: Retrieve the locale in your server actions (Optional)
+</Step>
+
+<Step number={14} title="Retrieve the locale in your server actions">
 
 You may want to access the current locale from within your server actions or API endpoints.
 You can do this using the `getLocale` helper from `intlayer`.
@@ -599,7 +664,9 @@ export const getLocaleServer = createServerFn().handler(async () => {
 
 ---
 
-### Step 15: Manage not found pages (Optional)
+</Step>
+
+<Step number={15} title="Manage not found pages">
 
 When a user visits a non-existent page, you can display a custom not found page and the locale prefix can impact the way the not found page is triggered.
 
@@ -673,7 +740,9 @@ export const Route = createFileRoute("/{-$locale}/$")({
 });
 ```
 
-### (Optional) Step 16: Extract the content from your components
+</Step>
+
+<Step number={16} title="Extract the content from your components" isOptional={true}>
 
 If you have an existing codebase, transforming thousands of files can be time-consuming.
 
@@ -786,7 +855,9 @@ bun run build # Or bun run dev
 
 ---
 
-### Step 16: Generate Sitemap (Optional)
+</Step>
+
+<Step number={16} title="Generate Sitemap">
 
 Intlayer comes with a built-in sitemap generator to help you create a sitemap for your application easily. It handles localised routes and adds the necessary metadata for search engines.
 
@@ -857,7 +928,9 @@ export const Route = createFileRoute("/sitemap.xml")({
 
 ---
 
-### Step 17: Configure TypeScript (Optional)
+</Step>
+
+<Step number={17} title="Configure TypeScript">
 
 Intlayer uses module augmentation to get the benefits of TypeScript and make your codebase stronger.
 
@@ -875,6 +948,10 @@ Ensure your TypeScript configuration includes the auto-generated types:
 
 ---
 
+</Step>
+
+</Steps>
+
 ### Git Configuration
 
 It is recommended to ignore the files generated by Intlayer. This allows you to avoid committing them to your Git repository.