@intlayer/docs 9.4.1 → 9.4.3

package/blog/uk/i18n_testing_strategies.md

@@ -0,0 +1,179 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: "Як тестувати переклади без створення крихких тестів"
+description: Що варто тестувати в додатку з i18n, а що ні. Тести рендерингу на основі провайдера, псевдолокалізація, покриття RTL та множини, а також пастка снепшотів.
+keywords:
+  - тестування перекладів
+  - i18n тестування
+  - testing library i18n
+  - псевдолокалізація
+  - тест провайдера локалі
+  - snapshot test i18n
+slugs:
+  - blog
+  - i18n-testing-strategies
+author: aymericzip
+---
+
+# Як тестувати переклади без створення крихких тестів
+
+Більшість наборів тестів i18n зазнають невдачі з однієї з двох причин. Або вони перевіряють буквальний текст, через що будь-яка зміна формулювання ламає п'ятдесят тестів і команда просто видаляє їх. Або вони рендерять усе лише в локалі за замовчуванням, нічого не доводячи щодо решти сімнадцяти мов. Обидва шляхи ведуть до одного результату: набору тестів, якому ніхто не довіряє.
+
+## Зміст
+
+<TOC/>
+
+## Патерни не залежать від бібліотеки
+
+Кожен наведений нижче патерн працює на будь-якому стеку i18n. Замініть провайдер на `I18nextProvider`, `NextIntlClientProvider` або `IntlProvider`, і тести залишаться ідентичними, оскільки вони перевіряють відрендерений результат, а не API конкретної бібліотеки.
+
+Інструменти перевірки покриття також легко переносяться: із [плагіном Sync JSON](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/plugins/sync-json.md), спрямованим на ваші каталоги, або [адаптером сумісності](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/compat/index.md), що створює псевдоніми для ваших поточних імпортів, перевірка покриття запускається безпосередньо над наявним JSON.
+
+## Визначте, що ви насправді тестуєте
+
+Якість перекладу неможливо перевірити тестом коду. Жодне твердження не підкаже, чи звучить німецька мова природно, а спроба це зробити призведе до наповнення коду захардкодzoneними рядками.
+
+Механічні речі, які дійсно варто тестувати:
+
+| Варто тестувати                              | Не варто тестувати              |
+| :------------------------------------------- | :------------------------------ |
+| Кожна обов'язкова локаль має значення        | Чи вдалим є формулювання        |
+| Правильна локаль передається в компонент     | Точний текст кожної мітки       |
+| Форми множини працюють для кожної категорії  | Чи сумлінно працював перекладач |
+| RTL-локалі задають напрямок та дзеркальність | Кожен рядок у кожній мові       |
+| Форматовані дати та числа враховують локаль  | Внутрішню коректність `Intl`    |
+
+Перевірка покриття має виконуватися в одному тесті на основі даних, а не в тестах окремих компонентів. Це докладно описано у статті [як виявляти відсутні переклади](https://github.com/aymericzip/intlayer/blob/main/docs/blog/uk/detecting_missing_translations.md); цей матеріал присвячений решті аспектів.
+
+## Рендеринг всередині провайдера та запит за роллю
+
+Основний патерн полягає в монтуванні компонента всередині провайдера локалі та пошуку елементів за роллю (role) або тестовим id замість тексту.
+
+```tsx fileName="CartSummary.test.tsx"
+import { render, screen } from "@testing-library/react";
+import { IntlayerProvider } from "react-intlayer/client";
+import { CartSummary } from "./CartSummary";
+
+test("рендерить заголовок підсумку французькою", () => {
+  render(
+    <IntlayerProvider locale="fr-FR">
+      <CartSummary />
+    </IntlayerProvider>
+  );
+
+  expect(screen.getByRole("heading")).toBeInTheDocument();
+});
+```
+
+Запит `getByRole("heading")` стійкий до змін тексту. `getByText("Récapitulatif")` зламається при першому ж редагуванні. Використовуйте точний текст лише тоді, коли сам рядок є об'єктом перевірки, що буває рідко.
+
+Для атрибутів на зразок `aria-label` вам потрібен необроблений рядок, а не вузол для рендерингу. У React записи `useIntlayer` мають поле `.value` для цього.
+
+## Параметризуйте тести для різних локалей
+
+Один універсальний тест, запущений для кожної локалі, набагато цінніший за окремі тести для кожної мови.
+
+```tsx fileName="direction.test.tsx"
+import { getHTMLTextDir } from "intlayer";
+import { render } from "@testing-library/react";
+import { IntlayerProvider } from "react-intlayer/client";
+
+describe.each(["en", "fr", "ja", "ar"])("локаль %s", (locale) => {
+  it("рендериться без відкату до ключа", () => {
+    const { container } = render(
+      <IntlayerProvider locale={locale}>
+        <CartSummary />
+      </IntlayerProvider>
+    );
+
+    // Якщо відрендерився ключ, значить пошук не вдався.
+    expect(container.textContent).not.toMatch(/^[a-z]+(\.[a-z]+)+$/);
+  });
+
+  it("встановлює правильний напрямок тексту", () => {
+    expect(getHTMLTextDir(locale)).toBe(locale === "ar" ? "rtl" : "ltr");
+  });
+});
+```
+
+Перша перевірка є універсальною перевагою: якщо пошук значення не вдався і бібліотека вивела ключ, DOM міститиме шаблон на кшталт `cart.summary.title`. Це виявляє цілий клас помилок без прив'язки до конкретних фраз.
+
+## Псевдолокалізація виявляє те, що пропускають каталоги
+
+Додайте штучну тестову локаль, яка трансформує кожен рядок, наприклад змінюючи `Checkout` на `[!!! Çĥéçķöũţ !!!]`. Потім відрендеріть сторінку цією мовою.
+
+Усе, що залишається звичайною англійською, захардкоджене безпосередньо в коді. Жоден аудит каталогів цього не помітить, адже для інструментів такого рядка взагалі не існує. Дужки виконують друге завдання: вони видовжують текст приблизно на 30 відсотків, виявляючи переповнення інтерфейсу ще до тестування німецької мови.
+
+Це корисно запускати як візуальний або end-to-end прогін, а не як юніт-тест, оскільки такі дефекти сприймаються візуально.
+
+## Для форм множини потрібен тест на категорію, а не на мову
+
+Помилки множини часто непомітні, тому що в англійській мові є лише дві форми і більшість розробників перевіряють тільки їх. У польській мові чотири категорії, в арабській шість.
+
+```ts fileName="plural.test.ts"
+// Арабська перевіряє zero, one, two, few, many, other.
+describe.each([0, 1, 2, 3, 11, 100])("кількість %i", (count) => {
+  it("генерує непорожній рядок арабською", () => {
+    expect(formatItems(count, "ar")).not.toBe("");
+  });
+});
+```
+
+Вибирайте значення, які потрапляють у кожну категорію CLDR для найскладнішої мови, замість того, щоб скрізь перевіряти лише 1 та 2. `Intl.PluralRules` підказує, до якої категорії належить число, що дозволяє формувати вибірку без ворожіння. Більше про категорії у [статті про формат повідомлень ICU](https://github.com/aymericzip/intlayer/blob/main/docs/blog/uk/icu_message_format.md).
+
+## Пастка снепшотів (Snapshots)
+
+Снепшоти та i18n погано сумісні. Снепшот локалізованого компонента фіксує кожен рядок у ньому: коли перекладач виправляє одруківку в португальській, зелений тест стає червоним у файлі, який рев'юер не може оцінити. Після кількох таких випадків розробники запускають `-u` не читаючи diff, і снепшоти втрачають будь-який сенс.
+
+Якщо ви бажаєте використовувати снепшоти, робіть їх лише для однієї локалі та сприймайте як структурну, а не смислову перевірку. Усе специфічне для окремих мов має перевірятися явними твердженнями.
+
+## Тестуйте узгодження локалі, а не лише рендеринг
+
+Найпоширеніша помилка i18n на продакшені, не відсутній переклад. Це вибір невірної локалі: URL містить `/fr/`, клієнт читає `navigator.language`, і вони не збігаються.
+
+Тестуйте порядок визначення локалі безпосередньо як чисту функцію, окремо від компонентів:
+
+```ts fileName="locale-resolution.test.ts"
+it("надає перевагу URL над збереженим налаштуванням", () => {
+  expect(resolveLocale({ url: "/fr/about", stored: "de", header: "ja" })).toBe(
+    "fr"
+  );
+});
+
+it("відкочується до заголовка, коли в URL немає префікса", () => {
+  expect(resolveLocale({ url: "/about", stored: null, header: "ja" })).toBe(
+    "ja"
+  );
+});
+```
+
+Це найцінніший тест i18n, якого бракує більшості проєктів, і він не потребує DOM.
+
+## Що і де запускати
+
+- **Unit**: узгодження локалей, форматери, категорії множини. Швидко, без DOM.
+- **Component**: один рендеринг із провайдером на локаль, перевірка ролей і відсутності сирих ключів.
+- **Покриття**: тест на основі даних, що гарантує відсутність пропусків у необхідних локалях.
+- **Visual або E2E**: перевірка псевдолокалізації та сторінки з RTL, оскільки ці проблеми є візуальними.
+
+Залишайте перші три в пайплайні CI на кожен коміт. Останнє дешевше запускати під час нічних збірок.
+
+## Поширені помилки
+
+- **Перевірка точного тексту всюди.** Гарантує видалення тестового набору через кілька місяців.
+- **Снепшоти локалізованих компонентів.** Перекладачі ламають збірку, а рев'юери схвалюють зміни наосліп.
+- **Тестування лише локалі за замовчуванням.** Єдина локаль, яка точно не може бути відсутня.
+- **Тестування лише 1 та 2 для множини.** Пропускає категорії, яких немає в англійській мові.
+- **Повне мокування бібліотеки i18n.** Тоді ви лише перевіряєте, чи повертає мок рядки.
+- **Ігнорування тестів узгодження локалей.** Найчастіша проблема на практиці, яку найпростіше протестувати.
+
+## Корисні матеріали
+
+- [Тестування контенту: аудит CLI, програмний API та перевірки UI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/testing.md)
+- [Плагін ESLint: пошук захардкодzoneних рядків і невикористаного контенту](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/eslint.md)
+- [Форматери та утиліти локалей, включно з `getHTMLTextDir`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/formatters.md)
+- [Звіти про продуктивність між різними фреймворками](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/benchmark/index.md)
+- [Адаптер сумісності react-i18next](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/compat/react-i18next.md)
+- [Як виявляти відсутні переклади](https://github.com/aymericzip/intlayer/blob/main/docs/blog/uk/detecting_missing_translations.md)
+- [Формат повідомлень ICU: множина, вибір та шаблони](https://github.com/aymericzip/intlayer/blob/main/docs/blog/uk/icu_message_format.md)

package/blog/uk/intlayer_with_i18next.md

@@ -89,15 +89,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > прапорець `--interactive` не є обов'язковим. Використовуйте `intlayer-cli init`, якщо ви є ШІ-агентом.
@@ -214,8 +214,6 @@ npx intlayer fill
 > Перегляньте всіх доступних AI-провайдерів у [документації з конфігурації Intlayer AI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/configuration.md#ai-configuration).
 > Перегляньте всі доступні команди в [документації Intlayer CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/cli/index.md).
 
----
-
 </Step>
 
 </Steps>

package/blog/uk/intlayer_with_next-i18next.md

@@ -80,15 +80,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > прапорець `--interactive` не є обов'язковим. Використовуйте `intlayer-cli init`, якщо ви є ШІ-агентом.
@@ -205,8 +205,6 @@ npx intlayer fill
 > Дивіться всіх доступних AI-провайдерів у [документації Intlayer щодо конфігурації AI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/configuration.md#ai-configuration).
 > Дивіться всі доступні команди у [документації Intlayer CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/cli/index.md).
 
----
-
 </Step>
 
 </Steps>

package/blog/uk/intlayer_with_next-intl.md

@@ -79,15 +79,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > прапорець `--interactive` не є обов'язковим. Використовуйте `intlayer-cli init`, якщо ви є ШІ-агентом.
@@ -206,8 +206,6 @@ npx intlayer fill
 > Див. усіх доступних AI-провайдерів у [документації конфігурації AI Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/configuration.md#ai-configuration).
 > Див. усі доступні команди в [документації Intlayer CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/cli/index.md).
 
----
-
 </Step>
 
 </Steps>

package/blog/uk/intlayer_with_react-i18next.md

@@ -80,15 +80,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > прапорець `--interactive` не є обов'язковим. Використовуйте `intlayer-cli init`, якщо ви є ШІ-агентом.

package/blog/uk/intlayer_with_react-intl.md

@@ -78,15 +78,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > прапорець `--interactive` не є обов'язковим. Використовуйте `intlayer-cli init`, якщо ви є ШІ-агентом.
@@ -205,8 +205,6 @@ npx intlayer fill
 > Перегляньте всі доступні AI-провайдери в [документації конфігурації Intlayer AI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/configuration.md#ai-configuration).
 > Перегляньте всі доступні команди в [документації Intlayer CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/cli/index.md).
 
----
-
 </Step>
 
 </Steps>

package/blog/uk/intlayer_with_vue-i18n.md

@@ -80,15 +80,15 @@ npx intlayer init --interactive
 ```
 
 ```bash packageManager="pnpm"
-pnpm dlx intlayer@canary init --interactive
+pnpm dlx intlayer init --interactive
 ```
 
 ```bash packageManager="yarn"
-yarn dlx intlayer@canary init --interactive
+yarn dlx intlayer init --interactive
 ```
 
 ```bash packageManager="bun"
-bunx intlayer@canary init --interactive
+bunx intlayer init --interactive
 ```
 
 > прапорець `--interactive` не є обов'язковим. Використовуйте `intlayer-cli init`, якщо ви є ШІ-агентом.
@@ -209,8 +209,6 @@ npx intlayer fill
 > Див. усіх доступних AI-провайдерів у [документації Intlayer щодо конфігурації AI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/configuration.md#ai-configuration).
 > Див. усі доступні команди у [документації Intlayer CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/cli/index.md).
 
----
-
 </Step>
 
 </Steps>