@intlayer/docs 9.3.0 → 9.3.1

package/docs/en-GB/interest_of_intlayer.md

@@ -207,7 +207,7 @@ export const ComponentExample = () => {
 This approach allows you to:
 
 1. **Increase the speed of development**
-   - `.content.{{ts|mjs|cjs|json}}` files can be created using a VSCode extension
+   - `.content.{ts|js|mjs|cjs|json|tsx|jsx|md|mdx|yaml|yml}` files can be created using a VSCode extension
    - Autocompletion AI tools in your IDE (such as GitHub Copilot) can help you declare your content, reducing copy/paste
 
 2. **Clean your codebase**
@@ -231,27 +231,27 @@ This approach allows you to:
 
 ## Additional features of Intlayer
 
-| Feature                                                                                                                   | Description                                                                                                                                                                                                                                                                                                                                                                                  |
-| ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/frameworks.png?raw=true)                          | **Cross-Frameworks Support**<br><br>Intlayer is compatible with all major frameworks and libraries, including Next.js, React, Vite, Vue.js, Nuxt, Preact, Express, and more.                                                                                                                                                                                                                 |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/javascript_content_management.jpg?raw=true)       | **JavaScript-Powered Content Management**<br><br>Harness the flexibility of JavaScript to define and manage your content efficiently. <br><br> - [Content declaration](https://intlayer.org/doc/concept/content)                                                                                                                                                                             |
-| <img src="https://github.com/aymericzip/intlayer/blob/main/docs/assets/compiler.jpg?raw=true" alt="Feature" width="700">  | **Compiler**<br><br>The Intlayer Compiler extract automatically the content from the components and generate the dictionary files.<br><br> - [Compiler](https://intlayer.org/doc/compiler)                                                                                                                                                                                                   |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/per_locale_content_declaration_file.png?raw=true) | **Per-Locale Content Declaration File**<br><br>Speed up your development by declaring your content once, before auto generation.<br><br> - [Per-Locale Content Declaration File](https://intlayer.org/doc/concept/per-locale-file)                                                                                                                                                           |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/autocompletion.png?raw=true)                      | **Type-Safe Environment**<br><br>Leverage TypeScript to ensure your content definitions and code are error-free, while also benefiting from IDE autocompletion.<br><br> - [TypeScript configuration](https://intlayer.org/doc/environment/vite-and-react#configure-typescript)                                                                                                               |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/config_file.png?raw=true)                         | **Simplified Setup**<br><br>Get up and running quickly with minimal configuration. Adjust settings for internationalization, routing, AI, build, and content handling with ease. <br><br> - [Explore Next.js integration](https://intlayer.org/doc/environment/nextjs)                                                                                                                       |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/content_retrieval.png?raw=true)                   | **Simplified Content Retrieval**<br><br>No need to call your `t` function for each piece of content. Retrieve all your content directly using a single hook.<br><br> - [React integration](https://intlayer.org/doc/environment/create-react-app)                                                                                                                                            |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/server_component.png?raw=true)                    | **Consistent Server Component Implementation**<br><br>Perfectly suited for Next.js server components, use the same implementation for both client and server components, no need to pass your `t` function across each server component. <br><br> - [Server Components](https://intlayer.org/doc/environment/nextjs#step-7-utilize-content-in-your-code)                                     |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/file_tree.png?raw=true)                           | **Organized Codebase**<br><br>Keep your codebase more organized: 1 component = 1 dictionary in the same folder. Translations close to their respective components enhance maintainability and clarity. <br><br> - [How Intlayer works](https://intlayer.org/doc/concept/how-works-intlayer)                                                                                                  |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/url_routing.png?raw=true)                         | **Enhanced Routing**<br><br>Full support of app routing, adapting seamlessly to complex application structures, for Next.js, React, Vite, Vue.js, etc.<br><br> - [Explore Next.js integration](https://intlayer.org/doc/environment/nextjs)                                                                                                                                                  |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/markdown.png?raw=true)                            | **Markdown Support**<br><br>Import and interpret locale files and remote Markdown for multilingual content like privacy policies, documentation, etc. Interpret and make Markdown metadata accessible in your code.<br><br> - [Content files](https://intlayer.org/doc/concept/content/file)                                                                                                 |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/visual_editor.png?raw=true)                       | **Free Visual Editor & CMS**<br><br>A free visual editor and CMS are available for content writers, removing the need for a localization platform. Keep your content synchronized using Git, or externalize it totally or partially with the CMS.<br><br> - [Intlayer Editor](https://intlayer.org/doc/concept/editor) <br> - [Intlayer CMS](https://intlayer.org/doc/concept/cms)           |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/bundle.png?raw=true)                              | **Tree-shakable Content**<br><br>Tree-shakable content, reducing the size of the final bundle. Loads content per component, excluding any unused content from your bundle. Supports lazy loading to enhance app loading efficiency. <br><br> - [App build optimization](https://intlayer.org/doc/concept/how-works-intlayer#app-build-optimization)                                          |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/static_rendering.png?raw=true)                    | **Static Rendering**<br><br>Doesn't block Static Rendering. <br><br> - [Next.js integration](https://intlayer.org/doc/environment/nextjs)                                                                                                                                                                                                                                                    |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/AI_translation.png?raw=true)                      | **AI-Powered Translation**<br><br>Transform your website into 231 languages with just one click using Intlayer's advanced AI-powered translation tools using your own AI provider/API key. <br><br> - [CI/CD integration](https://intlayer.org/doc/concept/ci-cd) <br> - [Intlayer CLI](https://intlayer.org/doc/concept/cli) <br> - [Auto fill](https://intlayer.org/doc/concept/auto-fill) |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/mcp.png?raw=true)                                 | **MCP Server Integration**<br><br>Provides an MCP (Model Context Protocol) server for IDE automation, enabling seamless content management and i18n workflows directly within your development environment. <br><br> - [MCP Server](https://github.com/aymericzip/intlayer/blob/main/docs/en/mcp_server.md)                                                                                  |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/vscode_extension.png?raw=true)                    | **VSCode Extension**<br><br>Intlayer provides a VSCode extension to help you manage your content and translations, building your dictionaries, translating your content, and more. <br><br> - [VSCode Extension](https://intlayer.org/doc/vs-code-extension)                                                                                                                                 |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/interoperability.png?raw=true)                    | **Interoperability**<br><br>Allows interoperability with react-i18next, next-i18next, next-intl, and react-intl. <br><br> - [Intlayer and react-intl](https://intlayer.org/blog/intlayer-with-react-intl) <br> - [Intlayer and next-intl](https://intlayer.org/blog/intlayer-with-next-intl) <br> - [Intlayer and next-i18next](https://intlayer.org/blog/intlayer-with-next-i18next)        |
-| Testing Missing Translations (CLI/CI)                                                                                     | ✅ CLI: npx intlayer content test (CI-friendly audit)                                                                                                                                                                                                                                                                                                                                        |
+| Feature                                                                                                                   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| ------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/frameworks.png?raw=true)                          | **Cross-Frameworks Support**<br><br>Intlayer is compatible with all major frameworks and libraries, including Next.js, React, Vite, Vue.js, Nuxt, Preact, Express, and more.                                                                                                                                                                                                                                                                                    |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/javascript_content_management.jpg?raw=true)       | **JavaScript-Powered Content Management**<br><br>Harness the flexibility of JavaScript to define and manage your content efficiently. <br><br> - [Content declaration](https://intlayer.org/doc/concept/content)                                                                                                                                                                                                                                                |
+| <img src="https://github.com/aymericzip/intlayer/blob/main/docs/assets/compiler.jpg?raw=true" alt="Feature" width="700">  | **Compiler**<br><br>The Intlayer Compiler extract automatically the content from the components and generate the dictionary files.<br><br> - [Compiler](https://intlayer.org/doc/compiler)                                                                                                                                                                                                                                                                      |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/per_locale_content_declaration_file.png?raw=true) | **Per-Locale Content Declaration File**<br><br>Speed up your development by declaring your content once, before auto generation.<br><br> - [Per-Locale Content Declaration File](https://intlayer.org/doc/concept/per-locale-file)                                                                                                                                                                                                                              |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/autocompletion.png?raw=true)                      | **Type-Safe Environment**<br><br>Leverage TypeScript to ensure your content definitions and code are error-free, while also benefiting from IDE autocompletion.<br><br> - [TypeScript configuration](https://intlayer.org/doc/environment/vite-and-react#configure-typescript)                                                                                                                                                                                  |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/config_file.png?raw=true)                         | **Simplified Setup**<br><br>Get up and running quickly with minimal configuration. Adjust settings for internationalization, routing, AI, build, and content handling with ease. <br><br> - [Explore Next.js integration](https://intlayer.org/doc/environment/nextjs)                                                                                                                                                                                          |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/content_retrieval.png?raw=true)                   | **Simplified Content Retrieval**<br><br>No need to call your `t` function for each piece of content. Retrieve all your content directly using a single hook.<br><br> - [React integration](https://intlayer.org/doc/environment/create-react-app)                                                                                                                                                                                                               |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/server_component.png?raw=true)                    | **Consistent Server Component Implementation**<br><br>Perfectly suited for Next.js server components, use the same implementation for both client and server components, no need to pass your `t` function across each server component. <br><br> - [Server Components](https://intlayer.org/doc/environment/nextjs#step-7-utilize-content-in-your-code)                                                                                                        |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/file_tree.png?raw=true)                           | **Organized Codebase**<br><br>Keep your codebase more organized: 1 component = 1 dictionary in the same folder. Translations close to their respective components enhance maintainability and clarity. <br><br> - [How Intlayer works](https://intlayer.org/doc/concept/how-works-intlayer)                                                                                                                                                                     |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/url_routing.png?raw=true)                         | **Enhanced Routing**<br><br>Full support of app routing, adapting seamlessly to complex application structures, for Next.js, React, Vite, Vue.js, etc.<br><br> - [Explore Next.js integration](https://intlayer.org/doc/environment/nextjs)                                                                                                                                                                                                                     |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/markdown.png?raw=true)                            | **Markdown Support**<br><br>Import and interpret locale files and remote Markdown for multilingual content like privacy policies, documentation, etc. Interpret and make Markdown metadata accessible in your code.<br><br> - [Content files](https://intlayer.org/doc/concept/content/file)                                                                                                                                                                    |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/visual_editor.png?raw=true)                       | **Free Visual Editor & CMS**<br><br>A free visual editor and CMS are available for content writers, removing the need for a localization platform. Keep your content synchronized using Git, or externalize it totally or partially with the CMS.<br><br> - [Intlayer Editor](https://intlayer.org/doc/concept/editor) <br> - [Intlayer CMS](https://intlayer.org/doc/concept/cms)                                                                              |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/bundle.png?raw=true)                              | **Tree-shakable Content**<br><br>Tree-shakable content, reducing the size of the final bundle. Loads content per component, excluding any unused content from your bundle. Supports lazy loading to enhance app loading efficiency. <br><br> - [App build optimization](https://intlayer.org/doc/concept/how-works-intlayer#app-build-optimization)                                                                                                             |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/static_rendering.png?raw=true)                    | **Static Rendering**<br><br>Doesn't block Static Rendering. <br><br> - [Next.js integration](https://intlayer.org/doc/environment/nextjs)                                                                                                                                                                                                                                                                                                                       |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/AI_translation.png?raw=true)                      | **AI-Powered Translation**<br><br>Transform your website into 231 languages with just one click using Intlayer's advanced AI-powered translation tools using your own AI provider/API key. <br><br> - [CI/CD integration](https://intlayer.org/doc/concept/ci-cd) <br> - [Intlayer CLI](https://intlayer.org/doc/concept/cli) <br> - [Auto fill](https://intlayer.org/doc/concept/auto-fill)                                                                    |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/mcp.png?raw=true)                                 | **MCP Server Integration**<br><br>Provides an MCP (Model Context Protocol) server for IDE automation, enabling seamless content management and i18n workflows directly within your development environment. <br><br> - [MCP Server](https://github.com/aymericzip/intlayer/blob/main/docs/en/mcp_server.md)                                                                                                                                                     |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/vscode_extension.png?raw=true)                    | **VSCode Extension**<br><br>Intlayer provides a VSCode extension to help you manage your content and translations, building your dictionaries, translating your content, and more. <br><br> - [VSCode Extension](https://intlayer.org/doc/vs-code-extension)                                                                                                                                                                                                    |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/interoperability.png?raw=true)                    | **Interoperability**<br><br>Allows interoperability with react-i18next, next-i18next, next-intl, and react-intl. <br><br> - [Intlayer and react-intl](https://intlayer.org/blog/intlayer-with-react-intl) <br> - [Intlayer and next-intl](https://intlayer.org/blog/intlayer-with-next-intl) <br> - [Intlayer and next-i18next](https://intlayer.org/blog/intlayer-with-next-i18next) <br> - [Intlayer compat adapters](https://intlayer.org/doc/compatibility) |
+| Testing Missing Translations (CLI/CI)                                                                                     | ✅ CLI: npx intlayer content test (CI-friendly audit)                                                                                                                                                                                                                                                                                                                                                                                                           |
 
 ## Comparison of Intlayer with other solutions
 
@@ -290,3 +290,5 @@ GitHub stars are a strong indicator of a project's popularity, community trust,
 `intlayer` can also help to manage your `react-intl`, `react-i18next`, `next-intl`, `next-i18next`, and `vue-i18n` namespaces.
 
 Using `intlayer`, you can declare your content in the format of your favorite i18n library, and intlayer will generate your namespaces in the location of your choice (example: `/messages/{{locale}}/{{namespace}}.json`).
+
+If you want to keep using the API of your current i18n library, `intlayer` also provides **compat adapters**: packages exposing the exact same API as `react-i18next`, `next-intl`, `react-intl`, `vue-i18n`, and more, but served by Intlayer dictionaries. This lets you migrate progressively without rewriting your code. See the [Compat Adapters documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/compat/index.md).

package/docs/en-GB/intlayer_with_svelte_kit.md

@@ -404,7 +404,7 @@ export const getLocale = (event: RequestEvent): Locale => {
 };
 ```
 
-> `getLocaleFromStorage` will check the locale from header or cookie depending on your configuration. See [Configuration](https://intlayer.org/doc/configuration) for more details.
+> `getLocaleFromStorage` will check the locale from header or cookie depending on your configuration. See [Configuration](https://intlayer.org/doc/concept/configuration) for more details.
 
 > The `localeDetector` function will process the `Accept-Language` header and return the best match.
 

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

@@ -253,19 +253,21 @@ import {
   HeadContent,
   Scripts,
   createRootRouteWithContext,
+  getRouteApi,
 } from "@tanstack/solid-router";
 import { HydrationScript } from "solid-js/web";
 import { Suspense, type ParentComponent } from "solid-js";
 import { IntlayerProvider } from "solid-intlayer";
 import { defaultLocale, getHTMLTextDir } from "intlayer";
-import { Route as LocaleRoute } from "./{-$locale}/route";
+
+const localeRoute = getRouteApi("/{-$locale}");
 
 export const Route = createRootRouteWithContext()({
   shellComponent: RootComponent,
 });
 
 const RootComponent: ParentComponent = (props) => {
-  const params = LocaleRoute.useParams();
+  const params = localeRoute.useParams();
   const locale = params()?.locale ?? defaultLocale;
 
   return (
@@ -551,7 +553,7 @@ As seen in Step 5, you can manage the `lang` and `dir` attributes of the `html`
 
 ```tsx fileName="src/routes/__root.tsx"
 const RootComponent: ParentComponent = (props) => {
-  const params = LocaleRoute.useParams();
+  const params = localeRoute.useParams();
   const locale = params()?.locale ?? defaultLocale;
 
   return (

package/docs/en-GB/intlayer_with_tanstack.md

@@ -270,13 +270,15 @@ Configure your root layout to support internationalisation by using `useParams`
 ```tsx fileName="src/routes/__root.tsx"
 import {
   createRootRouteWithContext,
+  getRouteApi,
   HeadContent,
   Scripts,
 } from "@tanstack/react-router";
 import { defaultLocale, getHTMLTextDir } from "intlayer";
 import { type ReactNode } from "react";
 import { IntlayerProvider } from "react-intlayer";
-import { Route as LocaleRoute } from "./{-$locale}/route";
+
+const localeRoute = getRouteApi("/{-$locale}");
 
 export const Route = createRootRouteWithContext<{}>()({
   head: () => ({
@@ -298,7 +300,7 @@ export const Route = createRootRouteWithContext<{}>()({
 });
 
 function RootDocument({ children }: { children: ReactNode }) {
-  const params = LocaleRoute.useParams();
+  const params = localeRoute.useParams();
   const locale = params?.locale ?? defaultLocale;
 
   return (
@@ -631,7 +633,7 @@ As seen in Step 5, you can manage the `lang` and `dir` attributes of the `html`
 
 ```tsx fileName="src/routes/__root.tsx"
 function RootDocument({ children }: { children: ReactNode }) {
-  const params = LocaleRoute.useParams();
+  const params = localeRoute.useParams();
   const locale = params?.locale ?? defaultLocale;
 
   return (

package/docs/en-GB/lsp.md

@@ -1,12 +1,14 @@
 ---
 createdAt: 2025-06-07
-updatedAt: 2026-05-31
+updatedAt: 2026-08-10
 title: Intlayer LSP Server
-description: Learn how the Intlayer Language Server provides Go-to-Definition and other IDE features for useIntlayer, getIntlayer, and related calls across all supported editors.
+description: Learn how the Intlayer Language Server brings Go-to-Definition, Find References, hover previews, key autocompletion, and diagnostics to your IDE and AI agent.
 keywords:
   - LSP
   - Language Server
   - Go to Definition
+  - Autocompletion
+  - Diagnostics
   - IDE
   - Intlayer
   - VS Code
@@ -16,6 +18,9 @@ slugs:
   - doc
   - lsp
 history:
+  - version: 9.1.3
+    date: 2026-08-10
+    changes: "Add Find References, hover, autocompletion and diagnostics"
   - version: 8.12.0
     date: 2026-06-01
     changes: "Release LSP"
@@ -24,48 +29,47 @@ author: aymericzip
 
 # Intlayer LSP Server
 
-The **Intlayer Language Server** is a [Language Server Protocol (LSP)](https://microsoft.github.io/language-server-protocol/) implementation that enhances your IDE with Intlayer-aware intelligence. It currently provides **Go to Definition** for dictionary key calls, letting you jump straight from `useIntlayer("my-key")` in your component to the `.content.ts` file that declares it.
+The **Intlayer Language Server** is a [Language Server Protocol (LSP)](https://microsoft.github.io/language-server-protocol/) implementation that makes your IDE — and your AI agent — Intlayer-aware. It connects a call like `useIntlayer("home")` to the `.content.ts` file that declares it, in both directions.
 
 ---
 
-## Why Use the LSP?
+## Features
 
-When you use Intlayer, the connection between a call like `useIntlayer("homepage")` and its declaration in `src/homepage.content.ts` is implicit. Without tooling, you must search for the file manually. The LSP makes that link explicit:
+| Feature                 | Shortcut            | What it does                                                                                       |
+| ----------------------- | ------------------- | -------------------------------------------------------------------------------------------------- |
+| **Go to Definition**    | `F12` / `Cmd+Click` | Jump from a dictionary key or a field usage to its declaration in the content file                 |
+| **Find All References** | `Shift+F12`         | From a content file, list every call site that uses that key or field                              |
+| **Hover**               | hover the cursor    | Preview a dictionary's fields, or a field's translated value, without leaving the file             |
+| **Autocompletion**      | `"` `'` `` ` `` `.` | Suggest declared dictionary keys inside a getter, and content fields after `.` or in destructuring |
+| **Diagnostics**         | automatic           | Warn when a key is not declared in any content file                                                |
 
-**AI agent awareness**
+Two extra behaviours are worth knowing:
 
-AI coding agents (Cursor, Windsurf, GitHub Copilot, Claude Code, Codex) rely on the language server to resolve symbols and understand cross-file relationships. With the Intlayer LSP running, agents can follow `useIntlayer("key")` back to its declaration, giving them accurate context about available content keys, the shape of each dictionary, and which files to read or edit.
+- **Merged dictionaries** — a key split across several content files returns one result per file, so you can navigate to every declaration.
+- **Monorepo-aware** — the server resolves the _closest_ `intlayer.config.*` to each file, so several projects in one workspace each get their own dictionaries.
 
-**Jump to Definition**
+### Supported calls
 
-Place your cursor on any dictionary key string inside a supported getter call and press `F12` (or `Cmd/Ctrl+Click`). The editor opens the content declaration file and positions the cursor on the `key:` line.
+The key is read either from a positional string argument or from an options object (`{ namespace }`, `{ id }`).
 
-**Merged dictionary support**
+| Library                     | Callers                                                  |
+| --------------------------- | -------------------------------------------------------- |
+| **Intlayer**                | `useIntlayer`, `getIntlayer`                             |
+| **i18next / react-i18next** | `useTranslation`, `getFixedT`, `t`, `Trans`              |
+| **next-intl / use-intl**    | `useTranslations`, `getTranslations`, `createTranslator` |
+| **react-intl**              | `formatMessage`, `FormattedMessage`                      |
+| **Lingui**                  | `useLingui`, `t`, `Trans`, `_`                           |
+| **vue-i18n**                | `useI18n`                                                |
 
-A key can be split across multiple content files (Intlayer merges them). The server returns one `Location` per source file so you can navigate to every declaration.
+This works for every `*-intlayer` package (`next-intlayer`, `react-intlayer`, `vue-intlayer`, `svelte-intlayer`, `solid-intlayer`, `preact-intlayer`, `angular-intlayer`, `lit-intlayer`, `express-intlayer`, `hono-intlayer`, `fastify-intlayer`, `intlayer`), and for the compat adapter packages that let you keep your existing i18n syntax.
 
-**Works everywhere**
-
-Supports all `*-intlayer` packages (`next-intlayer`, `react-intlayer`, `vue-intlayer`, `svelte-intlayer`, `solid-intlayer`, `preact-intlayer`, `angular-intlayer`, `lit-intlayer`, `express-intlayer`, `hono-intlayer`, `fastify-intlayer`, `adonis-intlayer`, `intlayer`).
-
-### Supported getter calls
-
-The server detects the following function calls and extracts the first string-literal argument as the dictionary key:
-
-| Function      | Example                       |
-| ------------- | ----------------------------- |
-| `useIntlayer` | `useIntlayer("hero")`         |
-| `getIntlayer` | `getIntlayer("hero", locale)` |
-
-TypeScript generics and extra arguments are ignored — only the key string matters.
-
-> `useDictionary` and `getDictionary` take an already-imported `Dictionary` object as their first argument rather than a string key, so they do not benefit from Go-to-Definition and are not tracked by the server.
+> Dictionaries are read from the build output, so run `npx intlayer build` — or keep your dev server running — to give the server something to resolve.
 
 ---
 
 ## Installation
 
-The LSP server is distributed as part of `@intlayer/lsp`:
+The server ships as the `intlayer-lsp` binary in `@intlayer/lsp`:
 
 ```bash packageManager="npm"
 npm install --save-dev @intlayer/lsp
@@ -83,43 +87,43 @@ pnpm add --save-dev @intlayer/lsp
 bun add --dev @intlayer/lsp
 ```
 
-The package exposes the `intlayer-lsp` binary, which editors use as the server executable.
+Install it globally instead (`npm install -g @intlayer/lsp`) if your editor needs `intlayer-lsp` on the `PATH` — this is the case for the Claude Code plugin and for any configuration below that calls the binary directly.
 
 ---
 
-## Setup as a Claude Code Plugin
+## Setup
 
-The Intlayer LSP is available as a **Claude Code plugin** hosted directly in the Intlayer GitHub repository. Installing it gives Claude Code native Go-to-Definition awareness for all your `useIntlayer` / `getIntlayer` calls.
+<Tabs defaultTab="vscode">
+  <Tab label="VS Code" value="vscode">
 
-### 1. Install the language server binary
+Install the [Intlayer VS Code extension](https://marketplace.visualstudio.com/items?itemName=Intlayer.intlayer-vs-code-extension). The language server is bundled since v8.12.0 and starts automatically — **no configuration required**.
 
-```bash packageManager="npm"
-npm install -g @intlayer/lsp
-```
+See the [VS Code extension documentation](https://intlayer.org/doc/vs-code-extension) for its other features.
 
-```bash packageManager="yarn"
-yarn global add @intlayer/lsp
-```
+  </Tab>
+  <Tab label="Cursor / Windsurf" value="cursor">
 
-```bash packageManager="pnpm"
-pnpm add -g @intlayer/lsp
-```
+[Cursor](https://www.cursor.com/) and [Windsurf](https://windsurf.com/) are VS Code forks and use the same extension ecosystem. Install the [Intlayer VS Code extension](https://marketplace.visualstudio.com/items?itemName=Intlayer.intlayer-vs-code-extension) once and the server activates automatically — **no configuration required**.
+
+  </Tab>
+  <Tab label="Claude Code" value="claude-code">
 
-This puts the `intlayer-lsp` binary on your PATH, which is what the plugin's `lspServers` entry invokes.
+Intlayer ships a **Claude Code plugin** hosted in the Intlayer repository. It gives Claude Code real symbol resolution for your dictionary keys instead of falling back to `grep`.
 
-### 2. Register the Intlayer marketplace and install the plugin
+Put the binary on your `PATH`, then register the marketplace and install the plugin:
 
 ```bash
+npm install -g @intlayer/lsp
+
 claude plugin marketplace add intlayer@github:aymericzip/intlayer
 claude plugin install intlayer-lsp@intlayer
-claude plugin enable intlayer-lsp@intlayer
 ```
 
-Claude Code will add `"intlayer-lsp@intlayer": true` to your `enabledPlugins` and automatically start the language server on the supported file types (`.ts`, `.tsx`, `.js`, `.jsx`, `.vue`, `.svelte`).
+`install` also enables the plugin. **Restart Claude Code** — language servers are loaded at startup, so the plugin has no effect until then.
 
-### 3. Enable the LSP tool (if not already active)
+Claude Code then starts the server on `.ts`, `.tsx`, `.js`, `.jsx`, `.vue`, `.astro` and `.svelte` files, and uses `goToDefinition`, `findReferences` and `hover` when navigating your code.
 
-Some Claude Code versions require the LSP feature flag to be set. Add the following to your `~/.claude/settings.json` if Go-to-Definition isn't working after installation:
+If Go-to-Definition still does nothing, your Claude Code version may gate the LSP tool behind a flag:
 
 ```json fileName="~/.claude/settings.json"
 {
@@ -129,61 +133,10 @@ Some Claude Code versions require the LSP feature flag to be set. Add the follow
 }
 ```
 
-Restart Claude Code — it will now use `goToDefinition`, `findReferences`, and other LSP operations when navigating your Intlayer codebase instead of falling back to `grep`.
-
----
-
-## Setup in VS Code (via extension — recommended)
-
-If you have the [Intlayer VS Code extension](https://marketplace.visualstudio.com/items?itemName=Intlayer.intlayer-vs-code-extension) installed, the language server starts automatically. No additional configuration is required. The LSP is directly integrated in the VSCode extension since v8.12.0.
-
-> See the [VS Code extension documentation](https://intlayer.org/doc/vs-code-extension) for installation and other features.
-
----
-
-## Manual Setup in VS Code
-
-If you are not using the Intlayer extension, you can wire up the language server manually using a generic LSP client extension such as [**vscode-glspc**](https://marketplace.visualstudio.com/items?itemName=sibiraj-s.vscode-scss-formatter) or by writing your own small extension. The recommended approach is to use the Intlayer extension.
-
-For reference, the server launches via the `intlayer-lsp` binary over stdio:
-
-```json fileName=".vscode/settings.json"
-{
-  "intlayer.languageServer.command": "npx",
-  "intlayer.languageServer.args": ["@intlayer/lsp"]
-}
-```
-
-The Intlayer extension reads these settings to launch the server. If you rely solely on the extension, no manual settings are needed.
-
----
-
-## Setup in Cursor
-
-[Cursor](https://www.cursor.com/) is a VS Code fork with built-in AI features. It uses the same extension ecosystem, so the **Intlayer VS Code extension** works without any extra configuration — install it once and Cursor picks it up automatically.
-
-If you prefer a manual configuration, Cursor also reads `.vscode/settings.json` from the workspace root, so the VS Code snippet above applies directly.
-
----
-
-## Setup in Windsurf
-
-[Windsurf](https://windsurf.com/) (by Codeium) is another VS Code-based editor. Install the Intlayer extension from the VS Code Marketplace and the language server activates automatically, exactly as it does in VS Code and Cursor.
-
-For manual configuration, create `.vscode/settings.json` at the project root:
-
-```json fileName=".vscode/settings.json"
-{
-  "intlayer.languageServer.command": "npx",
-  "intlayer.languageServer.args": ["@intlayer/lsp"]
-}
-```
-
----
-
-## Setup in Zed
+  </Tab>
+  <Tab label="Zed" value="zed">
 
-[Zed](https://zed.dev/) has native LSP support through its language settings. Add an entry in your Zed user settings (`~/.config/zed/settings.json`):
+Zed has native LSP support. Add the server to your user settings:
 
 ```json fileName="~/.config/zed/settings.json"
 {
@@ -196,45 +149,19 @@ For manual configuration, create `.vscode/settings.json` at the project root:
     }
   },
   "languages": {
-    "TypeScript": {
-      "language_servers": ["intlayer-lsp", "..."]
-    },
-    "TSX": {
-      "language_servers": ["intlayer-lsp", "..."]
-    },
-    "JavaScript": {
-      "language_servers": ["intlayer-lsp", "..."]
-    },
-    "Vue.js": {
-      "language_servers": ["intlayer-lsp", "..."]
-    },
-    "Svelte": {
-      "language_servers": ["intlayer-lsp", "..."]
-    }
+    "TypeScript": { "language_servers": ["intlayer-lsp", "..."] },
+    "TSX": { "language_servers": ["intlayer-lsp", "..."] },
+    "JavaScript": { "language_servers": ["intlayer-lsp", "..."] },
+    "Vue.js": { "language_servers": ["intlayer-lsp", "..."] },
+    "Svelte": { "language_servers": ["intlayer-lsp", "..."] }
   }
 }
 ```
 
-The `"..."` placeholder tells Zed to keep its default language servers alongside the Intlayer one.
-
----
-
-## Setup for AI Agent CLIs (Claude Code, Codex, etc.)
-
-**Claude Code** has first-class LSP plugin support — follow the [Claude Code Plugin setup](#setup-as-a-claude-code-plugin) above to get the full Go-to-Definition experience directly in your terminal sessions.
+The `"..."` placeholder keeps Zed's default language servers alongside the Intlayer one.
 
-**OpenAI Codex** and other terminal-based tools do not yet act as LSP clients — they read and write files directly rather than maintaining a persistent language-server session. For those tools, the value of having the LSP running comes indirectly: when the server is active in a companion editor (VS Code, Cursor, Windsurf, …) the editor's live index is available to any AI agent that can query it through editor-provided context (e.g., Cursor Composer, Windsurf Cascade, GitHub Copilot Chat).
-
-If you are working purely in a terminal without an editor open, you can start the language server in the background so it's ready for any editor that later connects to the same workspace:
-
-```bash
-# Keep the server alive in the background
-npx @intlayer/lsp &
-```
-
----
-
-## Manual Setup in Neovim
+  </Tab>
+  <Tab label="Neovim" value="neovim">
 
 Using [nvim-lspconfig](https://github.com/neovim/nvim-lspconfig), register a custom server configuration:
 
@@ -267,21 +194,10 @@ end
 lspconfig.intlayer_lsp.setup({})
 ```
 
-After restarting Neovim, pressing `gd` over an Intlayer key will invoke Go to Definition.
-
----
-
-## Manual Setup in Other Editors
-
-Any editor that supports the Language Server Protocol can use `@intlayer/lsp`. The server:
+After restarting Neovim, `gd` over a dictionary key runs Go to Definition and `gr` runs Find References.
 
-- **Transport** – Node.js IPC / stdio (standard)
-- **Executable** – `npx @intlayer/lsp` (or the locally installed `intlayer-lsp` binary)
-- **Capabilities** – `definitionProvider: true`, `textDocumentSync: Incremental`
-
-Consult your editor's LSP documentation for the exact configuration format (e.g., `languageserver.json` for [coc.nvim](https://github.com/neoclide/coc.nvim), or the LSP client settings in [Helix](https://helix-editor.com)).
-
-### Example: coc.nvim
+  </Tab>
+  <Tab label="coc.nvim" value="coc">
 
 ```json fileName="~/.config/nvim/coc-settings.json"
 {
@@ -307,9 +223,14 @@ Consult your editor's LSP documentation for the exact configuration format (e.g.
 }
 ```
 
-### Example: Helix
+  </Tab>
+  <Tab label="Helix" value="helix">
 
 ```toml fileName="~/.config/helix/languages.toml"
+[language-server.intlayer-lsp]
+command = "npx"
+args = ["@intlayer/lsp"]
+
 [[language]]
 name = "typescript"
 language-servers = ["intlayer-lsp", "typescript-language-server"]
@@ -317,36 +238,54 @@ language-servers = ["intlayer-lsp", "typescript-language-server"]
 [[language]]
 name = "tsx"
 language-servers = ["intlayer-lsp", "typescript-language-server"]
-
-[language-server.intlayer-lsp]
-command = "npx"
-args = ["@intlayer/lsp"]
 ```
 
+  </Tab>
+  <Tab label="Other editors" value="other">
+
+Any LSP-capable editor can run `@intlayer/lsp`. Point it at:
+
+- **Executable** — `npx @intlayer/lsp`, or the `intlayer-lsp` binary
+- **Transport** — stdio (standard)
+- **Capabilities** — `definitionProvider`, `referencesProvider`, `hoverProvider`, `completionProvider` (trigger characters `"` `'` `` ` `` `.`), push diagnostics, `textDocumentSync: Incremental`
+- **Root patterns** — `intlayer.config.ts`, `intlayer.config.js`, `package.json`
+
+Consult your editor's LSP documentation for the exact configuration format.
+
+  </Tab>
+</Tabs>
+
 ---
 
-## How It Works
+## Note on terminal AI agents
 
-When the server starts, it resolves the Intlayer configuration from the workspace root using `getConfiguration()`. This gives it the `build` and `system` paths needed to find compiled dictionaries.
+**Claude Code** acts as a real LSP client — see the tab above.
 
-On each **Go to Definition** request:
+**OpenAI Codex** and most other terminal tools are not LSP clients: they read and write files directly. Running the server on its own does not help them; the value comes from having it active in a companion editor whose index the agent can query (Cursor Composer, Windsurf Cascade, Copilot Chat).
 
-1. The server reads the full text of the open document.
-2. It scans for getter calls (`useIntlayer`, `getIntlayer`, etc.) using a regular expression.
-3. It checks whether the cursor position falls inside one of those calls.
-4. If it does, it extracts the dictionary key (capture group 3 of the regex) and calls `getUnmergedDictionaries()` to locate every content file that declares that key.
-5. It reads each matching file and finds the exact line containing `key: "<key>"` to position the cursor precisely.
-6. It returns an array of `Location` objects — one per source file.
+---
 
-Configuration is lazily resolved and cached per session; it resets on each `initialize` request (e.g., when you open a new workspace folder).
+## How It Works
+
+For each file, the server locates the closest `intlayer.config.*` and loads that project's configuration to find the compiled dictionaries. Configuration, dictionaries and the source-file list are cached with short TTLs, and invalidated whenever a watched content file changes.
+
+On a request, the server parses the document (via [oxc](https://oxc.rs/)) and inspects the cursor position:
+
+1. **On a key string** (`useIntlayer("home")`) → returns every content file declaring that key, positioned on its `key:` line.
+2. **On a field usage** (`content.title`, a destructured property, `t('path.to.field')`, `<Trans>`, …) → resolves the variable back to its dictionary and returns the matching field inside the content files.
+3. **From a content file** → runs the reverse lookup, scanning project sources for call sites of that key or field.
 
 ---
 
 ## Troubleshooting
 
-| Symptom                         | Likely cause               | Fix                                                                             |
-| ------------------------------- | -------------------------- | ------------------------------------------------------------------------------- |
-| Go to Definition does nothing   | Server not running         | Check that `@intlayer/lsp` is installed and the editor is launching it          |
-| Wrong workspace root detected   | Multiple workspace folders | Ensure the folder containing `intlayer.config.ts` is the first workspace folder |
-| Definitions not found for a key | Config not resolved        | Verify `intlayer.config.ts` (or `.js`) exists at the workspace root             |
-| Server crashes on start         | Node.js version too old    | Requires Node.js ≥ 14.18                                                        |
+| Symptom                                 | Likely cause                 | Fix                                                                      |
+| --------------------------------------- | ---------------------------- | ------------------------------------------------------------------------ |
+| Nothing happens at all                  | Server not running           | Check `@intlayer/lsp` is installed and your editor is launching it       |
+| Works in the editor, not in Claude Code | Plugin installed mid-session | Restart Claude Code — language servers load at startup                   |
+| No definitions found for a key          | Dictionaries not built       | Run `npx intlayer build`, or start your dev server                       |
+| Every key reported as undeclared        | Config not resolved          | Verify an `intlayer.config.ts` (or `.js`) exists at your project root    |
+| Wrong project used in a monorepo        | Missing per-package config   | Add an `intlayer.config.*` to each package that declares its own content |
+| Server crashes on start                 | Node.js version too old      | Requires Node.js ≥ 14.18                                                 |
+
+In VS Code, the server logs to **View → Output → "Intlayer LSP"** — useful to confirm which config was resolved and how many dictionaries were found.