@intlayer/docs 5.5.9 → 5.5.11

package/docs/en/packages/react-intlayer/useIntlayerAsync.md

@@ -0,0 +1,252 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-06-29
+title: useIntlayerAsync Hook Documentation | react-intlayer
+description: See how to use the useIntlayerAsync hook for react-intlayer package
+keywords:
+  - useIntlayerAsync
+  - dictionary
+  - key
+  - Intlayer
+  - Internationalization
+  - Documentation
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - packages
+  - react-intlayer
+  - useIntlayerAsync
+---
+
+# React Integration: `useIntlayerAsync` Hook Documentation
+
+The `useIntlayerAsync` hook extends the functionality of `useIntlayer` by not only returning pre-rendered dictionaries but also fetching updates asynchronously, making it ideal for applications that frequently update their localized content after the initial render.
+
+## Overview
+
+- **Asynchronous Dictionary Loading:**  
+  On initial mount, `useIntlayerAsync` first returns any pre-fetched or statically bundled locale dictionary (just like `useIntlayer` would) and then asynchronously fetches and merges any newly available remote dictionaries.
+- **Progress State Management:**  
+  The hook also provides an `isLoading` state, indicating when a remote dictionary is being fetched. This allows developers to display loading indicators or skeleton states for a smoother user experience.
+
+## Environment Setup
+
+Intlayer provides a headless Content Source Management (CSM) system that empowers non-developers to manage and update application content seamlessly. By using Intlayer’s intuitive dashboard, your team can edit localized text, images, and other resources without directly modifying code. This streamlines the content management process, fosters collaboration, and ensures that updates can be made quickly and easily.
+
+To get started with Intlayer:
+
+1. **Register and obtain an access token** at [https://intlayer.org/dashboard](https://intlayer.org/dashboard).
+2. **Add credentials to your configuration file:**  
+   In your React project, configure the Intlayer client with your credentials:
+
+   ```typescript fileName="intlayer.config.ts" codeFormat="typescript"
+   import type { IntlayerConfig } from "intlayer";
+
+   export default {
+     // ...
+     editor: {
+       clientId: process.env.INTLAYER_CLIENT_ID,
+       clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+     },
+   } satisfies IntlayerConfig;
+   ```
+
+   ```javascript fileName="intlayer.config.mjs" codeFormat="esm"
+   import { type IntlayerConfig } from "intlayer";
+
+   /** @type {import('intlayer').IntlayerConfig} */
+   const config = {
+     // ...
+     editor: {
+       clientId: process.env.INTLAYER_CLIENT_ID,
+       clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+     },
+   };
+
+   export default config;
+   ```
+
+   ```javascript fileName="intlayer.config.cjs" codeFormat="commonjs"
+   /** @type {import('intlayer').IntlayerConfig} */
+   const config = {
+     // ...
+     editor: {
+       clientId: process.env.INTLAYER_CLIENT_ID,
+       clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+     },
+   };
+
+   module.exports = config;
+   ```
+
+3. **Push a new locale dictionary to Intlayer:**
+
+   ```bash
+   npx intlayer dictionary push -d my-first-dictionary-key
+   ```
+
+   This command uploads your initial content dictionaries, making them available for asynchronous fetching and editing through the Intlayer platform.
+
+## Importing `useIntlayerAsync` in React
+
+In your React components, import `useIntlayerAsync`:
+
+```ts codeFormat="typescript"
+import { useIntlayerAsync } from "react-intlayer";
+```
+
+```js codeFormat="esm"
+import { useIntlayerAsync } from "react-intlayer";
+```
+
+```js codeFormat="commonjs"
+const { useIntlayerAsync } = require("react-intlayer");
+```
+
+## Parameters
+
+1. **`key`**:  
+   **Type**: `DictionaryKeys`  
+   The dictionary key used to identify the localized content block. This key should be defined in your content declaration files.
+
+2. **`locale`** (optional):  
+   **Type**: `Locales`  
+   The specific locale you want to target. If omitted, the hook uses the locale from the current Intlayer context.
+
+3. **`isRenderEditor`** (optional, defaults to `true`):  
+   **Type**: `boolean`  
+   Determines whether the content should be ready for rendering with the Intlayer editor overlay. If set to `false`, the returned dictionary data will exclude editor-specific features.
+
+## Return Value
+
+The hook returns a dictionary object containing localized content keyed by `key` and `locale`. It also includes an `isLoading` boolean indicating whether a remote dictionary is currently being fetched.
+
+## Example Usage in a React Component
+
+```tsx fileName="src/components/ComponentExample.tsx" codeFormat="typescript"
+import { useEffect, type FC } from "react";
+import { useIntlayerAsync } from "react-intlayer";
+
+export const ComponentExample: FC = () => {
+  const { title, description, isLoading } = useIntlayerAsync("async-component");
+
+  useEffect(() => {
+    if (isLoading) {
+      console.log("Content is loading...");
+    }
+  }, [isLoading]);
+
+  return (
+    <div>
+      {isLoading ? (
+        <div>
+          <h1>Loading…</h1>
+          <p>Please wait while content updates.</p>
+        </div>
+      ) : (
+        <div>
+          <h1>{title.value}</h1>
+          <p>{description.value}</p>
+        </div>
+      )}
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/ComponentExample.mjx" codeFormat="esm"
+import { useEffect } from "react";
+import { useIntlayerAsync } from "react-intlayer";
+
+const ComponentExample = () => {
+  const { title, description, isLoading } = useIntlayerAsync("async-component");
+
+  useEffect(() => {
+    if (isLoading) {
+      console.log("Content is loading...");
+    }
+  }, [isLoading]);
+
+  return (
+    <div>
+      {isLoading ? (
+        <div>
+          <h1>Loading…</h1>
+          <p>Please wait while content updates.</p>
+        </div>
+      ) : (
+        <div>
+          <h1>{title.value}</h1>
+          <p>{description.value}</p>
+        </div>
+      )}
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/ComponentExample.csx" codeFormat="commonjs"
+const { useEffect } = require("react");
+const { useIntlayerAsync } = require("react-intlayer");
+
+const ComponentExample = () => {
+  const { title, description, isLoading } = useIntlayerAsync("async-component");
+
+  useEffect(() => {
+    if (isLoading) {
+      console.log("Content is loading...");
+    }
+  }, [isLoading]);
+
+  return (
+    <div>
+      {isLoading ? (
+        <div>
+          <h1>Loading…</h1>
+          <p>Please wait while content updates.</p>
+        </div>
+      ) : (
+        <div>
+          <h1>{title.value}</h1>
+          <p>{description.value}</p>
+        </div>
+      )}
+    </div>
+  );
+};
+```
+
+**Key Points:**
+
+- On initial render, `title` and `description` come from the pre-fetched or statically embedded locale dictionary.
+- While `isLoading` is `true`, a background request fetches an updated dictionary.
+- Once the fetch completes, `title` and `description` are updated with the newest content, and `isLoading` returns to `false`.
+
+## Handling Attribute Localization
+
+You can also retrieve localized attribute values for various HTML properties (e.g., `alt`, `title`, `aria-label`):
+
+```jsx
+<img src={title.image.src.value} alt={title.image.alt.value} />
+```
+
+## Dictionary Files
+
+All content keys must be defined in your content declaration files for type safety and to prevent runtime errors. These files enable TypeScript validation, ensuring you always reference existing keys and locales.
+
+Instructions for setting up content declaration files are available [here](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/get_started.md).
+
+## Further Information
+
+- **Intlayer Visual Editor:**  
+  Integrate with the Intlayer visual editor for managing and editing content directly from the UI. More details [here](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_visual_editor.md).
+
+---
+
+**In summary**, `useIntlayerAsync` is a powerful React hook designed to enhance the user experience and maintain content freshness by merging pre-rendered or pre-fetched dictionaries with asynchronous dictionary updates. By leveraging `isLoading` and TypeScript-based content declarations, you can seamlessly integrate dynamic, localized content into your React applications.
+
+## Doc History
+
+- 5.5.10 - 2025-06-29: Init history

package/docs/en/packages/react-intlayer/useLocale.md

@@ -0,0 +1,210 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-06-29
+title: useLocale Hook Documentation | react-intlayer
+description: See how to use the useLocale hook for react-intlayer package
+keywords:
+  - useLocale
+  - dictionary
+  - key
+  - Intlayer
+  - Internationalization
+  - Documentation
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - packages
+  - react-intlayer
+  - useLocale
+---
+
+# React Integration: `useLocale` Hook Documentation
+
+This section provides comprehensive details on the `useLocale` hook from the `react-intlayer` library, designed for handling locale management in React applications.
+
+## Importing `useLocale` in React
+
+To integrate the `useLocale` hook into your React application, import it from its respective package:
+
+```typescript codeFormat="typescript"
+import { useLocale } from "react-intlayer"; // Used in React components for locale management
+```
+
+```javascript codeFormat="esm"
+import { useLocale } from "react-intlayer"; // Used in React components for locale management
+```
+
+```javascript codeFormat="commonjs"
+const { useLocale } = require("react-intlayer"); // Used in React components for locale management
+```
+
+## Overview
+
+The `useLocale` hook offers an easy way to access and manipulate the locale settings within React components. It provides access to the current locale, the default locale, all available locales, and functions to update the locale settings.
+
+## Usage
+
+Here’s how you can use the `useLocale` hook within a React component:
+
+```tsx fileName="src/components/LocaleSwitcher.tsx" codeFormat="typescript"
+import type { FC } from "react";
+import { useLocale } from "react-intlayer";
+
+const LocaleSwitcher: FC = () => {
+  const { locale, defaultLocale, availableLocales, setLocale } = useLocale();
+
+  return (
+    <div>
+      <h1>Current Locale: {locale}</h1>
+      <p>Default Locale: {defaultLocale}</p>
+      <select value={locale} onChange={(e) => setLocale(e.target.value)}>
+        {availableLocales.map((loc) => (
+          <option key={loc} value={loc}>
+            {loc}
+          </option>
+        ))}
+      </select>
+    </div>
+  );
+};
+
+export default LocaleSwitcher;
+```
+
+```jsx fileName="src/components/LocaleSwitcher.mjx" codeFormat="esm"
+import { useLocale } from "react-intlayer";
+
+const LocaleSwitcher = () => {
+  const { locale, defaultLocale, availableLocales, setLocale } = useLocale();
+
+  return (
+    <div>
+      <h1>Current Locale: {locale}</h1>
+      <p>Default Locale: {defaultLocale}</p>
+      <select value={locale} onChange={(e) => setLocale(e.target.value)}>
+        {availableLocales.map((loc) => (
+          <option key={loc} value={loc}>
+            {loc}
+          </option>
+        ))}
+      </select>
+    </div>
+  );
+};
+
+export default LocaleSwitcher;
+```
+
+```jsx fileName="src/components/LocaleSwitcher.csx" codeFormat="commonjs"
+const { useLocale } = require("react-intlayer");
+
+const LocaleSwitcher = () => {
+  const { locale, defaultLocale, availableLocales, setLocale } = useLocale();
+
+  return (
+    <div>
+      <h1>Current Locale: {locale}</h1>
+      <p>Default Locale: {defaultLocale}</p>
+      <select value={locale} onChange={(e) => setLocale(e.target.value)}>
+        {availableLocales.map((loc) => (
+          <option key={loc} value={loc}>
+            {loc}
+          </option>
+        ))}
+      </select>
+    </div>
+  );
+};
+
+export default LocaleSwitcher;
+```
+
+## Parameters and Return Values
+
+When you invoke the `useLocale` hook, it returns an object containing the following properties:
+
+- **`locale`**: The current locale as set in the React context.
+- **`defaultLocale`**: The primary locale defined in the configuration.
+- **`availableLocales`**: A list of all locales available as defined in the configuration.
+- **`setLocale`**: A function to update the current locale within the application's context.
+
+## Example
+
+This example shows a component that uses the `useLocale` hook to render a locale switcher, allowing users to dynamically change the locale of the application:
+
+```tsx fileName="src/components/LocaleSelector.tsx" codeFormat="typescript"
+import type { FC } from "react";
+import { useLocale } from "react-intlayer";
+
+const LocaleSelector: FC = () => {
+  const { locale, setLocale, availableLocales } = useLocale();
+
+  const handleLocaleChange = (newLocale) => {
+    setLocale(newLocale);
+  };
+
+  return (
+    <select value={locale} onChange={(e) => handleLocaleChange(e.target.value)}>
+      {availableLocales.map((locale) => (
+        <option key={locale} value={locale}>
+          {locale}
+        </option>
+      ))}
+    </select>
+  );
+};
+```
+
+```jsx fileName="src/components/LocaleSelector.mjx" codeFormat="esm"
+import { useLocale } from "react-intlayer";
+
+const LocaleSelector = () => {
+  const { locale, setLocale, availableLocales } = useLocale();
+
+  const handleLocaleChange = (newLocale) => {
+    setLocale(newLocale);
+  };
+
+  return (
+    <select value={locale} onChange={(e) => handleLocaleChange(e.target.value)}>
+      {availableLocales.map((locale) => (
+        <option key={locale} value={locale}>
+          {locale}
+        </option>
+      ))}
+    </select>
+  );
+};
+```
+
+```jsx fileName="src/components/LocaleSelector.csx" codeFormat="commonjs"
+const { useLocale } = require("react-intlayer");
+
+const LocaleSelector = () => {
+  const { locale, setLocale, availableLocales } = useLocale();
+
+  const handleLocaleChange = (newLocale) => {
+    setLocale(newLocale);
+  };
+
+  return (
+    <select value={locale} onChange={(e) => handleLocaleChange(e.target.value)}>
+      {availableLocales.map((locale) => (
+        <option key={locale} value={locale}>
+          {locale}
+        </option>
+      ))}
+    </select>
+  );
+};
+```
+
+## Conclusion
+
+The `useLocale` hook from `react-intlayer` is an essential tool for managing locales in your React applications, providing the functionality needed to adapt your application to various international audiences effectively.
+
+## Doc History
+
+- 5.5.10 - 2025-06-29: Init history

package/docs/en/packages/react-native-intlayer/index.md

@@ -0,0 +1,83 @@
+---
+createdAt: 2025-03-13
+updatedAt: 2025-06-29
+title: Package Documentation | react-native-intlayer
+description: See how to use the react-native-intlayer package
+keywords:
+  - Intlayer
+  - React Native
+  - react-native-intlayer
+  - Internationalization
+  - Documentation
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - packages
+  - react-native-intlayer
+---
+
+# react-native-intlayer: Internationalize (i18n) an React Native application
+
+**Intlayer** is a suite of packages designed specifically for JavaScript developers. It is compatible with frameworks like React, React, and Express.js.
+
+**The `react-native-intlayer` package** allows you to internationalize your Vite application. It includes the Metro plugin to set the configuration through environment variables into the [Metro bundler](https://docs.expo.dev/guides/customizing-metro/).
+
+## Why Internationalize Your React Native Application?
+
+Internationalizing your React Native application is essential for serving a global audience effectively. It allows your application to deliver content and messages in the preferred language of each user. This capability enhances user experience and broadens your application's reach by making it more accessible and relevant to people from different linguistic backgrounds.
+
+## Configuration
+
+The `react-native-intlayer` package works seamlessly with the [`react-intlayer` package](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/react-intlayer/index.md), and the [`intlayer` package](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/intlayer/index.md). Have a look at the relevant documentation for more information.
+
+## Installation
+
+Install the necessary package using your preferred package manager:
+
+```bash packageManager="npm"
+npm install react-native-intlayer
+```
+
+```bash packageManager="yarn"
+yarn add react-native-intlayer
+```
+
+```bash packageManager="pnpm"
+pnpm add react-native-intlayer
+```
+
+## Example of usage
+
+See an example of how to include the plugins into your vite configuration.
+
+```js
+// metro.config.js
+const { getDefaultConfig } = require("expo/metro-config");
+const { configMetroIntlayer } = require("react-native-intlayer/metro");
+
+module.exports = (async () => {
+  const defaultConfig = getDefaultConfig(__dirname);
+
+  return await configMetroIntlayer(defaultConfig);
+})();
+```
+
+## Mastering the internationalization of your Vite application
+
+Intlayer provides a lot of features to help you internationalize your Vite application.
+
+**To learn more about these features, refer to the [React Internationalization (i18n) with Intlayer and React Native](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_react_native+expo.md) guide for React Native Application.**
+
+## Read about Intlayer
+
+- [Intlayer Website](https://intlayer.org)
+- [Intlayer Documentation](https://intlayer.org/doc)
+- [Intlayer GitHub](https://github.com/aymericzip/intlayer)
+
+- [Ask your questions to our smart documentation](https://intlayer.org/docchat)
+
+## Doc History
+
+- 5.5.10 - 2025-06-29: Init history

package/docs/en/packages/react-scripts-intlayer/index.md

@@ -0,0 +1,80 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-06-29
+title: Package Documentation | react-scripts-intlayer
+description: See how to use the react-scripts-intlayer package
+keywords:
+  - Intlayer
+  - react-scripts-intlayer
+  - Internationalization
+  - Documentation
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - packages
+  - react-scripts-intlayer
+---
+
+# react-scripts-intlayer: NPM Package to use Intlayer in a React Create App application
+
+**Intlayer** is a suite of packages designed specifically for JavaScript developers. It is compatible with frameworks like React, React, and Express.js.
+
+**The `react-scripts-intlayer` package** 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 includes additional configuration for the [Webpack](https://webpack.js.org/) bundler.
+
+## Configuration
+
+The `react-scripts-intlayer` package works seamlessly with the [`react-intlayer` package](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/react-intlayer/index.md), and the [`intlayer` package](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/intlayer/index.md). Have a look at the relevant documentation for more information.
+
+## Installation
+
+Install the necessary package using your preferred package manager:
+
+```bash packageManager="npm"
+npm install react-scripts-intlayer
+```
+
+```bash packageManager="yarn"
+yarn add react-scripts-intlayer
+```
+
+```bash packageManager="pnpm"
+pnpm add react-scripts-intlayer
+```
+
+## Usage
+
+### CLI Commands
+
+The `react-scripts-intlayer` package provides the following CLI commands:
+
+- `npx react-scripts-intlayer build`: Builds React application with the Intlayer configuration.
+- `npx react-scripts-intlayer start`: Starts the development server with the Intlayer configuration.
+
+### Replace package.json scripts
+
+To use the `react-scripts-intlayer` package, you need to replace the `package.json` scripts with the following commands:
+
+```json fileName="package.json"
+{
+  "scripts": {
+    "start": "react-scripts-intlayer start",
+    "build": "react-scripts-intlayer build"
+  }
+}
+```
+
+## Use custom Webpack configuration
+
+`react-scripts-intlayer` is based on [craco](https://craco.js.org/), which allows you to customize the Webpack configuration.
+If you need to customize the Webpack configuration, 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).
+
+## Read the full Intlayer guide for React Create App
+
+Intlayer provides a lot of features to help you internationalize your React application.
+[See how to use intlayer with React Create App](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_create_react_app.md).
+
+## Doc History
+
+- 5.5.10 - 2025-06-29: Init history

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

@@ -0,0 +1,54 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-06-29
+title: Package Documentation | solid-intlayer
+description: See how to use the solid-intlayer package
+keywords:
+  - Intlayer
+  - solid-intlayer
+  - Internationalization
+  - Documentation
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - packages
+  - solid-intlayer
+---
+
+# solid-intlayer: NPM Package to internationalize (i18n) an Solid application
+
+**Intlayer** is a suite of packages designed specifically for JavaScript developers. It is compatible with frameworks like Solid, Solid, and Express.js.
+
+**The `solid-intlayer` package** allows you to internationalize your Solid application. It provides context providers and hooks for Solid internationalization.
+
+## Why Internationalize Your Solid Application?
+
+Internationalizing your Solid application is essential for serving a global audience effectively. It allows your application to deliver content and messages in the preferred language of each user. This capability enhances user experience and broadens your application's reach by making it more accessible and relevant to people from different linguistic backgrounds.
+
+## Why to integrate Intlayer?
+
+- **JavaScript-Powered Content Management**: Harness the flexibility of JavaScript to define and manage your content efficiently.
+- **Type-Safe Environment**: Leverage 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.
+
+## Installation
+
+Install the necessary package using your preferred package manager:
+
+```bash packageManager="npm"
+npm install solid-intlayer
+```
+
+```bash packageManager="yarn"
+yarn add solid-intlayer
+```
+
+```bash packageManager="pnpm"
+pnpm add solid-intlayer
+```
+
+## Doc History
+
+- 5.5.10 - 2025-06-29: Init history