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

Зміст

Що таке Intlayer?

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

Перегляньте конкретне порівняння з next-intl у нашому дописі в блозі next-i18next vs. next-intl vs. Intlayer.

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

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

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

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

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

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

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

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

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

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

Встановіть необхідні пакети, використовуючи ваш улюблений пакетний менеджер:

npm install intlayer @intlayer/sync-json-plugin --save-devnpx 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 }) => `./public/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 залишається незмінним.
• Порційний (chunked) переклад для великих JSON-файлів: Коли ваші файли перекладу дуже великі, Intlayer автоматично розбиває обробку на керовані порції, перекладаючи їх незалежно, щоб уникнути лімітів API та проблем із пам'яттю.
• Паралелізація namespace-ів: Якщо у вас сотні namespace-ів (або файлів), 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 }) => `./public/locales/${locale}/${key}.json`,    }),  ],};export default config;

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

npx intlayer fill

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

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

Конфігурація Git

Виключити згенеровані файли з контролю версій:

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

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

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

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

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