@intlayer/docs 7.5.12 → 7.5.14

package/docs/uk/packages/next-intlayer/useIntlayer.md

@@ -0,0 +1,263 @@
+---
+createdAt: 2025-08-23
+updatedAt: 2025-08-23
+title: Інструкція по використанню хуку useIntlayer | next-intlayer
+description: Дізнайтеся, як використовувати хук useIntlayer для пакета next-intlayer
+keywords:
+  - useIntlayer
+  - словник
+  - ключ
+  - Intlayer
+  - Internationalization
+  - Документація
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - packages
+  - next-intlayer
+  - useIntlayer
+history:
+  - version: 5.5.10
+    date: 2025-06-29
+    changes: Ініціалізація історії
+---
+
+# Інтеграція з Next.js: документація хуку `useIntlayer`
+
+Хук `useIntlayer` призначений для застосунків Next.js для ефективного отримання та керування локалізованим контентом. Ця документація зосереджена на тому, як використовувати хук у проектах Next.js, забезпечуючи належні практики локалізації.
+
+## Імпорт `useIntlayer` в Next.js
+
+Залежно від того, чи працюєте ви з компонентами на боці клієнта чи на боці сервера в додатку Next.js, хук `useIntlayer` можна імпортувати таким чином:
+
+- **Клієнтський компонент:**
+
+  ```typescript codeFormat="typescript"
+  import { useIntlayer } from "next-intlayer"; // Використовується в компонентах на боці клієнта
+  ```
+
+  ```javascript codeFormat="esm"
+  import { useIntlayer } from "next-intlayer"; // Використовується в компонентах на боці клієнта
+  ```
+
+  ```javascript codeFormat="commonjs"
+  const { useIntlayer } = require("next-intlayer"); // Використовується в компонентах на боці клієнта
+  ```
+
+- **Серверний компонент:**
+
+  ```tsx codeFormat="typescript"
+  import { useIntlayer } from "next-intlayer/server"; // Використовується в компонентах на боці сервера
+  ```
+
+  ```javascript codeFormat="esm"
+  import { useIntlayer } from "next-intlayer/server"; // Використовується у серверних компонентах
+  ```
+
+  ```javascript codeFormat="commonjs"
+  const { useIntlayer } = require("next-intlayer/server"); // Використовується у серверних компонентах
+  ```
+
+## Параметри
+
+1. **`key`**: Рядковий ідентифікатор ключа словника, з якого потрібно отримати вміст.
+2. **`locale`** (необов'язковий): Конкретна локаль для використання. Якщо пропущено, хук за замовчуванням використовує локаль, встановлену в клієнтському або серверному контексті.
+
+## Файли словника
+
+Критично, щоб всі ключі вмісту були визначені у файлах декларації контенту, щоб уникнути помилок під час виконання та забезпечити безпеку типів. Такий підхід також полегшує інтеграцію з TypeScript для валідації на етапі компіляції.
+
+Інструкції щодо налаштування файлів декларації контенту доступні [тут](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/dictionary/content_file.md).
+
+## Приклад використання в Next.js
+
+Ось як ви можете реалізувати хук `useIntlayer` на сторінці Next.js, щоб динамічно завантажувати локалізований контент залежно від поточної локалі застосунку:
+
+```tsx fileName="src/pages/[locale]/index.tsx" codeFormat="typescript"
+import { ClientComponentExample } from "@components/ClientComponentExample";
+import { ServerComponentExample } from "@components/ServerComponentExample";
+import { type NextPageIntlayer, IntlayerClientProvider } from "next-intlayer";
+import { useIntlayer, IntlayerServerProvider } from "next-intlayer/server";
+
+const HomePage: NextPageIntlayer = async ({ params }) => {
+  const { locale } = await params;
+
+  const content = useIntlayer("homepage", locale);
+
+  return (
+    <>
+      <p>{content.introduction}</p>
+      <IntlayerClientProvider locale={locale}>
+        <ClientComponentExample />
+      </IntlayerClientProvider>
+      <IntlayerServerProvider locale={locale}>
+        <ServerComponentExample />
+      </IntlayerServerProvider>
+    </>
+  );
+};
+```
+
+```jsx fileName="src/pages/[locale]/index.csx" codeFormat="esm"
+import { ClientComponentExample } from "@components/ClientComponentExample";
+import { ServerComponentExample } from "@components/ServerComponentExample";
+import { IntlayerClientProvider } from "next-intlayer";
+import { IntlayerServerProvider, useIntlayer } from "next-intlayer/server";
+
+const HomePage = ({ locale }) => {
+  const content = useIntlayer("homepage", locale);
+
+  return (
+    <>
+      <p>{content.introduction}</p>
+      <IntlayerClientProvider locale={locale}>
+        <ClientComponentExample />
+      </IntlayerClientProvider>
+      <IntlayerServerProvider locale={locale}>
+        <ServerComponentExample />
+      </IntlayerServerProvider>
+    </>
+  );
+};
+```
+
+```jsx fileName="src/components/ClientComponentExample.csx" codeFormat="commonjs"
+const {
+  ClientComponentExample,
+} = require("@components/ClientComponentExample");
+const {
+  ServerComponentExample,
+} = require("@components/ServerComponentExample");
+const { IntlayerClientProvider } = require("next-intlayer");
+const { useIntlayer } = require("next-intlayer/server");
+
+const HomePage = ({ locale }) => {
+  const content = useIntlayer("homepage", locale);
+
+  return (
+    <>
+      <p>{content.introduction}</p>
+      <IntlayerClientProvider locale={locale}>
+        <ClientComponentExample />
+      </IntlayerClientProvider>
+      <IntlayerServerProvider locale={locale}>
+        <ServerComponentExample />
+      </IntlayerServerProvider>
+    </>
+  );
+};
+```
+
+```tsx fileName="src/components/ClientComponentExample.tsx" codeFormat="typescript"
+"use-client";
+
+import type { FC } from "react";
+import { useIntlayer } from "next-intlayer";
+
+const ClientComponentExample: FC = () => {
+  const content = useIntlayer("component-content");
+
+  return (
+    <div>
+      <h1>{content.title}</h1>
+      <p>{content.description}</p>
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/ClientComponentExample.msx" codeFormat="esm"
+"use-client";
+
+import { useIntlayer } from "next-intlayer";
+
+const ServerComponentExample = () => {
+  const content = useIntlayer("component-content");
+
+  return (
+    <div>
+      <h1>{content.title}</h1>
+      <p>{content.description}</p>
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/ClientComponentExample.csx" codeFormat="commonjs"
+"use-client";
+
+const { useIntlayer } = require("next-intlayer");
+
+const ServerComponentExample = () => {
+  const content = useIntlayer("component-content");
+
+  return (
+    <div>
+      <h1>{content.title}</h1>
+      <p>{content.description}</p>
+    </div>
+  );
+};
+```
+
+```tsx fileName="src/components/ServerComponentExample.tsx" codeFormat="typescript"
+import type { FC } from "react";
+import { useIntlayer } from "next-intlayer/server";
+
+const ServerComponentExample: FC = () => {
+  const content = useIntlayer("component-content");
+
+  return (
+    <div>
+      <h1>{content.title}</h1>
+      <p>{content.description}</p>
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/ServerComponentExample.mjx" codeFormat="esm"
+import { useIntlayer } from "next-intlayer/server";
+
+const ServerComponentExample = () => {
+  const content = useIntlayer("component-content");
+
+  return (
+    <div>
+      <h1>{content.title}</h1>
+      <p>{content.description}</p>
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/ServerComponentExample.csx" codeFormat="commonjs"
+const { useIntlayer } = require("next-intlayer/server");
+
+const ServerComponentExample = () => {
+  const content = useIntlayer("component-content");
+
+  return (
+    <div>
+      <h1>{content.title}</h1>
+      <p>{content.description}</p>
+    </div>
+  );
+};
+```
+
+## Локалізація атрибутів
+
+Щоб локалізувати атрибути, такі як `alt`, `title`, `href`, `aria-label` тощо, переконайтеся, що ви правильно посилаєтеся на вміст:
+
+```tsx
+<img src={content.image.src.value} alt={content.image.alt.value} />
+```
+
+## Додаткова інформація
+
+- **Intlayer Visual Editor**: Дізнайтеся, як використовувати візуальний редактор для зручнішого керування контентом [тут](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/intlayer_visual_editor.md).
+
+Ця документація описує використання хуку `useIntlayer` саме в середовищах Next.js, пропонуючи надійне рішення для керування локалізацією у ваших застосунках Next.js.

package/docs/uk/packages/next-intlayer/useLocale.md

@@ -0,0 +1,166 @@
+---
+createdAt: 2025-08-23
+updatedAt: 2025-10-09
+title: Документація хуку useLocale | next-intlayer
+description: Дивіться, як використовувати хук useLocale у пакеті next-intlayer
+keywords:
+  - useLocale
+  - dictionary
+  - key
+  - Intlayer
+  - Internationalization
+  - Documentation
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - packages
+  - next-intlayer
+  - useLocale
+history:
+  - version: 6.2.0
+    date: 2025-10-09
+    changes: Додано документацію для хуку `useLocale` з опцією `onLocaleChange`
+  - version: 5.5.10
+    date: 2025-06-29
+    changes: Ініціалізація історії
+---
+
+# Інтеграція з Next.js: документація хуку `useLocale` для `next-intlayer`
+
+This section offers detailed documentation on the `useLocale` hook tailored for Next.js applications within the `next-intlayer` library. It is designed to handle locale changes and routing efficiently.
+
+## Імпорт `useLocale` у Next.js
+
+Щоб використовувати хук `useLocale` у вашому Next.js застосунку, імпортуйте його, як показано нижче:
+
+```javascript
+import { useLocale } from "next-intlayer"; // Використовується для керування локалями та маршрутизацією в Next.js
+```
+
+## Використання
+
+Ось як реалізувати хук `useLocale` у компоненті Next.js:
+
+```tsx fileName="src/components/LocaleSwitcher.tsx" codeFormat="typescript"
+"use client";
+
+import type { FC } from "react";
+import { Locales } from "intlayer";
+import { useLocale } from "next-intlayer";
+
+const LocaleSwitcher: FC = () => {
+  const { locale, defaultLocale, availableLocales, setLocale } = useLocale();
+
+  return (
+    <div>
+      <h1>Поточна локаль: {locale}</h1>
+      <p>Локаль за замовчуванням: {defaultLocale}</p>
+      <select value={locale} onChange={(e) => setLocale(e.target.value)}>
+        {availableLocales.map((loc) => (
+          <option key={loc} value={loc}>
+            {loc}
+          </option>
+        ))}
+      </select>
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/LocaleSwitcher.mjx" codeFormat="esm"
+"use client";
+
+import { Locales } from "intlayer";
+import { useLocale } from "next-intlayer";
+
+const LocaleSwitcher = () => {
+  const { locale, defaultLocale, availableLocales, setLocale } = useLocale();
+
+  return (
+    <div>
+      <h1>Поточна локаль: {locale}</h1>
+      <p>Мова за замовчуванням: {defaultLocale}</p>
+      <select value={locale} onChange={(e) => setLocale(e.target.value)}>
+        {availableLocales.map((loc) => (
+          <option key={loc} value={loc}>
+            {loc}
+          </option>
+        ))}
+      </select>
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/LocaleSwitcher.csx" codeFormat="commonjs"
+"use client";
+
+const { Locales } = require("intlayer");
+const { useLocale } = require("next-intlayer");
+
+const LocaleSwitcher = () => {
+  const { locale, defaultLocale, availableLocales, setLocale } = useLocale();
+
+  return (
+    <div>
+      <h1>Поточна локаль: {locale}</h1>
+      <p>Мова за замовчуванням: {defaultLocale}</p>
+      <select value={locale} onChange={(e) => setLocale(e.target.value)}>
+        {availableLocales.map((loc) => (
+          <option key={loc} value={loc}>
+            {loc}
+          </option>
+        ))}
+      </select>
+    </div>
+  );
+};
+```
+
+## Параметри
+
+Хук `useLocale` приймає такі параметри:
+
+- **`onLocaleChange`**: Рядок, який визначає, як має оновлюватися URL під час зміни локалі. Може бути `"replace"`, `"push"` або `"none"`.
+
+  > Розглянемо приклад:
+  >
+  > 1. Ви перебуваєте на `/fr/home`
+  > 2. Ви переходите на `/fr/about`
+  > 3. Ви переключаєтесь на `/es/about`
+  > 4. Ви натискаєте кнопку "назад" у браузері
+  >
+  > Поведінка відрізнятиметься залежно від значення `onLocaleChange`:
+  >
+  > - `undefined`: (за замовчуванням) Оновлює лише локаль у клієнтському контексті та встановлює cookie, не змінюючи URL.
+  >   -> Кнопка «назад» перейде на `/fr/home`
+  > - `"replace"`: Замінює поточний URL на новий локалізований URL і встановлює cookie.
+  >   -> Кнопка «назад» перейде на `/es/home`
+  > - `"push"`: Додає новий локалізований URL в історію браузера та встановлює cookie.
+  >   -> Кнопка «назад» перейде на `/fr/about`
+  > - `(locale) => void`: Встановлює cookie і викликає кастомну функцію, яка буде запущена при зміні локалі.
+  >
+  >   Опція `undefined` — поведінка за замовчуванням: ми рекомендуємо використовувати компонент `Link` для навігації на нову локаль.
+  >   Приклад:
+  >
+  >   ```tsx
+  >   <Link href="/es/about" replace>
+  >     Про нас
+  >   </Link>
+  >   ```
+
+## Повернуті значення
+
+Коли ви викликаєте хук `useLocale`, він повертає об'єкт, що містить наступні властивості:
+
+- **`locale`**: Поточна локаль, як встановлено в контексті React.
+- **`defaultLocale`**: Основна локаль, визначена в конфігурації.
+- **`availableLocales`**: Список усіх доступних локалей, визначених у конфігурації.
+- **`setLocale`**: Функція для зміни локалі застосунку та відповідного оновлення URL. Вона враховує правила префіксів, чи додавати локаль у шлях залежно від конфігурації. Використовує `useRouter` з `next/navigation` для навігаційних функцій, таких як `push` і `refresh`.
+- **`pathWithoutLocale`**: обчислювана властивість, яка повертає шлях без локалі. Корисна для порівняння URL-адрес. Наприклад, якщо поточна локаль — `fr`, а URL — `fr/my_path`, то шлях без локалі буде `/my_path`. Використовує `usePathname` з `next/navigation` для отримання поточного шляху.
+
+## Висновок
+
+Хук `useLocale` з `next-intlayer` — це ключовий інструмент для керування локалями в додатках Next.js. Він пропонує інтегрований підхід для адаптації вашого застосунку до кількох локалей, безшовно обробляючи збереження локалі, управління станом та модифікації URL.