Як автоматизувати ваші JSON-переклади i18next за допомогою Intlayer

Зміст

Що таке Intlayer?

Intlayer, інноваційна open-source бібліотека для інтернаціоналізації, створена для вирішення недоліків традиційних i18n-рішень. Вона пропонує сучасний підхід до керування контентом у JavaScript-додатках.

Дивіться конкретне порівняння з i18next у нашому дописі в блозі «next-i18next vs. next-intl vs. Intlayer»: /uk/blog/next-i18next-vs-next-intl-vs-intlayer

Чому поєднувати Intlayer з i18next?

Хоча Intlayer пропонує відмінне автономне i18n-рішення (див. наш посібник з інтеграції Next.js: /uk/doc/environment/nextjs), ви можете захотіти поєднати його з i18next з кількох причин.

Intlayer пропонує широкий набір розширених функцій, що виходять за межі традиційних i18n-інструментів. Він допомагає вам:

• Автоматично виявляти та заповнювати відсутні переклади, щоб спростити локалізацію.
• Тестувати та перевіряти ваші переклади безпосередньо у ваших робочих процесах розробки або CI/CD.
• Керувати контентом на рівні компонентів, що дозволяє отримати чисту, масштабовану та легку в підтримці структуру в усьому вашому додатку.
• Виносити контент за межі коду, роблячи його простим для редагування всією вашою командою (розробники, перекладачі та контент-менеджери).

Однак, i18next залишається відмінним і широко застосовуваним рішенням для i18n завдяки своїй дозрілій екосистемі, широкій підтримці спільноти та широкій сумісності з плагінами.

Поєднавши Intlayer з i18next, ви отримуєте найкраще з обох світів, стабільність і зрілість екосистеми i18next разом із сучасним керуванням контентом, автоматизацією та покращенням developer experience від Intlayer.

Цей посібник пояснює, як використовувати Intlayer як адаптер для i18next, що дозволяє вам:

• Поступово мігрувати з i18next на Intlayer.
• Зберігайте існуючі плагіни та робочі процеси i18next.
• Автоматизуйте ваші JSON-переклади у CLI або в CI/CD конвеєрах.
• Тестуйте, синхронізуйте та керуйте перекладами ефективніше.

Зміст

Покроковий посібник із налаштування Intlayer з i18next

Крок 1: Встановлення залежностей

Встановіть необхідні пакети:

npm install intlayer @intlayer/sync-json-plugin --save-dev
npx intlayer init

pnpm add intlayer @intlayer/sync-json-plugin --save-dev
pnpm intlayer init

yarn add intlayer @intlayer/sync-json-plugin --dev
yarn intlayer init

bun add intlayer @intlayer/sync-json-plugin --dev
bun x intlayer init

Опис пакетів:

• intlayer: Базова бібліотека для управління інтернаціоналізацією, декларації контенту та побудови
• @intlayer/sync-json-plugin: Плагін для експорту декларацій контенту Intlayer у формат JSON, сумісний з i18next

Крок 2: Реалізуйте плагін Intlayer для обгортання JSON

Створіть файл конфігурації Intlayer, щоб визначити підтримувані локалі:

Якщо ви також хочете експортувати JSON-словники для i18next, додайте плагін syncJSON:

import { Locales, type IntlayerConfig } from "intlayer";
import { syncJSON } from "@intlayer/sync-json-plugin";

const config: IntlayerConfig = {
  internationalization: {
    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
    defaultLocale: Locales.ENGLISH,
  },
  plugins: [
    syncJSON({
      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
    }),
  ],
};

export default config;

Плагін syncJSON автоматично обгортає JSON. Він читає та записує JSON-файли, не змінюючи архітектуру їхнього вмісту.

Якщо ви хочете, щоб ці JSON-файли співіснували з файлами декларацій контенту Intlayer (.content файли), Intlayer оброблятиме їх таким чином:

1. завантажить як JSON, так і файли декларацій контенту і перетворить їх на словник Intlayer.
2. якщо виникають конфлікти між JSON та файлами декларацій контенту, Intlayer виконає злиття всіх словників. Результат залежатиме від пріоритету плагінів і пріоритету файлів декларацій контенту (усі параметри можна налаштувати).

Якщо зміни вносяться за допомогою CLI для перекладу JSON або через CMS, Intlayer оновить JSON-файл з новими перекладами.

Щоб дізнатися більше про плагін syncJSON, див. документацію плагіна syncJSON.

Крок 4: Налаштування AI-провайдера

Intlayer надає набір просунутих автоматизаційних та дружніх до розробника функцій для вашого робочого процесу i18next.

• Автоматичне виявлення та заповнення відсутніх перекладів: Intlayer сканує ваші JSON-словники, знаходить неперекладені або відсутні ключі і перекладає лише їх, тож 99% вашого JSON залишається незмінним.
• Поблочний переклад великих JSON-файлів: Коли ваші файли перекладу дуже великі, Intlayer автоматично розбиває обробку на керовані блоки, перекладаючи їх незалежно, щоб уникнути обмежень API та проблем з пам’яттю.
• Паралелізація просторів імен (namespaces): Якщо у вас сотні просторів імен (або файлів), Intlayer паралелізує задачі перекладу, ефективно прискорюючи ваші CI/CD або масові операції перекладу.
• Гнучка підтримка AI-провайдерів: Обирайте улюбленого AI-провайдера (наприклад, OpenAI, Claude, Gemini), просто налаштувавши облікові дані. Використовуйте власний API-ключ і за потреби перемикайте провайдерів.
• Стійка обробка відповідей AI: Intlayer може обробляти крайові випадки, коли ваш AI-провайдер повертає текст або як рядок, або як об’єкт, навіть автоматично повторюючи спроби, якщо формат є непослідовним.
• Готовий для CLI та CI/CD: запускайте перевірки Intlayer і автозаповнення безпосередньо у ваших тестах або пайплайнах, роблячи процес локалізації надійним та автоматизованим.
• Інтегрується поверх наявної конфігурації: вам не потрібно змінювати i18next або основу Next.js. Intlayer працює як додатковий плагін до вашої поточної установки, надаючи всі ці переваги з мінімальною міграцією.

Ось приклад того, як налаштувати AI-провайдера:

import { Locales, type IntlayerConfig } from "intlayer";
import { loadJSON, syncJSON } from "@intlayer/sync-json-plugin";

const config: IntlayerConfig = {
  internationalization: {
    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
    defaultLocale: Locales.ENGLISH,
  },
  ai: {
    provider: "openai",
    model: "gpt-5-mini",
    apiKey: process.env.OPENAI_API_KEY,
  },
  plugins: [
    syncJSON({
      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
    }),
  ],
};

export default config;

Потім ви можете виконати наступну команду, щоб заповнити переклади:

npx intlayer fill

Це заповнить ваші переклади за допомогою AI-провайдера, якого ви налаштували.

Перегляньте всіх доступних AI-провайдерів у документації з конфігурації Intlayer AI. Перегляньте всі доступні команди в документації Intlayer CLI.

Налаштування Git

Рекомендується ігнорувати автоматично згенеровані файли Intlayer:

# Ігнорувати файли, згенеровані Intlayer
.intlayer

Ці файли можуть бути повторно згенеровані під час збірки і їх не потрібно додавати до системи контролю версій.

Розширення для VS Code

Для покращення досвіду розробника встановіть офіційне Intlayer VS Code Extension:

Встановити з VS Code Marketplace