@intlayer/docs 8.12.5-canary.0 → 9.0.0-canary.11

package/docs/en-GB/intlayer_with_react_native+expo.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-06-18
-updatedAt: 2026-05-31
+updatedAt: 2026-06-25
 title: "Expo + React Native i18n - Complete guide to translate your app"
 description: "No more i18next. The 2026 guide to building a multilingual (i18n) Expo + React Native app. Translate with AI agents and optimise bundle size, SEO and performances."
 keywords:
@@ -17,6 +17,9 @@ slugs:
 applicationTemplate: https://github.com/aymericzip/intlayer-react-native-template
 applicationShowcase: https://intlayer-react-native.vercel.app
 history:
+  - version: 9.0.0
+    date: 2026-06-25
+    changes: "Import providers and hooks directly from react-native-intlayer; react-intlayer is no longer needed as a direct dependency"
   - version: 8.9.0
     date: 2026-05-04
     changes: "Update Solid useIntlayer API usage to direct property access"
@@ -29,7 +32,7 @@ history:
 author: aymericzip
 ---
 
-# Getting Started Internationalising (i18n) with Intlayer and React Native
+# Translate your Expo and React Native app | Internationalisation (i18n)
 
 <Tabs defaultTab="code">
   <Tab label="Code" value="code">
@@ -37,7 +40,7 @@ author: aymericzip
 <iframe
   src="https://ide.intlayer.org/aymericzip/intlayer-react-native-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 - Intlayer"
+  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"
 />
@@ -56,17 +59,19 @@ author: aymericzip
   </Tab>
 </Tabs>
 
-See [Application Template](https://github.com/aymericzip/intlayer-react-native-template) on GitHub.
+## Table of Contents
+
+<TOC/>
 
 ## Why Intlayer over alternatives?
 
-Compared to main solutions like `react-native-localize` or `i18next`, Intlayer is a solution that comes with integrated optimizations such as:
+Compared to main solutions like `react-native-localize` or `i18next`, Intlayer is a solution that comes with integrated optimisations such as:
 
 <AccordionGroup>
 
 <Accordion header="Full React Native coverage">
 
-Intlayer is optimized to work perfectly with React Native and Expo by offering **component-level content scoping**, **TypeScript support**, and all the features needed for scaling internationalization (i18n) in mobile apps.
+Intlayer is optimised to work perfectly with React Native and Expo by offering **component-level content scoping**, **TypeScript support**, and all the features needed for scaling internationalisation (i18n) in mobile apps.
 
 </Accordion>
 
@@ -90,7 +95,7 @@ Use automation to translate in your CI/CD pipeline using the LLM of your choice
 
 <Accordion header="Performance">
 
-Connecting massive JSON files to components can lead to performance and reactivity issues. Intlayer optimizes your content loading at build time.
+Connecting massive JSON files to components can lead to performance and reactivity issues. Intlayer optimises your content loading at build time.
 
 </Accordion>
 
@@ -116,70 +121,39 @@ See [Application Template](https://github.com/aymericzip/intlayer-react-native-t
 From your React Native project, install the following packages:
 
 ```bash packageManager="npm"
-npm install intlayer react-intlayer
-npm install --save-dev react-native-intlayer
-npx intlayer init
+npx intlayer-cli init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm add intlayer react-intlayer
-pnpm add --save-dev react-native-intlayer
-pnpm intlayer init
+pnpm dlx intlayer-cli init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn add intlayer react-intlayer
-yarn add --save-dev react-native-intlayer
-yarn intlayer init
+yarn dlx intlayer-cli init --interactive
 ```
 
 ```bash packageManager="bun"
-bun add intlayer react-intlayer
-bun add --dev react-native-intlayer
-bun x intlayer init
+bunx intlayer-cli init --interactive
 ```
 
-### Packages
-
-- **intlayer**  
-  The core i18n toolkit for configuration, dictionary content, types generation, and CLI commands.
+> the `--interactive` flag is optional. Use `intlayer-cli init` if you're an AI agent.
 
-- **react-intlayer**  
-  React integration that provides the context providers and React hooks you’ll use in React Native for obtaining and switching locales.
-
-- **react-native-intlayer**  
-  React Native integration that provides the Metro plugin for integrating Intlayer with the React Native bundler.
-
----
-
-</Step>
-
-<Step number={2} title="Install Dependencies">
-
-From your React Native project, install the following packages:
+> This command will detect your environment and install the required packages. For example:
 
 ```bash packageManager="npm"
-npm install intlayer react-intlayer
-npm install --save-dev react-native-intlayer
-npx intlayer init
+npm install intlayer react-native-intlayer
 ```
 
 ```bash packageManager="pnpm"
-pnpm add intlayer react-intlayer
-pnpm add --save-dev react-native-intlayer
-pnpm intlayer init
+pnpm add intlayer react-native-intlayer
 ```
 
 ```bash packageManager="yarn"
-yarn add intlayer react-intlayer
-yarn add --save-dev react-native-intlayer
-yarn intlayer init
+yarn add intlayer react-native-intlayer
 ```
 
 ```bash packageManager="bun"
-bun add intlayer react-intlayer
-bun add --dev react-native-intlayer
-bun x intlayer init
+bun add intlayer react-native-intlayer
 ```
 
 ### Packages
@@ -187,17 +161,14 @@ bun x intlayer init
 - **intlayer**  
   The core i18n toolkit for configuration, dictionary content, types generation, and CLI commands.
 
-- **react-intlayer**  
-  React integration that provides the context providers and React hooks you’ll use in React Native for obtaining and switching locales.
-
 - **react-native-intlayer**  
-  React Native integration that provides the Metro plugin for integrating Intlayer with the React Native bundler.
+  React Native integration that provides the context providers and React hooks you'll use to obtain and switch locales, the React Native polyfills, and the Metro plugin for integrating Intlayer with the React Native bundler. It re-exports everything from `react-intlayer`, so you only need this single package in a React Native app.
 
 ---
 
 </Step>
 
-<Step number={3} title="Create an Intlayer Config">
+<Step number={2} title="Create an Intlayer Config">
 
 In your project root (or anywhere convenient), create an **Intlayer config** file. It might look like this:
 
@@ -231,7 +202,7 @@ Within this config, you can:
 
 </Step>
 
-<Step number={4} title="Add the Metro plugin">
+<Step number={3} title="Add the Metro plugin">
 
 Metro is a bundler for React Native. It is the default bundler for React Native projects created with the `react-native init` command. To use Intlayer with Metro, you need to add the plugin to your `metro.config.js` file:
 
@@ -246,13 +217,18 @@ module.exports = (async () => {
 })();
 ```
 
+> Note: `configMetroIntlayer` is a promise function. Use `configMetroIntlayerSync` instead if you want to use it synchronously, or avoid IFFE (Immediately Invoked Function Expression).
+> Note: `configMetroIntlayerSync` does not allow building intlayer dictionaries on server start.
+
 </Step>
 
-<Step number={5} title="Add the Intlayer provider">
+<Step number={4} title="Add the Intlayer provider">
 
-To keep synchronized the user language across your application, you need to wrap your root component with the `IntlayerProvider` component from `react-intlayer-native`.
+To keep the user language synchronised across your application, you need to wrap your root component with the `IntlayerProvider` component from `react-native-intlayer`.
 
-> Make sure to use the provider from `react-native-intlayer` instead of `react-intlayer`. The export from `react-native-intlayer` includes polyfills for the web API.
+> Always import from `react-native-intlayer`. Its `IntlayerProvider` includes polyfills for the web API used by Intlayer, and the package re-exports all the hooks and utilities from `react-intlayer`.
+
+Also, you need to add the `intlayerPolyfill` function to your `index.js` file to ensure that Intlayer can work properly.
 
 ```tsx fileName="app/_layout.tsx" codeFormat={["typescript", "esm"]}
 import { Stack } from "expo-router";
@@ -277,11 +253,13 @@ export default RootLayout;
 
 </Step>
 
-<Step number={6} title="Declare Your Content">
+<Step number={5} title="Declare Your Content">
 
 Create **content declaration** files anywhere in your project (commonly within `src/`), using any of the extension formats that Intlayer supports:
 
 - `.content.json`
+- `.content.jsonc`
+- `.content.json5`
 - `.content.ts`
 - `.content.tsx`
 - `.content.js`
@@ -289,9 +267,20 @@ Create **content declaration** files anywhere in your project (commonly within `
 - `.content.mjs`
 - `.content.mjx`
 - `.content.cjs`
-- `.content.cjx`
+- `.content.md`
+- `.content.mdx`
+- `.content.yaml`
+- `.content.yml`
 - etc.
 
+> **Expo Router (web): keep `.content.*` files out of the `app/` directory.** Expo Router treats every JavaScript/TypeScript file inside `app/` as a route. On web, its route discovery scans the filesystem directly and does **not** honour Metro's `resolver.blockList`, so a co-located `*.content.ts` is registered as a route. A file such as `app/(tabs)/_layout.content.ts` is even parsed as a layout (the `.content` part is read as a platform suffix), which collides with the real `_layout.tsx` and throws:
+>
+> ```
+> The layouts "./(tabs)/_layout.content.ts" and "./(tabs)/_layout.tsx" conflict on the route "/(tabs)/_layout.content". Remove or rename one of these files.
+> ```
+>
+> Place your declarations in a directory outside `app/` (for example `content/` or `src/content/`). Intlayer discovers `.content.*` files anywhere in the project and dictionaries are referenced by their `key`, so no import changes are needed. On native this is not required (Metro's `blockList` already hides them), but using a non-`app/` directory keeps both platforms working.
+
 Example (TypeScript with TSX nodes for React Native):
 
 ```tsx fileName="src/app.content.tsx" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
@@ -335,13 +324,13 @@ export default homeScreenContent;
 }
 ```
 
-> For details on content declarations, see [Intlayer’s content docs](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/dictionary/content_file.md).
+> For details on content declarations, see [Intlayer's content docs](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/dictionary/content_file.md).
 
 ---
 
 </Step>
 
-<Step number={7} title="Use Intlayer in Your Components">
+<Step number={6} title="Use Intlayer in Your Components">
 
 Use the `useIntlayer` hook in child components to obtain localised content.
 
@@ -349,7 +338,7 @@ Use the `useIntlayer` hook in child components to obtain localised content.
 
 ```tsx fileName="app/(tabs)/index.tsx" codeFormat={["typescript", "esm"]}
 import { Image, StyleSheet, Platform } from "react-native";
-import { useIntlayer } from "intlayer";
+import { useIntlayer } from "react-native-intlayer";
 import { HelloWave } from "@/components/HelloWave";
 import ParallaxScrollView from "@/components/ParallaxScrollView";
 import { ThemedText } from "@/components/ThemedText";
@@ -388,21 +377,23 @@ const styles = StyleSheet.create({
 export default HomeScreen;
 ```
 
-> When using `content.someKey` in string-based props (e.g., a button’s `title` or a `Text` component’s `children`), **call `content.someKey.value`** to obtain the actual string.
+> When using `content.someKey` in string-based props (e.g., a button's `title` or a `Text` component's `children`), **call `content.someKey.value`** to obtain the actual string.
+
+> If your app already exists, you can use the [Intlayer Compiler](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/compiler.md), as well as the [extract command](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/extract.md), to transform thousands of components in a second.
 
 ---
 
 </Step>
 
-<Step number={8} title="Change the App Locale" isOptional={true}>
+<Step number={7} title="Change the App Locale" isOptional={true}>
 
-To switch locales from within your components, you can use the `useLocale` hook’s `setLocale` method:
+To switch locales from within your components, you can use the `useLocale` hook's `setLocale` method:
 
 ```tsx fileName="src/components/LocaleSwitcher.tsx" codeFormat={["typescript", "esm"]}
 import { type FC } from "react";
 import { View, Text, TouchableOpacity, StyleSheet } from "react-native";
 import { getLocaleName } from "intlayer";
-import { useLocale } from "react-intlayer";
+import { useLocale } from "react-native-intlayer";
 
 export const LocaleSwitcher: FC = () => {
   const { setLocale, availableLocales } = useLocale();
@@ -443,7 +434,7 @@ const styles = StyleSheet.create({
 });
 ```
 
-This triggers a re-render of all components that use Intlayer content, now displaying translations for the new locale.
+This triggers a re-render of all components that use Intlayer content, now showing translations for the new locale.
 
 > See [`useLocale` docs](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/packages/react-intlayer/useLocale.md) for more details.
 
@@ -511,3 +502,31 @@ For more details on how to use the extension, refer to the [Intlayer VS Code Ext
 Enjoy building your **React Native** apps with fully powered i18n through **Intlayer**!
 
 ---
+
+### Debug
+
+React Native can be less stable than React Web, so pay extra attention to version alignment.
+
+Intlayer primarily targets the Web Intl API; on React Native you must include the appropriate polyfills.
+
+Checklist:
+
+- Use the latest versions of `intlayer` and `react-native-intlayer`.
+- Enable the Intlayer polyfill.
+- If you use `getLocaleName` or other Intl-API-based utilities, import these polyfills early (for example in `index.js` or `App.tsx`):
+
+```ts
+import "intl";
+import "@formatjs/intl-getcanonicallocales/polyfill";
+import "@formatjs/intl-locale/polyfill";
+import "@formatjs/intl-pluralrules/polyfill";
+import "@formatjs/intl-displaynames/polyfill";
+import "@formatjs/intl-listformat/polyfill";
+import "@formatjs/intl-numberformat/polyfill";
+import "@formatjs/intl-relativetimeformat/polyfill";
+import "@formatjs/intl-datetimeformat/polyfill";
+```
+
+- Verify your Metro configuration (resolver aliases, asset plugins, `tsconfig` paths) if modules fail to resolve.
+
+---

package/docs/en-GB/intlayer_with_react_router_v7.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-09-04
-updatedAt: 2026-05-31
+updatedAt: 2026-06-23
 title: "React Router v7 i18n - Complete guide to translate your app"
 description: "No more i18next. The 2026 guide to building a multilingual (i18n) React Router v7 app. Translate with AI agents and optimise bundle size, SEO and performances."
 keywords:
@@ -106,28 +106,44 @@ More than just an i18n solution, Intlayer provides an **self-hosted [visual edit
 
 Install the necessary packages using your preferred package manager:
 
+```bash packageManager="npm"
+npx intlayer-cli init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer-cli 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 react-intlayer
 npm install vite-intlayer --save-dev
-npx intlayer init
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer react-intlayer
 pnpm add vite-intlayer --save-dev
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer react-intlayer
 yarn add vite-intlayer --save-dev
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer react-intlayer
 bun add vite-intlayer --dev
-bun x intlayer init
 ```
 
 - **intlayer**
@@ -561,14 +577,17 @@ You can also use the `intlayerProxy` to add server-side routing to your applicat
 ```typescript {3,7} fileName="vite.config.ts"
 import { reactRouter } from "@react-router/dev/vite";
 import { defineConfig } from "vite";
-import { intlayer, intlayerProxy } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 
 export default defineConfig({
   plugins: [
-    intlayerProxy(), // should be placed first
     reactRouter(),
 
-    intlayer(),
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
   ],
 });
 ```

package/docs/en-GB/intlayer_with_react_router_v7_fs_routes.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-09-04
-updatedAt: 2026-05-31
+updatedAt: 2026-06-23
 title: "React Router v7 i18n - Complete guide to translate your app"
 description: "No more i18next. The 2026 guide to building a multilingual (i18n) React Router v7 app. Translate with AI agents and optimise bundle size, SEO and performances."
 keywords:
@@ -105,28 +105,44 @@ More than just an i18n solution, Intlayer provides an **self-hosted [visual edit
 
 Install the necessary packages using your preferred package manager:
 
+```bash packageManager="npm"
+npx intlayer-cli init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer-cli 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 react-intlayer
 npm install vite-intlayer --save-dev
-npx intlayer init
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer react-intlayer
 pnpm add vite-intlayer --save-dev
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer react-intlayer
 yarn add vite-intlayer --save-dev
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer react-intlayer
 bun add vite-intlayer --dev
-bun x intlayer init
 ```
 
 - **intlayer**
@@ -147,6 +163,25 @@ The core package that provides internationalisation tools for configuration mana
 
 </Steps>
 
+#### File Structure
+
+```bash
+app/
+├── root.tsx                         # Layout wrapper for locale routes
+└──routes/
+    ├── ($locale)._index.tsx         # Home page (/, /es, etc.)
+    ├── ($locale)._index.content.ts  # Home page content
+    ├── ($locale).about.tsx          # About page (/about, /es/about, etc.)
+    └── ($locale).about.content.ts   # About page content
+```
+
+The naming conventions:
+
+- `($locale)` - Optional dynamic segment for the locale parameter
+- `_layout` - Layout route that wraps child routes
+- `_index` - Index route (renders at the parent path)
+- `.` (dot) - Separates path segments (e.g., `($locale).about` → `/:locale?/about`)
+
 ## Step-by-Step Guide to Set Up Intlayer in a React Router v7 Application with File-System Routes
 
 <Tabs defaultTab="video">
@@ -506,14 +541,17 @@ You can also use the `intlayerProxy` to add server-side routing to your applicat
 ```typescript {3,7} fileName="vite.config.ts"
 import { reactRouter } from "@react-router/dev/vite";
 import { defineConfig } from "vite";
-import { intlayer, intlayerProxy } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 
 export default defineConfig({
   plugins: [
-    intlayerProxy(), // should be placed first
     reactRouter(),
 
-    intlayer(),
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
   ],
 });
 ```

package/docs/en-GB/intlayer_with_storybook.md

@@ -190,7 +190,13 @@ const config: StorybookConfig = {
     } as const;
 
     const viteConfig = defineConfig(() => ({
-      plugins: [intlayer()],
+      plugins: [
+        intlayer({
+          proxy: {
+            ignore: (req) => req.url?.startsWith("/api"),
+          },
+        }),
+      ],
     }));
 
     return mergeConfig(baseConfig, viteConfig(env));