@intlayer/docs 9.4.0-canary.0 → 9.4.0

package/docs/en-GB/formatters.md

@@ -48,46 +48,16 @@ Intlayer provides a set of lightweight helpers built on top of the native `Intl`
 
 ## Cached Intl
 
-The exported `Intl` is a thin, cached wrapper around the global `Intl`. It memoises instances of `NumberFormat`, `DateTimeFormat`, `RelativeTimeFormat`, `ListFormat`, `DisplayNames`, `Collator`, and `PluralRules`, 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).
 
 Examples:
 
-```ts
-import { Intl } from "intlayer";
-
-// Number formatting
-const numberFormat = new Intl.NumberFormat("en-GB", {
-  style: "currency",
-  currency: "GBP",
-});
-numberFormat.format(1234.5); // "£1,234.50"
-
-// Display names for languages, regions, etc.
-const displayNames = new Intl.DisplayNames("fr", { type: "language" });
-displayNames.of("en"); // "anglais"
-
-// Collation for sorting
-const collator = new Intl.Collator("fr", { sensitivity: "base" });
-collator.compare("é", "e"); // 0 (equal)
-
-// Plural rules
-const pluralRules = new Intl.PluralRules("fr");
-pluralRules.select(1); // "one"
-pluralRules.select(2); // "other"
-```
-
 ## Locale Utilities
 
 ### `getLocaleFromPath(inputUrl)`
 
-Extracts the locale segment from a URL or pathname:
-
 ```ts
 import { getLocaleFromPath } from "intlayer";
 
@@ -97,29 +67,16 @@ getLocaleFromPath("/dashboard"); // "en" (default locale)
 getLocaleFromPath("https://example.com/es/about"); // "es"
 ```
 
-- **inputUrl**: The complete URL string or pathname to process
-- **returns**: The detected locale or default locale if no locale is found
-
 ### `getPathWithoutLocale(inputUrl, locales?)`
 
 Removes the locale segment from a URL or pathname:
 
-```ts
-import { getPathWithoutLocale } from "intlayer";
-
-getPathWithoutLocale("/en/dashboard"); // "/dashboard"
-getPathWithoutLocale("/fr/dashboard"); // "/dashboard"
-getPathWithoutLocale("https://example.com/en/about"); // "https://example.com/about"
-```
-
 - **inputUrl**: The complete URL string or pathname to process
 - **locales**: Optional array of supported locales (defaults to configured locales)
 - **returns**: The URL without the locale segment
 
 ### `getLocalizedUrl(url, currentLocale, locales?, defaultLocale?, prefixDefault?)`
 
-Generates a localised URL for the current locale:
-
 ```ts
 import { getLocalizedUrl } from "intlayer";
 
@@ -128,12 +85,6 @@ getLocalizedUrl("/about", "en", ["en", "fr"], "en", false); // "/about"
 getLocalizedUrl("https://example.com/about", "fr", ["en", "fr"], "en", true); // "https://example.com/fr/about"
 ```
 
-- **url**: The original URL to localise
-- **currentLocale**: The current locale
-- **locales**: Optional array of supported locales (defaults to configured locales)
-- **defaultLocale**: Optional default locale (defaults to configured default locale)
-- **prefixDefault**: Whether to prefix the default locale (defaults to configured value)
-
 ### `getHTMLTextDir(locale?)`
 
 Returns the text direction for a locale:
@@ -146,15 +97,10 @@ getHTMLTextDir("ar"); // "rtl"
 getHTMLTextDir("he"); // "rtl"
 ```
 
-- **locale**: The locale to get the text direction for (defaults to current locale)
-- **returns**: `"ltr"`, `"rtl"`, or `"auto"`
-
 ## Content Handling Utilities
 
 ### `getContent(node, nodeProps, locale?)`
 
-Transforms a content node with all available plugins (translation, enumeration, insertion, etc.):
-
 ```ts
 import { getContent } from "intlayer";
 
@@ -165,36 +111,16 @@ const content = getContent(
 );
 ```
 
-- **node**: The content node to transform
-- **nodeProps**: Properties for the transformation context
-- **locale**: Optional locale (defaults to configured default locale)
-
 ### `getTranslation(languageContent, locale?, fallback?)`
 
 Extracts content for a specific locale from a language content object:
 
-```ts
-import { getTranslation } from "intlayer";
-
-const content = getTranslation(
-  {
-    en: "Hello",
-    fr: "Bonjour",
-    de: "Hallo",
-  },
-  "fr",
-  true
-); // "Bonjour"
-```
-
 - **languageContent**: Object mapping locales to content
 - **locale**: Target locale (defaults to configured default locale)
 - **fallback**: Whether to fallback to the default locale (defaults to true)
 
 ### `getIntlayer(dictionaryKey, locale?, plugins?)`
 
-Retrieves and transforms content from a dictionary by key:
-
 ```ts
 import { getIntlayer } from "intlayer";
 
@@ -202,10 +128,6 @@ const content = getIntlayer("common", "fr");
 const nestedContent = getIntlayer("common", "fr", customPlugins);
 ```
 
-- **dictionaryKey**: The key of the dictionary to retrieve
-- **locale**: Optional locale (defaults to configured default locale)
-- **plugins**: Optional array of custom transformation plugins
-
 ### `getIntlayerAsync(dictionaryKey, locale?, plugins?)`
 
 Asynchronously retrieves content from a remote dictionary:
@@ -216,25 +138,12 @@ import { getIntlayerAsync } from "intlayer";
 const content = await getIntlayerAsync("common", "fr");
 ```
 
-- **dictionaryKey**: The key of the dictionary to retrieve
-- **locale**: Optional locale (defaults to configured default locale)
-- **plugins**: Optional array of custom transformation plugins
-
 ## Formatters
 
 All helpers below are exported from `intlayer`.
 
 ### `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";
 
@@ -430,13 +339,6 @@ pluralRules.select(11); // "many"
 
 ### `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
@@ -448,11 +350,6 @@ units(1024, { unit: "byte", unitDisplay: "narrow" }); // "1,024B" (locale-depend
 
 ### `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
@@ -464,13 +361,6 @@ compact("1000000", { locale: "fr", compactDisplay: "long" }); // "1 million"
 
 ### `list(values, options?)`
 
-Formats an array of values into a localised list string using `Intl.ListFormat`.
-
-- **values**: `(string | number)[]`
-- **options**: `Intl.ListFormatOptions & { locale?: LocalesValues }`
-  - Common fields: `type` (`"conjunction" | "disjunction" | "unit"`), `style` (`"long" | "short" | "narrow"`)
-  - Defaults: `type: 'conjunction'`, `style: 'long'`
-
 Examples:
 
 ```ts
@@ -496,56 +386,6 @@ getLocaleLang("fr-CA"); // "fr"
 
 Client components:
 
-```tsx
-import {
-  useNumber,
-  useCurrency,
-  useDate,
-  usePercentage,
-  useCompact,
-  useList,
-  useRelativeTime,
-  useUnit,
-} from "react-intlayer/format";
-// or in Next.js apps
-import {
-  useNumber,
-  useCurrency,
-  useDate,
-  usePercentage,
-  useCompact,
-  useList,
-  useRelativeTime,
-  useUnit,
-} from "next-intlayer/client/format";
-
-const MyComponent = () => {
-  const number = useNumber();
-  const currency = useCurrency();
-  const date = useDate();
-  const percentage = usePercentage();
-  const compact = useCompact();
-  const list = useList();
-  const relativeTime = useRelativeTime();
-  const unit = useUnit();
-
-  return (
-    <div>
-      <p>{number(123456.789)}</p>
-      <p>{currency(1234.5, { currency: "EUR" })}</p>
-      <p>{date(new Date(), "short")}</p>
-      <p>{percentage(0.25)}</p>
-      <p>{compact(1200)}</p>
-      <p>{list(["apple", "banana", "orange"])}</p>
-      <p>{relativeTime(new Date(), new Date() + 1000)}</p>
-      <p>{unit(123456.789, { unit: "kilometre" })}</p>
-    </div>
-  );
-};
-```
-
-Server components (or React Server runtime):
-
 ```ts
 import {
   useNumber,
@@ -570,8 +410,6 @@ import {
 } from "next-intlayer/server/format";
 ```
 
-> These hooks will consider the locale from the `IntlayerProvider` or `IntlayerServerProvider`
-
 ### `getHTMLTextDir(locale?)`
 
 Returns the text direction for a locale:
@@ -603,8 +441,6 @@ import {
 } from "vue-intlayer/format";
 ```
 
-> These composables will consider the locale from the injected `IntlayerProvider`
-
 ### `getTranslation(languageContent, locale?, fallback?)`
 
 Extracts content for a specific locale:

package/docs/en-GB/how_works_intlayer.md

@@ -62,6 +62,8 @@ The build step can be done in three ways:
    - Those dictionaries are generated in different formats to match all needs and optimise the performance of the application.
 
 3. Generation of dictionary types
+
+4. Generation of dictionary types
    Based on your `dictionaries`, Intlayer will generate types to make them usable in your application.
 
 - Dictionary types are generated from Intlayer `content declaration files`. By default, Intlayer dictionary types are generated in the `.intlayer/types` directory of the project.
@@ -98,6 +100,9 @@ Intlayer also provides a visual editor to allow you to edit your content in a vi
 
 ![visual editor](https://github.com/aymericzip/intlayer/blob/main/docs/assets/visual_editor.gif?raw=true)
 
+- The server is a simple Express application that listens to requests from the client and retrieves the content of your application, such as the `dictionaries` and the configuration to make it accessible on the client side.
+- On the other hand, the client is a React application that is used to interact with your content using a visual interface.
+
 - The server is a simple Express application that listens to requests from the client and retrieves the content of your application, such as the `dictionaries` and the configuration to make it accessible on the client side.
 - On the other hand, the client is a React application that is used to interact with your content using a visual interface.
   When you call your content using `useIntlayer` and the editor is enabled, it automatically wraps your strings with a Proxy object named `IntlayerNode`. This node uses `window.postMessage` to communicate with a wrapped iframe containing the visual editor interface.  
@@ -108,6 +113,8 @@ Intlayer also provides a visual editor to allow you to edit your content in a vi
 To optimise the bundle size of your application, Intlayer provides two plugins to optimise the build of your application: `@intlayer/babel` and `@intlayer/swc` plugins.  
 The Babel and SWC plugins work by analysing your application's Abstract Syntax Tree (AST) to replace calls of Intlayer functions with optimised code. This process makes your final bundle lighter in production by ensuring that only the dictionaries that are actually used are imported, optimising chunking and reducing bundle size.
 
+The Babel and SWC plugins work by analysing your application's Abstract Syntax Tree (AST) to replace calls of Intlayer functions with optimised code. This process makes your final bundle lighter in production by ensuring that only the dictionaries that are actually used are imported, optimising chunking and reducing bundle size.
+
 In development mode, Intlayer uses a centralised static import for dictionaries to simplify the development experience.
 
 By activating the option `importMode = "dynamic"` in the `dictionary` configuration within your [configuration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/configuration.md), Intlayer will use the dynamic import to load the dictionaries. This option is disabled by default to avoid async processing when rendering the application.

package/docs/en-GB/intlayer_visual_editor.md

@@ -85,6 +85,16 @@ pnpm add intlayer-editor --save-dev
 bun add intlayer-editor --dev
 ```
 
+With the `--with` flag, you can start the editor in parallel with another command:
+
+```json5 fileName="package.json"
+{
+  "scripts": {
+    "start:editor": "npx intlayer-editor start --with 'next dev --turbopack'",
+  },
+}
+```
+
 ## Configuration
 
 In your Intlayer configuration file, you can customise the editor settings:
@@ -146,6 +156,8 @@ export default config;
 
    > **Note that you should run your application in parallel.** The application URL should match the one you set in the editor configuration (`applicationURL`).
 
+> **Note the command is reexported by the `intlayer` package. You can use `npx intlayer editor start` instead.**
+
 2. Then, open the URL provided. By default `http://localhost:8000`.
 
    You can view each field indexed by Intlayer by hovering over your content with your cursor.

package/docs/en-GB/intlayer_with_adonisjs.md

@@ -258,9 +258,11 @@ import { Locales, type IntlayerConfig } from "intlayer";
 
 const config: IntlayerConfig = {
   // ... Other configuration options
-  middleware: {
-    headerName: "my-locale-header",
-    cookieName: "my-locale-cookie",
+  routing: {
+    storage: [
+      { type: "header", name: "my-locale-header" },
+      { type: "cookie", name: "my-locale-cookie" },
+    ],
   },
 };
 

package/docs/en-GB/intlayer_with_astro.md

@@ -122,6 +122,30 @@ Check out the [application template](https://github.com/aymericzip/intlayer-astr
 
 Install the necessary packages using your preferred package manager:
 
+```bash packageManager="npm"
+npx intlayer init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer@canary init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer@canary init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer@canary init --interactive
+```
+
+> the `--interactive` flag is optional. Use `intlayer-cli init` if you're an AI agent.
+
+> This command will detect your environment and install the required packages. For example:
+
+```bash packageManager="npm"
+npm install intlayer astro-intlayer
+```
+
 ```bash packageManager="npm"
 npm install intlayer astro-intlayer
 # Optional: If you add support for React islands

package/docs/en-GB/intlayer_with_astro_preact.md

@@ -606,6 +606,12 @@ bun run build # Or bun run dev
 
 ### TypeScript Configuration
 
+Intlayer uses module augmentation to get the benefits of TypeScript and make your codebase stronger.
+
+![Autocompletion](https://github.com/aymericzip/intlayer/blob/main/docs/assets/autocompletion.png?raw=true)
+
+![Translation error](https://github.com/aymericzip/intlayer/blob/main/docs/assets/translation_error.png?raw=true)
+
 Intlayer uses module augmentation to leverage TypeScript, making your codebase more robust. Ensure your TypeScript configuration includes the autogenerated types and is configured for Preact:
 
 ```json5 fileName="tsconfig.json"

package/docs/en-GB/intlayer_with_create_react_app.md

@@ -31,6 +31,14 @@ author: aymericzip
 
 # Translate your Create React App website using Intlayer | Internationalization (i18n)
 
+<iframe
+  src="https://ide.intlayer.org/aymericzip/intlayer-react-cra-template?file=intlayer.config.ts"
+  className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
+  title="Demo CodeSandbox - How to Internationalise your application using Intlayer"
+  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
+  loading="lazy"
+/>
+
 See [Application Template](https://github.com/aymericzip/intlayer-react-cra-template) on GitHub.
 
 ## Why Intlayer over alternatives?
@@ -138,32 +146,6 @@ bun add intlayer react-intlayer react-scripts-intlayer
 
 - **react-scripts-intlayer**
 
-Includes the `react-scripts-intlayer` commands and plugins for integrating Intlayer with the Create React App based application. These plugins are based on [craco](https://craco.js.org/) and include additional configuration for the [Webpack](https://webpack.js.org/) bundler.
-
-</Step>
-
-<Step number={2} title="Configuration of your project">
-
-Create a config file to configure the languages of your application:
-
-```typescript fileName="intlayer.config.ts"  codeFormat="typescript"
-import { Locales, type IntlayerConfig } from "intlayer";
-
-const config: IntlayerConfig = {
-  internationalization: {
-    locales: [
-      Locales.ENGLISH,
-      Locales.FRENCH,
-      Locales.SPANISH,
-      // Your other locales
-    ],
-    defaultLocale: Locales.ENGLISH,
-  },
-};
-
-export default config;
-```
-
 Includes the`react-scripts-intlayer` commands and plugins for integrating Intlayer with the Create React App based application. These plugins are based on [craco](https://craco.js.org/) and include additional configuration for the [Webpack](https://webpack.js.org/) bundler.
 
 </Step>
@@ -206,22 +188,6 @@ Change your scripts to use react-intlayer
   },
 ```
 
-> Through this configuration file, you can set up localised URLs, middleware redirection, cookie names, the location and extension of your content declarations, disable Intlayer logs in the console, and more. For a complete list of available parameters, refer to the [configuration documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/configuration.md).
-
-</Step>
-
-<Step number={3} title="Integrate Intlayer in Your CRA Configuration">
-
-Change your scripts to use react-intlayer
-
-```json fileName="package.json"
-  "scripts": {
-    "build": "react-scripts-intlayer build",
-    "start": "react-scripts-intlayer start",
-    "transpile": "intlayer build"
-  },
-```
-
 > `react-scripts-intlayer` scripts are based on [CRACO](https://craco.js.org/). You can also implement your own setup based on the intlayer craco plugin. [See example here](https://github.com/aymericzip/intlayer/blob/main/examples/react-app/craco.config.js).
 
 </Step>
@@ -326,27 +292,6 @@ export default App;
 >
 > To learn more about the `useIntlayer` hook, refer to the [documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/packages/react-intlayer/useIntlayer.md).
 
-</Step>
-
-<Step number={6} title="Change the language of your content" isOptional={true}>
-
-To change the language of your content, you can use the `setLocale` function provided by the `useLocale` hook. This function allows you to set the locale of the application and update the content accordingly.
-
-```tsx fileName="src/components/LocaleSwitcher.tsx" codeFormat="typescript"
-import { Locales } from "intlayer";
-import { useLocale } from "react-intlayer";
-
-const LocaleSwitcher = () => {
-  const { setLocale } = useLocale();
-
-  return (
-    <button onClick={() => setLocale(Locales.English)}>
-      Change Language to English
-    </button>
-  );
-};
-```
-
 > To Learn more about the `useIntlayer` hook, refer to the [documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/packages/react-intlayer/useIntlayer.md).
 
 </Step>
@@ -370,21 +315,6 @@ const LocaleSwitcher = () => {
 };
 ```
 
-> To Learn more about the `useLocale` hook, refer to the [documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/packages/react-intlayer/useLocale.md).
-
-</Step>
-
-<Step number={7} title="Add localised Routing to your application" isOptional={true}>
-
-The purpose of this step is to make unique routes for each language. This is useful for SEO and SEO-friendly URLs.
-Example:
-
-```plaintext
-- https://example.com/about
-- https://example.com/es/about
-- https://example.com/fr/about
-```
-
 > To learn more about the `useLocale` hook, refer to the [documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/packages/react-intlayer/useLocale.md).
 
 </Step>
@@ -725,6 +655,8 @@ To do this, you can add the following instructions to your `.gitignore` file:
 
 ### VS Code Extension
 
+To improve your development experience with Intlayer, you can install the official **Intlayer VS Code Extension**.
+
 To improve your development experience with Intlayer, you can install the official **Intlayer VS Code Extension**.
 [Install from the VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)