@intlayer/docs 5.7.6-canary.0 → 5.7.7

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

@@ -1,254 +0,0 @@
----
-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
-
-| Version | Date       | Changes      |
-| ------- | ---------- | ------------ |
-| 5.5.10  | 2025-06-29 | Init history |

package/docs/en-GB/packages/next-intlayer/useIntlayerAsync.md

@@ -1,237 +0,0 @@
----
-createdAt: 2024-08-11
-updatedAt: 2025-06-29
-title: useIntlayerAsync Hook Documentation | next-intlayer
-description: See how to use the useIntlayerAsync hook for next-intlayer package
-keywords:
-  - useIntlayerAsync
-  - dictionary
-  - key
-  - Intlayer
-  - Internationalisation
-  - Documentation
-  - Next.js
-  - JavaScript
-  - React
-slugs:
-  - doc
-  - packages
-  - next-intlayer
-  - useIntlayerAsync
----
-
-# Next.js 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 localised content after the initial render.
-
-## Overview
-
-- **Asynchronous Dictionary Loading:**  
-  On the client side, `useIntlayerAsync` first returns the pre-rendered locale dictionary (just like `useIntlayer`) 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 localised 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, you will first need to register and obtain an access token in the [dashboard](https://intlayer.org/dashboard). Once you have your credentials, add them to your configuration file as shown below:
-
-```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;
-```
-
-After configuring your credentials, you can push a new locale dictionary to Intlayer by running:
-
-```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 Next.js
-
-Since `useIntlayerAsync` is intended for **client-side** components, you’ll import it from the same client entry point as `useIntlayer`:
-
-```tsx codeFormat="typescript"
-"use client";
-
-import { useIntlayerAsync } from "next-intlayer";
-```
-
-```javascript codeFormat="esm"
-"use client";
-
-import { useIntlayerAsync } from "next-intlayer";
-```
-
-```javascript codeFormat="commonjs"
-"use client";
-
-const { useIntlayerAsync } = require("next-intlayer");
-```
-
-Make sure that the importing file is annotated with `"use client"` at the top, if you’re using Next.js App Router with server and client components separated.
-
-## Parameters
-
-1. **`key`**:
-   **Type**: `DictionaryKeys`
-   The dictionary key used to identify the localised 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 client 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 localised content keyed by `key` and `locale`. It also includes an `isLoading` boolean indicating whether a remote dictionary is currently being fetched.
-
-## Example Usage in Next.js
-
-### Client-Side Component Example
-
-```tsx fileName="src/components/AsyncClientComponentExample.tsx" codeFormat="typescript"
-"use client";
-
-import { useEffect, type FC } from "react";
-import { useIntlayerAsync } from "next-intlayer";
-
-export const AsyncClientComponentExample: FC = () => {
-  const { title, description, isLoading } = useIntlayerAsync("async-component");
-
-  useEffect(() => {
-    if (isLoading) {
-      console.log("Content is loading...");
-    }
-  }, [isLoading]);
-
-  return (
-    <div>
-      <h1>{title.value}</h1>
-      <p>{description.value}</p>
-    </div>
-  );
-};
-```
-
-```jsx fileName="src/components/AsyncClientComponentExample.mjx" codeFormat="esm"
-"use client";
-
-import { useEffect } from "react";
-import { useIntlayerAsync } from "next-intlayer";
-
-const AsyncClientComponentExample = () => {
-  const { title, description, isLoading } = useIntlayerAsync("async-component");
-
-  useEffect(() => {
-    if (isLoading) {
-      console.log("Content is loading...");
-    }
-  }, [isLoading]);
-
-  return (
-    <div>
-      <h1>{title.value}</h1>
-      <p>{description.value}</p>
-    </div>
-  );
-};
-```
-
-```jsx fileName="src/components/AsyncClientComponentExample.csx" codeFormat="commonjs"
-"use client";
-
-const { useEffect } = require("react");
-const { useIntlayerAsync } = require("next-intlayer");
-
-const AsyncClientComponentExample = () => {
-  const { title, description, isLoading } = useIntlayerAsync("async-component");
-
-  useEffect(() => {
-    if (isLoading) {
-      console.log("Content is loading...");
-    }
-  }, [isLoading]);
-
-  return (
-    <div>
-      <h1>{title.value}</h1>
-      <p>{description.value}</p>
-    </div>
-  );
-};
-```
-
-**Key Points:**
-
-- On initial render, `title` and `description` come from the pre-rendered locale dictionary.
-- While `isLoading` is `true`, a remote request is made in the background to fetch an updated dictionary.
-- Once the fetch completes, `title` and `description` are updated with the newest content, and `isLoading` returns to `false`.
-
-## Handling Attribute Localisation
-
-As with `useIntlayer`, you can retrieve localised attribute values for various HTML properties (e.g., `alt`, `title`, `aria-label`):
-
-```tsx
-<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-GB/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-GB/intlayer_visual_editor.md).
-
----
-
-**In summary**, `useIntlayerAsync` is a powerful client-side hook designed to enhance the user experience and maintain content freshness by combining pre-rendered dictionaries with asynchronous dictionary updates. By leveraging `isLoading` and TypeScript-based content declarations, you can seamlessly integrate dynamic, localised content into your Next.js applications.
-
-## Doc History
-
-- 5.5.10 - 2025-06-29: Init history