@intlayer/docs 7.5.11 → 7.5.13

package/docs/uk/packages/intlayer/getEnumeration.md

@@ -0,0 +1,159 @@
+---
+createdAt: 2025-08-23
+updatedAt: 2025-08-23
+title: Документація функції getEnumeration | intlayer
+description: Дивіться, як використовувати функцію getEnumeration у пакеті intlayer
+keywords:
+  - getEnumeration
+  - переклад
+  - Intlayer
+  - intlayer
+  - Інтернаціоналізація
+  - Документація
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - packages
+  - intlayer
+  - getEnumeration
+history:
+  - version: 5.5.10
+    date: 2025-06-29
+    changes: Ініціалізація історії
+---
+
+# Документація: функція `getEnumeration` в `intlayer`
+
+## Опис
+
+Функція `getEnumeration` повертає контент, що відповідає певній кількості, на основі заздалегідь визначених умов в об'єкті перечислення. Умови задаються як ключі, а їхній пріоритет визначається порядком їх розташування в об'єкті.
+
+## Параметри
+
+- `enumerationContent: QuantityContent<Content>`
+  - **Опис**: Об'єкт, де ключі представляють умови (наприклад `<=`, `<`, `>=`, `=`), а значення — відповідний вміст. Порядок ключів визначає пріоритет їхнього зіставлення.
+  - **Тип**: `QuantityContent<Content>`
+    - `Content` може бути будь-якого типу.
+
+- `quantity: number`
+  - **Опис**: Числове значення, яке використовується для співставлення з умовами в `enumerationContent`.
+  - **Тип**: `number`
+
+## Повертає
+
+- **Тип**: `Content`
+- **Опис**: Вміст, що відповідає першій умові, яка збіглася в `enumerationContent`. Якщо збігів не знайдено, поведінка залежить від реалізації (наприклад, помилка або запасний вміст).
+
+## Приклад використання
+
+### Базове використання
+
+```typescript codeFormat="typescript"
+import { getEnumeration } from "intlayer";
+
+const content = getEnumeration(
+  {
+    "<=-2.3": "У вас менше ніж -2.3",
+    "<1": "У вас менше ніж один",
+    "2": "У вас два",
+    ">=3": "У вас три або більше",
+  },
+  2
+);
+
+console.log(content); // Вивід: "У вас два"
+```
+
+```javascript codeFormat="esm"
+import { getEnumeration } from "intlayer";
+
+const content = getEnumeration(
+  {
+    "<1": "У вас менше ніж один",
+    "2": "У вас два",
+    ">=3": "У вас три або більше",
+  },
+  2
+);
+
+console.log(content); // Вивід: "У вас два"
+```
+
+```javascript codeFormat="commonjs"
+const { getEnumeration } = require("intlayer");
+
+const content = getEnumeration(
+  {
+    "<1": "У вас менше ніж один",
+    "2": "У вас два",
+    ">=3": "У вас три або більше",
+  },
+  2
+);
+
+console.log(content); // Вивід: "You have two"
+```
+
+### Пріоритет умов
+
+```typescript codeFormat="typescript"
+import { getEnumeration } from "intlayer";
+
+const content = getEnumeration(
+  {
+    "<4": "You have less than four",
+    "2": "You have two",
+  },
+  2
+);
+
+console.log(content); // Вивід: "You have less than four"
+```
+
+```javascript codeFormat="esm"
+import { getEnumeration } from "intlayer";
+
+const content = getEnumeration(
+  {
+    "<4": "You have less than four",
+    "2": "You have two",
+  },
+  2
+);
+
+console.log(content); // Вивід: "You have less than four"
+```
+
+```javascript codeFormat="commonjs"
+const { getEnumeration } = require("intlayer");
+
+const content = getEnumeration(
+  {
+    "<4": "You have less than four",
+    "2": "You have two",
+  },
+  2
+);
+
+console.log(content); // Вивід: "You have less than four"
+```
+
+## Граничні випадки
+
+- **Відсутність відповідної умови:**
+  - Якщо жодна умова не відповідає переданій кількості, функція або поверне `undefined`, або явно обробить сценарій за замовчуванням (fallback).
+
+- **Неоднозначні умови:**
+  - Якщо умови перекриваються, пріоритет має перша знайдена умова (в порядку визначення в об'єкті).
+
+- **Невірні ключі:**
+  - Функція припускає, що всі ключі в `enumerationContent` є дійсними та розбираються як умови. Невірні або неправильно відформатовані ключі можуть призвести до непередбаченої поведінки.
+
+- **Забезпечення TypeScript:**
+  - Функція гарантує, що тип `Content` узгоджений для всіх ключів, що дозволяє забезпечити типобезпеку при отриманні вмісту.
+
+## Примітки
+
+- Утиліта `findMatchingCondition` використовується для визначення відповідної умови на основі заданої кількості.

package/docs/uk/packages/intlayer/getHTMLTextDir.md

@@ -0,0 +1,121 @@
+---
+createdAt: 2025-08-23
+updatedAt: 2025-08-23
+title: Документація: функція getHTMLTextDir | intlayer
+description: Дізнайтеся, як використовувати функцію getHTMLTextDir у пакеті intlayer
+keywords:
+  - getHTMLTextDir
+  - переклад
+  - Intlayer
+  - intlayer
+  - інтернаціоналізація
+  - документація
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - packages
+  - intlayer
+  - getHTMLTextDir
+history:
+  - version: 5.5.10
+    date: 2025-06-29
+    changes: Ініціалізація історії
+---
+
+# Документація: функція `getHTMLTextDir` в `intlayer`
+
+## Опис
+
+Функція `getHTMLTextDir` визначає напрямок тексту (`ltr`, `rtl` або `auto`) на основі заданої локалі. Вона призначена, щоб допомогти розробникам встановити атрибут `dir` в HTML для коректного відображення тексту.
+
+## Параметри
+
+- `locale?: Locales`
+  - **Опис**: Рядок локалі (наприклад, `Locales.ENGLISH`, `Locales.ARABIC`), що використовується для визначення напрямку тексту.
+  - **Тип**: `Locales` (необов'язковий)
+
+## Повертає
+
+- **Тип**: `Dir` (`'ltr' | 'rtl' | 'auto'`)
+- **Опис**: Напрямок тексту, що відповідає локалі:
+  - `'ltr'` для мов з напрямком зліва направо.
+  - `'rtl'` для мов з напрямком справа наліво.
+  - `'auto'` якщо локаль не розпізнана.
+
+## Приклад використання
+
+### Визначення напряму тексту
+
+```typescript codeFormat="typescript"
+import { getHTMLTextDir } from "intlayer";
+
+getHTMLTextDir(Locales.ENGLISH); // Output: "ltr"
+getHTMLTextDir(Locales.FRENCH); // Output: "ltr"
+getHTMLTextDir(Locales.ARABIC); // Output: "rtl"
+```
+
+```javascript codeFormat="esm"
+import { getHTMLTextDir } from "intlayer";
+
+getHTMLTextDir(Locales.ENGLISH); // Вивід: "ltr"
+getHTMLTextDir(Locales.FRENCH); // Вивід: "ltr"
+getHTMLTextDir(Locales.ARABIC); // Вивід: "rtl"
+```
+
+```javascript codeFormat="commonjs"
+const { getHTMLTextDir } = require("intlayer");
+
+getHTMLTextDir(Locales.ENGLISH); // Вивід: "ltr"
+getHTMLTextDir(Locales.FRENCH); // Вивід: "ltr"
+getHTMLTextDir(Locales.ARABIC); // Вивід: "rtl"
+```
+
+## Крайні випадки
+
+- **Локаль не вказано:**
+  - Функція повертає `'auto'`, коли `locale` має значення `undefined`.
+
+- **Невідома локаль:**
+  - Для невідомих локалей функція за замовчуванням повертає `'auto'`.
+
+## Використання в компонентах:
+
+Функцію `getHTMLTextDir` можна використовувати для динамічної установки атрибута `dir` в HTML-документі для коректного відображення тексту залежно від локалі.
+
+```tsx codeFormat="typescript"
+import type { FC } from "react";
+import { getHTMLTextDir, type Locales } from "intlayer";
+
+export const HTMLLayout: FC<PropsWithChildren<{ locale: Locales }>> = ({
+  children,
+  locale,
+}) => (
+  <html dir={getHTMLTextDir(locale)} locale={locale}>
+    <body>{children}</body>
+  </html>
+);
+```
+
+```jsx codeFormat="esm"
+import { getHTMLTextDir } from "intlayer";
+
+const HTMLLayout = ({ children, locale }) => (
+  <html dir={getHTMLTextDir(locale)} locale={locale}>
+    <body>{children}</body>
+  </html>
+);
+```
+
+```jsx codeFormat="commonjs"
+const { getHTMLTextDir } = require("intlayer");
+
+const HTMLLayout = ({ children, locale }) => (
+  <html dir={getHTMLTextDir(locale)} locale={locale}>
+    <body>{children}</body>
+  </html>
+);
+```
+
+У наведеному вище прикладі атрибут `dir` динамічно встановлюється на основі локалі.

package/docs/uk/packages/intlayer/getLocaleLang.md

@@ -0,0 +1,81 @@
+---
+createdAt: 2025-08-23
+updatedAt: 2025-08-23
+title: Документація функції getLocaleLang | intlayer
+description: Дізнайтеся, як використовувати функцію getLocaleLang у пакеті intlayer
+keywords:
+  - getLocaleLang
+  - переклад
+  - Intlayer
+  - intlayer
+  - інтернаціоналізація
+  - документація
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - packages
+  - intlayer
+  - getLocaleLang
+history:
+  - version: 5.5.10
+    date: 2025-06-29
+    changes: Ініціалізація історії
+---
+
+# Документація: функція `getLocaleLang` у `intlayer`
+
+## Опис
+
+Функція `getLocaleLang` витягує код мови з рядка локалі. Вона підтримує локалі як з кодами країн, так і без них. Якщо локаль не вказана, за замовчуванням повертається пустий рядок.
+
+## Параметри
+
+- `locale?: Locales`
+  - **Опис**: Рядок локалі (наприклад, `Locales.ENGLISH_UNITED_STATES`, `Locales.FRENCH_CANADA`), з якого витягується код мови.
+  - **Тип**: `Locales` (необов'язково)
+
+## Повертає
+
+- **Тип**: `string`
+- **Опис**: Код мови, витягнутий з локалі. Якщо локаль не вказана, повертається порожній рядок (`''`).
+
+## Приклад використання
+
+### Отримання кодів мов:
+
+```typescript codeFormat="typescript"
+import { getLocaleLang, Locales } from "intlayer";
+
+getLocaleLang(Locales.ENGLISH_UNITED_STATES); // Output: "en"
+getLocaleLang(Locales.ENGLISH); // Output: "en"
+getLocaleLang(Locales.FRENCH_CANADA); // Output: "fr"
+getLocaleLang(Locales.FRENCH); // Output: "fr"
+```
+
+```javascript codeFormat="esm"
+import { getLocaleLang } from "intlayer";
+
+getLocaleLang(Locales.ENGLISH_UNITED_STATES); // Вивід: "en"
+getLocaleLang(Locales.ENGLISH); // Вивід: "en"
+getLocaleLang(Locales.FRENCH_CANADA); // Вивід: "fr"
+getLocaleLang(Locales.FRENCH); // Вивід: "fr"
+```
+
+```javascript codeFormat="commonjs"
+const { getLocaleLang } = require("intlayer");
+
+getLocaleLang(Locales.ENGLISH_UNITED_STATES); // Вивід: "en"
+getLocaleLang(Locales.ENGLISH); // Вивід: "en"
+getLocaleLang(Locales.FRENCH_CANADA); // Вивід: "fr"
+getLocaleLang(Locales.FRENCH); // Вивід: "fr"
+```
+
+## Крайові випадки
+
+- **Locale не вказано:**
+  - Функція повертає порожній рядок, коли `locale` є `undefined`.
+
+- **Некоректні рядки locale:**
+  - Якщо `locale` не відповідає формату `language-country` (наприклад, `Locales.ENGLISH-US`), функція безпечно повертає частину перед `'-'` або весь рядок, якщо `'-'` відсутній.

package/docs/uk/packages/intlayer/getLocaleName.md

@@ -0,0 +1,135 @@
+---
+createdAt: 2025-08-23
+updatedAt: 2025-08-23
+title: Документація функції getLocaleName | intlayer
+description: Дивіться, як використовувати функцію getLocaleName у пакеті intlayer
+keywords:
+  - getLocaleName
+  - локалізація
+  - Intlayer
+  - intlayer
+  - Інтернаціоналізація
+  - Документація
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - packages
+  - intlayer
+  - getLocaleName
+history:
+  - version: 7.5.0
+    date: 2025-12-18
+    changes: Додано поліфіли для React Native та старіших середовищ
+  - version: 5.5.10
+    date: 2025-06-29
+    changes: Ініціалізація історії
+---
+
+# Документація: функція `getLocaleName` у `intlayer`
+
+## Опис
+
+Функція `getLocaleName` повертає локалізовану назву заданої локалі (`targetLocale`) мовою відображення (`displayLocale`). Якщо `targetLocale` не вказано, вона повертає назву `displayLocale` його власною мовою.
+
+## Параметри
+
+- `displayLocale: Locales`
+  - **Опис**: Локаль, якою буде відображено назву цільової локалі.
+  - **Тип**: Enum або рядок, що представляє допустимі локалі.
+
+- `targetLocale?: Locales`
+  - **Опис**: Локаль, назву якої потрібно локалізувати.
+  - **Тип**: Необов'язковий. Enum або рядок, що представляє допустимі локалі.
+
+## Повертає
+
+- **Тип**: `string`
+- **Опис**: Локалізована назва `targetLocale` мовою `displayLocale`, або власна назва `displayLocale`, якщо `targetLocale` не вказано. Якщо переклад не знайдено, функція повертає "Unknown locale".
+
+## Приклад використання
+
+```typescript codeFormat="typescript"
+import { Locales, getLocaleName } from "intlayer";
+
+getLocaleName(Locales.ENGLISH); // Вивід: "English"
+getLocaleName(Locales.ENGLISH, Locales.FRENCH); // Вивід: "Anglais"
+getLocaleName(Locales.ENGLISH, Locales.ESPANOL); // Вивід: "Inglés"
+getLocaleName(Locales.ENGLISH, Locales.ENGLISH); // Вивід: "English"
+
+getLocaleName(Locales.FRENCH); // Вивід: "Français"
+getLocaleName(Locales.FRENCH, Locales.FRENCH); // Вивід: "Français"
+getLocaleName(Locales.FRENCH, Locales.ESPANOL); // Вивід: "Francés"
+getLocaleName(Locales.FRENCH, Locales.ENGLISH); // Вивід: "French"
+
+getLocaleName(Locales.CHINESE); // Вивід: "中文"
+getLocaleName(Locales.CHINESE, Locales.FRENCH); // Вивід: "Chinois"
+getLocaleName(Locales.CHINESE, Locales.ESPANOL); // Вивід: "Chino"
+getLocaleName(Locales.CHINESE, Locales.ENGLISH); // Вивід: "Chinese"
+
+getLocaleName("unknown-locale"); // Вивід: "Unknown locale"
+```
+
+```javascript codeFormat="esm"
+import { Locales, getLocaleName } from "intlayer";
+
+getLocaleName(Locales.ENGLISH); // Вивід: "English"
+getLocaleName(Locales.ENGLISH, Locales.FRENCH); // Вивід: "Anglais"
+getLocaleName(Locales.ENGLISH, Locales.ESPANOL); // Вивід: "Inglés"
+getLocaleName(Locales.ENGLISH, Locales.ENGLISH); // Вивід: "English"
+
+getLocaleName(Locales.FRENCH); // Вивід: "Français"
+getLocaleName(Locales.FRENCH, Locales.FRENCH); // Вивід: "Français"
+getLocaleName(Locales.FRENCH, Locales.ESPANOL); // Вивід: "Francés"
+getLocaleName(Locales.FRENCH, Locales.ENGLISH); // Вивід: "French"
+
+getLocaleName(Locales.CHINESE); // Вивід: "中文"
+getLocaleName(Locales.CHINESE, Locales.FRENCH); // Вивід: "Chinois"
+getLocaleName(Locales.CHINESE, Locales.ESPANOL); // Вивід: "Chino"
+getLocaleName(Locales.CHINESE, Locales.ENGLISH); // Вивід: "Chinese"
+
+getLocaleName("unknown-locale"); // Вивід: "Unknown locale"
+```
+
+```javascript codeFormat="commonjs"
+const { Locales, getLocaleName } = require("intlayer");
+
+getLocaleName(Locales.ENGLISH); // Вивід: "English"
+getLocaleName(Locales.ENGLISH, Locales.FRENCH); // Вивід: "Anglais"
+getLocaleName(Locales.ENGLISH, Locales.ESPANOL); // Вивід: "Inglés"
+getLocaleName(Locales.ENGLISH, Locales.ENGLISH); // Вивід: "English"
+
+getLocaleName(Locales.FRENCH); // Вивід: "Français"
+getLocaleName(Locales.FRENCH, Locales.FRENCH); // Вивід: "Français"
+getLocaleName(Locales.FRENCH, Locales.ESPANOL); // Вивід: "Francés"
+getLocaleName(Locales.FRENCH, Locales.ENGLISH); // Вивід: "French"
+
+getLocaleName(Locales.CHINESE); // Вивід: "中文"
+getLocaleName(Locales.CHINESE, Locales.FRENCH); // Вивід: "Chinois"
+getLocaleName(Locales.CHINESE, Locales.ESPANOL); // Вивід: "Chino"
+getLocaleName(Locales.CHINESE, Locales.ENGLISH); // Вивід: "Chinese"
+
+getLocaleName("unknown-locale"); // Вивід: "Unknown locale"
+```
+
+## Крайні випадки
+
+- **Не вказано `targetLocale`:**
+  - Функція за замовчуванням повертає власну назву `displayLocale`.
+- **Відсутні переклади:**
+  - Якщо `localeNameTranslations` не містить запису для `targetLocale` або конкретного `displayLocale`, функція використовує `ownLocalesName` або повертає `"Unknown locale"`.
+
+## Поліфіли для React Native та старіших середовищ
+
+Функція `getLocaleName` покладається на API `Intl.DisplayNames`, який недоступний у React Native або старіших JavaScript-середовищах. Якщо ви використовуєте `getLocaleName` у таких середовищах, потрібно додати поліфіли.
+
+Імпортуйте поліфіли на початку вашого застосунку, бажано в точці входу (наприклад, `index.js`, `App.tsx`, або `main.tsx`):
+
+```typescript
+import "intl";
+import "@formatjs/intl-locale/polyfill";
+import "@formatjs/intl-displaynames/polyfill";
+```
+
+Для детальнішої інформації див. [документацію поліфілів FormatJS](https://formatjs.io/docs/polyfills/intl-displaynames/).