@intlayer/docs 5.7.8 → 5.8.0-canary.0

package/docs/en-GB/formatters.md

@@ -0,0 +1,239 @@
+---
+createdAt: 2024-08-13
+updatedAt: 2025-08-20
+title: Formatters
+description: Locale-aware formatting utilities based on Intl for numbers, percentages, currency, dates, relative time, units, and compact notation. Includes a cached Intl helper.
+keywords:
+  - Formatters
+  - Intl
+  - Number
+  - Currency
+  - Percentage
+  - Date
+  - Relative Time
+  - Units
+  - Compact
+  - Internationalisation
+slugs:
+  - doc
+  - formatters
+---
+
+# Intlayer Formatters
+
+## Overview
+
+Intlayer provides a set of lightweight helpers built on top of the native `Intl` APIs, plus a cached `Intl` wrapper to avoid repeatedly constructing heavy formatters. These utilities are fully locale-aware and can be used from the main `intlayer` package.
+
+### Import
+
+```ts
+import {
+  Intl,
+  number,
+  percentage,
+  currency,
+  date,
+  relativeTime,
+  units,
+  compact,
+} from "intlayer";
+```
+
+If you are using React, hooks are also available; see `react-intlayer/format`.
+
+## Cached Intl
+
+The exported `Intl` is a thin, cached wrapper around the global `Intl`. It memoises instances of `NumberFormat`, `DateTimeFormat`, `RelativeTimeFormat`, which avoids rebuilding the same formatter repeatedly.
+
+Because formatter construction is relatively expensive, this caching improves performance without changing behaviour. The wrapper exposes the same API as the native `Intl`, so usage is identical.
+
+- Caching is per process and transparent to callers.
+
+> If `Intl.DisplayNames` is not available in the environment, a single dev-only warning is printed (consider a polyfill).
+
+Example:
+
+```ts
+import { Intl } from "intlayer";
+
+const numberFormat = new Intl.NumberFormat("en-GB", {
+  style: "currency",
+  currency: "GBP",
+});
+numberFormat.format(1234.5); // "£1,234.50"
+```
+
+## Formatters
+
+All helpers below are exported from `intlayer`.
+
+### `number(value, options?)`
+
+Formats a numeric value using locale-aware grouping and decimals.
+
+- **value**: `number | string`
+- **options**: `Intl.NumberFormatOptions & { locale?: LocalesValues }`
+
+Examples:
+
+```ts
+import { number } from "intlayer";
+
+number(123456.789); // "123,456.789" (in en-US)
+number("1000000", { locale: "fr" }); // "1 000 000"
+number(1234.5, { minimumFractionDigits: 2 }); // "1,234.50"
+```
+
+### `percentage(value, options?)`
+
+Formats a number as a percentage string.
+
+Behaviour: values greater than 1 are interpreted as whole percentages and normalised (e.g., `25` → `25%`, `0.25` → `25%`).
+
+- **value**: `number | string`
+- **options**: `Intl.NumberFormatOptions & { locale?: LocalesValues }`
+
+Examples:
+
+```ts
+import { percentage } from "intlayer";
+
+percentage(0.25); // "25%"
+percentage(25); // "25%"
+percentage(0.237, { minimumFractionDigits: 1 }); // "23.7%"
+```
+
+### `currency(value, options?)`
+
+Formats a value as localised currency. Defaults to `USD` with two fraction digits.
+
+- **value**: `number | string`
+- **options**: `Intl.NumberFormatOptions & { locale?: LocalesValues }`
+  - Common fields: `currency` (e.g., `"EUR"`), `currencyDisplay` (`"symbol" | "code" | "name"`)
+
+Examples:
+
+```ts
+import { currency } from "intlayer";
+
+currency(1234.5, { currency: "EUR" }); // "€1,234.50"
+currency("5000", { locale: "fr", currency: "CAD", currencyDisplay: "code" }); // "5 000,00 CAD"
+```
+
+### `date(date, optionsOrPreset?)`
+
+Formats a date/time value with `Intl.DateTimeFormat`.
+
+- **date**: `Date | string | number`
+- **optionsOrPreset**: `Intl.DateTimeFormatOptions & { locale?: LocalesValues }` or one of the presets:
+  - Presets: `"short" | "long" | "dateOnly" | "timeOnly" | "full"`
+
+Examples:
+
+```ts
+import { date } from "intlayer";
+
+date(new Date(), "short"); // e.g., "08/02/25, 14:30"
+date("2025-08-02T14:30:00Z", { locale: "fr", month: "long", day: "numeric" }); // "2 août"
+```
+
+### `relativeTime(from, to = new Date(), options?)`
+
+Formats relative time between two instants with `Intl.RelativeTimeFormat`.
+
+- Pass "now" as the first argument and the target as the second to obtain natural phrasing.
+- **from**: `Date | string | number`
+- **to**: `Date | string | number` (defaults to `new Date()`)
+- **options**: `{ locale?: LocalesValues; unit?: Intl.RelativeTimeFormatUnit; numeric?: Intl.RelativeTimeFormatNumeric; style?: Intl.RelativeTimeFormatStyle }`
+  - Default `unit` is `"second"`.
+
+Examples:
+
+```ts
+import { relativeTime } from "intlayer";
+
+const now = new Date();
+const in3Days = new Date(now.getTime() + 3 * 864e5);
+relativeTime(now, in3Days, { unit: "day" }); // "in 3 days"
+
+const twoHoursAgo = new Date(now.getTime() - 2 * 3600e3);
+relativeTime(now, twoHoursAgo, { unit: "hour", numeric: "auto" }); // "2 hours ago"
+```
+
+### `units(value, options?)`
+
+Formats a numeric value as a localised unit string using `Intl.NumberFormat` with `style: 'unit'`.
+
+- **value**: `number | string`
+- **options**: `Intl.NumberFormatOptions & { locale?: LocalesValues }`
+  - Common fields: `unit` (e.g., `"kilometre"`, `"byte"`), `unitDisplay` (`"short" | "narrow" | "long"`)
+  - Defaults: `unit: 'day'`, `unitDisplay: 'short'`, `useGrouping: false`
+
+Examples:
+
+```ts
+import { units } from "intlayer";
+
+units(5, { unit: "kilometre", unitDisplay: "long", locale: "en-GB" }); // "5 kilometres"
+units(1024, { unit: "byte", unitDisplay: "narrow" }); // "1,024B" (locale-dependent)
+```
+
+### `compact(value, options?)`
+
+Formats a number using compact notation (e.g., `1.2K`, `1M`).
+
+- **value**: `number | string`
+- **options**: `Intl.NumberFormatOptions & { locale?: LocalesValues }` (uses `notation: 'compact'` under the hood)
+
+Examples:
+
+```ts
+import { compact } from "intlayer";
+
+compact(1200); // "1.2K"
+compact("1000000", { locale: "fr", compactDisplay: "long" }); // "1 million"
+```
+
+## Notes
+
+- All helpers accept `string` inputs; these are internally coerced to numbers or dates.
+- The locale defaults to your configured `internationalization.defaultLocale` if not provided.
+- These utilities are thin wrappers; for advanced formatting, pass through the standard `Intl` options.
+
+## Entry points and re-exports (`@index.ts`)
+
+The formatters reside in the core package and are re-exported from higher-level packages to keep imports ergonomic across runtimes:
+
+Examples:
+
+```ts
+// App code (recommended)
+import { number, currency, date, Intl } from "intlayer";
+```
+
+### React
+
+Client components:
+
+```ts
+import { useNumber, useCurrency, useDate } from "react-intlayer/format";
+// or in Next.js apps
+import { useNumber, useCurrency, useDate } from "next-intlayer/client/format";
+```
+
+Server components (or React Server runtime):
+
+```ts
+import { useNumber, useCurrency, useDate } from "intlayer/server/format";
+// or in Next.js apps
+import { useNumber, useCurrency, useDate } from "next-intlayer/server/format";
+```
+
+> These hooks will consider the locale from the `IntlayerProvider` or `IntlayerServerProvider`
+
+## Doc History
+
+| Version | Date       | Changes                      |
+| ------- | ---------- | ---------------------------- |
+| 5.8.0   | 2025-08-18 | Add formatters documentation |

package/docs/en-GB/interest_of_intlayer.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-14
-updatedAt: 2025-06-29
+updatedAt: 2025-08-20
 title: Interest of Intlayer
 description: Discover the benefits and advantages of using Intlayer in your projects. Understand why Intlayer stands out among other frameworks.
 keywords:
@@ -11,105 +11,159 @@ keywords:
   - Comparison
 slugs:
   - doc
-  - concept
-  - interest
+  - why
 ---
 
-# Intlayer: A tailored way to translate your website
+# Why you should consider Intlayer?
 
-**Intlayer** is an internationalisation library designed specifically for JavaScript developers. It allows the declaration of your content everywhere in your code. It converts declarations of multilingual content into structured dictionaries to integrate easily into your code. Using TypeScript, **Intlayer** makes your development stronger and more efficient.
+## What is Intlayer?
 
-## Example of usage
+**Intlayer** is an internationalisation library designed specifically for JavaScript developers. It allows the declaration of your content everywhere in your code. It converts declarations of multilingual content into structured dictionaries to integrate easily in your code. Using TypeScript, **Intlayer** makes your development stronger and more efficient.
+
+## Why was Intlayer created?
+
+Intlayer was created to solve a common problem that affects all common i18n libraries such as `next-intl`, `react-i18next`, `react-intl`, `next-i18next`, `react-intl`, and `vue-i18n`.
+
+All these solutions adopt a centralised approach to list and manage your content. For example:
+
+```bash
+.
+├── locales
+│   ├── en.json
+│   ├── fr.json
+│   └── es.json
+├── i18n.ts
+└── src
+    └── components
+        └── MyComponent
+            └── index.tsx
+```
+
+Or here using namespaces:
+
+```bash
+.
+├── locales
+│   ├── en
+│   │  ├── footer.json
+│   │  └── navbar.json
+│   ├── fr
+│   │  ├── footer.json
+│   │  └── navbar.json
+│   └── es
+│      ├── footer.json
+│      └── navbar.json
+├── i18n.ts
+└── src
+    └── components
+        └── MyComponent
+            └── index.tsx
+```
+
+This type of architecture slows down the development process and makes the codebase more complex to maintain for several reasons:
+
+1. **For any new component created, you should:**
+   - Create the new resource/namespace in the `locales` folder
+   - Remember to import the new namespace in your page
+   - Translate your content (often done manually by copy/paste from AI providers)
+
+2. **For any change made on your components, you should:**
+   - Search for the related resource/namespace (far from the component)
+   - Translate your content
+   - Ensure your content is up to date for any locale
+   - Verify your namespace doesn't include unused keys/values
+   - Ensure the structure of your JSON files is the same for all locales
+
+On professional projects using these solutions, localisation platforms are often used to help manage the translation of your content. However, this can quickly become costly for large projects.
+
+To solve this problem, Intlayer adopts an approach that scopes your content per-component and keeps your content close to your component, as we often do with CSS (`styled-components`), types, documentation (`storybook`), or unit tests (`jest`).
 
 ```bash codeFormat="typescript"
 .
-└── Components
+└── components
     └── MyComponent
         ├── index.content.ts
+        ├── index.test.tsx
+        ├── index.stories.tsx
         └── index.tsx
 ```
 
 ```bash codeFormat="commonjs"
 .
-└── Components
+└── components
     └── MyComponent
         ├── index.content.cjs
-        └── index.mjs
+        ├── index.test.mjs
+        ├── index.stories.mjs
+        └── index.tsx
 ```
 
 ```bash codeFormat="esm"
 .
-└── Components
+└── components
     └── MyComponent
         ├── index.content.mjs
-        └── index.js
+        ├── index.test.mjs
+        ├── index.stories.mjs
+        └── index.tsx
 ```
 
-```tsx fileName="./Components/MyComponent/index.content.ts" codeFormat="typescript"
+```tsx fileName="./components/MyComponent/index.content.ts" codeFormat="typescript"
 import { t, type Dictionary } from "intlayer";
 
 const componentExampleContent = {
   key: "component-example",
   content: {
     myTranslatedContent: t({
-      "en-GB": "Hello World",
       en: "Hello World",
-      fr: "Bonjour le monde",
       es: "Hola Mundo",
+      fr: "Bonjour le monde",
     }),
   },
 } satisfies Dictionary;
 
-// Export the content dictionary for the component
 export default componentExampleContent;
 ```
 
-```jsx fileName="./Components/MyComponent/index.mjx" codeFormat="esm"
+```jsx fileName="./components/MyComponent/index.mjx" codeFormat="esm"
 import { t } from "intlayer";
 
 /** @type {import('intlayer').Dictionary} */
-// Define the content dictionary for the component
 const componentExampleContent = {
   key: "component-example",
   content: {
     myTranslatedContent: t({
-      "en-GB": "Hello World",
       en: "Hello World",
-      fr: "Bonjour le monde",
       es: "Hola Mundo",
+      fr: "Bonjour le monde",
     }),
   },
 };
 
-// Export the content dictionary for the component
 export default componentExampleContent;
 ```
 
-```jsx fileName="./Components/MyComponent/index.csx" codeFormat="commonjs"
+```jsx fileName="./components/MyComponent/index.csx" codeFormat="commonjs"
 const { t } = require("intlayer");
 
 /** @type {import('intlayer').Dictionary} */
-// Define the content dictionary for the component
 const componentExampleContent = {
   key: "component-example",
   content: {
     myTranslatedContent: t({
-      "en-GB": "Hello World",
       en: "Hello World",
-      fr: "Bonjour le monde",
       es: "Hola Mundo",
+      fr: "Bonjour le monde",
     }),
   },
 };
 
-// Export the content dictionary for the component
 module.exports = componentExampleContent;
 ```
 
-```tsx fileName="./Components/MyComponent/index.tsx" codeFormat="typescript"
+```tsx fileName="./components/MyComponent/index.tsx" codeFormat="typescript"
 import { useIntlayer } from "react-intlayer";
 
-// Component that uses the Intlayer hook to retrieve translated content
 export const ComponentExample = () => {
   const { myTranslatedContent } = useIntlayer("component-example");
 
@@ -117,7 +171,7 @@ export const ComponentExample = () => {
 };
 ```
 
-```jsx fileName="./Components/MyComponent/index.mjx" codeFormat="esm"
+```jsx fileName="./components/MyComponent/index.mjx" codeFormat="esm"
 import { useIntlayer } from "react-intlayer";
 
 const ComponentExample = () => {
@@ -127,7 +181,7 @@ const ComponentExample = () => {
 };
 ```
 
-```jsx fileName="./Components/MyComponent/index.csx" codeFormat="commonjs"
+```jsx fileName="./components/MyComponent/index.csx" codeFormat="commonjs"
 const { useIntlayer } = require("react-intlayer");
 
 const ComponentExample = () => {
@@ -137,27 +191,80 @@ const ComponentExample = () => {
 };
 ```
 
-## Why Choose Intlayer?
-
-| Feature                                   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **JavaScript-Powered Content Management** | Harness the flexibility of JavaScript to define and manage your content efficiently.                                                                                                                                                                                                                                                                                                                                                                                                     |
-| **Type-Safe Environment**                 | Utilise TypeScript to ensure all your content definitions are precise and error-free.                                                                                                                                                                                                                                                                                                                                                                                                    |
-| **Integrated Content Files**              | Keep your translations close to their respective components, enhancing maintainability and clarity.                                                                                                                                                                                                                                                                                                                                                                                      |
-| **Simplified Setup**                      | Get up and running swiftly with minimal configuration, especially optimised for Next.js projects.                                                                                                                                                                                                                                                                                                                                                                                        |
-| **Server Component Support**              | Perfectly suited for Next.js server components, ensuring smooth server-side rendering.                                                                                                                                                                                                                                                                                                                                                                                                   |
-| **Enhanced Routing**                      | Full support for Next.js app routing, adapting seamlessly to complex application structures.                                                                                                                                                                                                                                                                                                                                                                                             |
-| **Organised Codebase**                    | Keep your codebase more organised: 1 component = 1 dictionary in the same folder.                                                                                                                                                                                                                                                                                                                                                                                                        |
-| **CI Auto-translation**                   | Autofill your translations in your CI using your own OpenAI API key, eliminating the need for an L10n platform.                                                                                                                                                                                                                                                                                                                                                                          |
-| **MCP Server Integration**                | Provides an MCP (Model Context Protocol) server for IDE automation, enabling seamless content management and i18n workflows directly within your development environment. [Learn more](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/mcp_server.md).                                                                                                                                                                                                                  |
-| **Markdown Support**                      | Import and interpret markdown files for multilingual content such as privacy policies.                                                                                                                                                                                                                                                                                                                                                                                                   |
-| **Free Visual Editor & CMS**              | A free visual editor and CMS are available if you need to collaborate with content writers for your translations, once again removing the need for a localisation platform and allowing content externalisation from the codebase.                                                                                                                                                                                                                                                       |
-| **Simplified Content Retrieval**          | No need to call your `t` function for each piece of content; retrieve all your content directly using a single hook.                                                                                                                                                                                                                                                                                                                                                                     |
-| **Consistent Implementation**             | The same implementation for both client and server components, with no need to pass your `t` function through each server component.                                                                                                                                                                                                                                                                                                                                                     |
-| **Tree-shakable Content**                 | The content is tree-shakable, which reduces the size of the final bundle.                                                                                                                                                                                                                                                                                                                                                                                                                |
-| **Non-blocking Static Rendering**         | Intlayer doesn't block Static Rendering as `next-intl` does.                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| **Interoperability**                      | Allows interoperability with [react-i18next](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_with_react-i18next.md), [next-i18next](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_with_next-i18next.md), [next-intl](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_with_next-intl.md), and [react-intl](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_with_react-intl.md). |
-
-## Doc History
-
-- 5.5.10 - 2025-06-29: Initial history
+This approach allows you to:
+
+1. **Increase the speed of development**
+   - `.content.{{ts|mjs|cjs|json}}` 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. **Reduce the complexity of your codebase**
+
+3. **Increase the maintainability of your codebase**
+
+4. **Duplicate your components and their related content more easily (Example: login/register components, etc.)**
+   - By limiting the risk of impacting other components' content
+   - By copy/pasting your content from one application to another without external dependencies
+
+5. **Avoid polluting your codebase with unused keys/values for unused components**
+   - If you don't use a component, you don't need to import its content
+   - If you delete a component, you'll more easily remember to remove its related content as it will be present in the same folder
+
+6. **Reduce reasoning cost for AI agents to declare your multilingual content**
+   - The AI agent won't have to scan your entire codebase to know where to implement your content
+   - Translations can easily be done by autocompletion AI tools in your IDE (such as GitHub Copilot)
+
+7. **Optimise loading performance**
+   - If a component is lazy-loaded, its related content will be loaded at the same time
+
+## Additional features of Intlayer
+
+| Feature                                                                                                                   | Description                                                                                                                                                                                                                                                                                                                                                                                  |
+| ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/frameworks.png?raw=true)                          | **Cross-Framework 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.png?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)                                                                                                                                                                             |
+| ![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>Accelerate your development by declaring your content once, prior to 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 internationalisation, 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-utilise-content-in-your-code)                                     |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/file_tree.png?raw=true)                           | **Organised Codebase**<br><br>Keep your codebase more organised: 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 for 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 such as 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 localisation platform. Keep your content synchronised using Git, or externalise 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 optimisation](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>Does not 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 with 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/docs/en-GB/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, build your dictionaries, translate 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>Enables 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)       |
+
+## Comparison of Intlayer with other solutions
+
+| Feature                                       | Intlayer                                                                                                                         | React-i18next / i18next                                            | React-Intl (FormatJS)                              | LinguiJS                                           | next-intl                                          | next-i18next                                       | vue-i18n                                                  |
+| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | -------------------------------------------------- | -------------------------------------------------- | -------------------------------------------------- | -------------------------------------------------- | --------------------------------------------------------- |
+| **Translations Near Components**              | Yes, content collocated with each component                                                                                      | No                                                                 | No                                                 | No                                                 | No                                                 | No                                                 | Yes - using `Single File Components` (SFCs)               |
+| **TypeScript Integration**                    | Advanced, auto-generated strict types                                                                                            | Basic; extra config for safety                                     | Good, but less strict                              | Typings, needs config                              | Good                                               | Basic                                              | Good (types available; key-safety needs setup)            |
+| **Missing Translation Detection**             | Build-time error/warning                                                                                                         | Mostly fallback strings at runtime                                 | Fallback strings                                   | Needs extra config                                 | Runtime fallback                                   | Runtime fallback                                   | Runtime fallback/warnings (configurable)                  |
+| **Rich Content (JSX/Markdown/components)**    | Direct support, even React nodes                                                                                                 | Limited / interpolation only                                       | ICU syntax, not real JSX                           | Limited                                            | Not designed for rich nodes                        | Limited                                            | Limited (components via `<i18n-t>`, Markdown via plugins) |
+| **AI-powered Translation**                    | Yes, supports multiple AI providers. Usable using your own API keys. Considers the context of your application and content scope | No                                                                 | No                                                 | No                                                 | No                                                 | No                                                 | No                                                        |
+| **Visual Editor**                             | Yes, local Visual Editor + optional CMS; can externalise codebase content; embeddable                                            | No / available via external localisation platforms                 | No / available via external localisation platforms | No / available via external localisation platforms | No / available via external localisation platforms | No / available via external localisation platforms | No / available via external localisation platforms        |
+| **Localised Routing**                         | Built-in, middleware support                                                                                                     | Plugins or manual config                                           | Not built-in                                       | Plugin/manual config                               | Built-in                                           | Built-in                                           | Manual via Vue Router (Nuxt i18n handles it)              |
+| **Dynamic Route Generation**                  | Yes                                                                                                                              | Plugin/ecosystem or manual setup                                   | Not provided                                       | Plugin/manual                                      | Yes                                                | Yes                                                | Not provided (Nuxt i18n provides)                         |
+| **Pluralisation**                             | Enumeration-based patterns; see docs                                                                                             | Configurable (plugins like i18next-icu)                            | Advanced (ICU)                                     | Advanced (ICU/messageformat)                       | Good                                               | Good                                               | Advanced (built-in plural rules)                          |
+| **Formatting (dates, numbers, currencies)**   | Optimised formatters (Intl under the hood)                                                                                       | Via plugins or custom Intl usage                                   | Advanced ICU formatters                            | ICU/CLI helpers                                    | Good (Intl helpers)                                | Good (Intl helpers)                                | Built-in date/number formatters (Intl)                    |
+| **Content Format**                            | .tsx, .ts, .js, .json, .md, .txt                                                                                                 | .json                                                              | .json, .js                                         | .po, .json                                         | .json, .js, .ts                                    | .json                                              | .json, .js                                                |
+| **ICU support**                               | WIP (native ICU)                                                                                                                 | Via plugin (i18next-icu)                                           | Yes                                                | Yes                                                | Yes                                                | Via plugin (i18next-icu)                           | Via custom formatter/compiler                             |
+| **SEO Helpers (hreflang, sitemap)**           | Built-in tools: helpers for sitemap, **robots.txt**, metadata                                                                    | Community plugins/manual                                           | Not core                                           | Not core                                           | Good                                               | Good                                               | Not core (Nuxt i18n provides helpers)                     |
+| **Ecosystem / Community**                     | Smaller but growing fast and reactive                                                                                            | Largest and most mature                                            | Large, enterprise                                  | Growing, smaller                                   | Mid-size, Next.js-focused                          | Mid-size, Next.js-focused                          | Large in Vue ecosystem                                    |
+| **Server-side Rendering & Server Components** | Yes, streamlined for SSR / React Server Components                                                                               | Supported, some configuration needed                               | Supported in Next.js                               | Supported                                          | Full support                                       | Full support                                       | SSR via Nuxt/Vue SSR (no RSC)                             |
+| **Tree-shaking (load only used content)**     | Yes, per-component at build time via Babel/SWC plugins                                                                           | Usually loads all (can be improved with namespaces/code-splitting) | Usually loads all                                  | Not default                                        | Partial                                            | Partial                                            | Partial (with code-splitting/manual setup)                |
+| **Lazy loading**                              | Yes, per-locale/per-component                                                                                                    | Yes (e.g., backends/namespaces on demand)                          | Yes (split locale bundles)                         | Yes (dynamic catalogue imports)                    | Yes (per-route/per-locale)                         | Yes (per-route/per-locale)                         | Yes (async locale messages)                               |
+| **Management of Large Projects**              | Encourages modularity, suited for design systems                                                                                 | Requires good file discipline                                      | Central catalogues can become large                | Can become complex                                 | Modular with setup                                 | Modular with setup                                 | Modular with Vue Router/Nuxt i18n setup                   |
+
+## Document History
+
+| Version | Date       | Changes                   |
+| ------- | ---------- | ------------------------- |
+| 5.8.0   | 2025-08-19 | Updated comparative table |
+| 5.5.10  | 2025-06-29 | Initial history           |

package/docs/en-GB/packages/intlayer/index.md

@@ -148,8 +148,8 @@ const clientComponentContent = {
   content: {
     myTranslatedContent: t({
       en: "Hello World",
-      fr: "Bonjour le monde",
       es: "Hola Mundo",
+      fr: "Bonjour le monde",
     }),
     numberOfCar: enu({
       "<-1": "Less than minus one car",
@@ -174,8 +174,8 @@ const clientComponentContent = {
   content: {
     myTranslatedContent: t({
       en: "Hello World",
-      fr: "Bonjour le monde",
       es: "Hola Mundo",
+      fr: "Bonjour le monde",
     }),
     numberOfCar: enu({
       "<-1": "Less than minus one car",
@@ -234,8 +234,8 @@ const clientComponentContent = {
   content: {
     myTranslatedContent: t({
       en: "Hello World",
-      fr: "Bonjour le monde",
       es: "Hola Mundo",
+      fr: "Bonjour le monde",
     }),
     numberOfCar: enu({
       "<-1": "Less than minus one car",