Задайте питання та отримайте підсумок документа, вказавши цю сторінку та обраного вами постачальника штучного інтелекту
Історія версій
- "Додано підтримку форматів файлів YAML та Markdown"v8.10.019.05.2026
- "Add `plural` content node type"v8.9.012.05.2026
- "Додано тип вузла контенту `html`"v8.0.028.01.2026
- "Rename `live` import mode to `fetch` to better describe the underlying mechanism."v8.0.024.01.2026
- "Додано опції словника `location` та `schema`"v8.0.018.01.2026
- "Додано підтримку форматів файлів JSON5 та JSONC"v7.5.1310.01.2026
- "Додано підтримку форматів ICU та i18next"v7.5.013.12.2025
- "Перейменовано `autoFill` на `fill`"v7.0.023.10.2025
- "Додано документацію для полів"v6.0.020.09.2025
- "Ініціалізовано історію"v5.5.1029.06.2025
Вміст цієї сторінки перекладено за допомогою штучного інтелекту.
Переглянути останню версію оригінального вмісту англійськоюЯкщо у вас є ідея щодо покращення цієї документації, будь ласка, долучіться, надіславши pull request на GitHub.
Посилання на документацію на GitHubСкопіювати документацію у форматі Markdown в буфер обміну
Файл контенту
Що таке файл контенту?
Файл контенту в Intlayer, це файл, який містить визначення словників. Такі файли оголошують текстовий контент вашого застосунку, переклади та ресурси. Файли контенту обробляються Intlayer для генерації словників.
Словники будуть кінцевим результатом, який ваш застосунок імпортуватиме з використанням хуку useIntlayer.
Ключові поняття
Словник
Словник, це структурована колекція контенту, організована за ключами. Кожен словник містить:
- Ключ: Унікальний ідентифікатор словника
- Контент: Фактичні значення контенту (текст, числа, об'єкти тощо)
- Метадані: Додаткова інформація, наприклад title, description, tags тощо
Файл контенту
Приклад файлу контенту:
Скопіюйте код у буфер обміну
import { type ReactNode } from "react";
import {
t,
enu,
plural,
cond,
nest,
md,
html,
insert,
file,
type Dictionary,
} from "intlayer";
interface Content {
imbricatedContent: {
imbricatedContent2: {
stringContent: string;
numberContent: number;
booleanContent: boolean;
javaScriptContent: string;
};
};
multilingualContent: string;
quantityContent: string;
pluralContent: string;
conditionalContent: string;
markdownContent: never;
htmlContent: never;
externalContent: string;
insertionContent: string;
nestedContent: string;
fileContent: string;
jsxContent: ReactNode;
}
export default {
key: "page",
content: {
imbricatedContent: {
imbricatedContent2: {
stringContent: "Привіт, світ",
numberContent: 123,
booleanContent: true,
javaScriptContent: `${process.env.NODE_ENV}`,
},
},
multilingualContent: t({
uk: "Український контент",
en: "English content",
"en-GB": "English content (UK)",
fr: "French content",
es: "Spanish content",
}),
quantityContent: enu({
"<-1": "Менше ніж мінус одна машина",
"-1": "Мінус одна машина",
"0": "Немає машин",
"1": "Одна машина",
">5": "Декілька машин",
">19": "Багато машин",
}),
pluralContent: plural({
one: "One car",
other: "{{count}} cars",
}),
conditionalContent: cond({
true: "Валідація увімкнена",
false: "Валідація вимкнена",
}),
insertionContent: insert("Привіт {{name}}!"),
nestedContent: nest(
"navbar", // Ключ словника для вкладення
"login.button" // [Необов'язково] Шлях до вмісту для вкладення
),
fileContent: file("./path/to/file.txt"),
externalContent: fetch("https://example.com").then((res) => res.json()),
markdownContent: md("# Приклад Markdown"),
htmlContent: html("<p>Hello <strong>World</strong></p>"),
/*
* Доступно лише при використанні `react-intlayer` або `next-intlayer`
*/
jsxContent: <h1>Мій заголовок</h1>,
},
} satisfies Dictionary<Content>; // [необов'язково] Dictionary, generic тип, який дозволяє уточнити форматування вашого словникаВузли контенту
Вузли контенту, це будівельні блоки вмісту словника. Вони можуть бути:
- Примітивні значення: strings, numbers, booleans, null, undefined
- Типізовані вузли: спеціальні типи контенту, такі як translations, conditions, markdown тощо
- Функції: динамічний контент, який може бути виконаний під час виконання див. Отримання функцій
- Plural Content: See Plural Content See Plural Content
- Вкладений контент: посилання на інші словники
Типи контенту
Intlayer підтримує різні типи контенту через типізовані вузли:
- Контент перекладів: багатомовний текст зі значеннями для конкретних локалей див. Контент перекладів
- Умовний контент: Контент, що залежить від булевих виразів див. Умовний контент
- Контент перелічення: Контент, який змінюється залежно від переліку значень див. Контент перелічення
- Вставний контент: Контент, який можна вставити в інший контент див. Вставний контент
- Markdown-контент: Багатий текстовий контент у форматі Markdown див. Markdown-контент
- HTML-вміст: Багатий HTML-вміст з опційними власними компонентами див. HTML-вміст
- Вкладений вміст: Посилання на інші словники див. Вкладений вміст
- Гендерний вміст: Вміст, що змінюється залежно від статі див. Гендерний вміст
- Вміст файлу: Посилання на зовнішні файли див. Вміст файлу
Структура словника
Словник в Intlayer визначається типом Dictionary і містить кілька властивостей, які керують його поведінкою:
Обов'язкові властивості
key (string)
Ідентифікатор словника. Якщо кілька словників мають однаковий key, Intlayer автоматично їх об'єднає.
Використовуйте формат іменування kebab-case (наприклад, "about-page-meta").
content (string | number | boolean | object | array | function)
Властивість content містить фактичні дані словника та підтримує:
- Примітивні значення: рядки, числа, булеві значення, null, undefined
- Типізовані вузли: спеціальні типи контенту, що використовують допоміжні функції Intlayer
- Вкладені об'єкти: складні структури даних
- Масиви: колекції контенту
- Функції: динамічна оцінка контенту
Необов'язкові властивості
title (string)
Зрозуміла для людини назва словника, яка допомагає ідентифікувати його в редакторах та CMS. Це особливо корисно при керуванні великою кількістю словників або роботі з інтерфейсами систем управління контентом.
Приклад:
Скопіюйте код у буфер обміну
description (string)
Детальний опис, який пояснює призначення словника, рекомендації щодо використання та будь-які особливі зауваження. Цей опис також використовується як контекст для генерації перекладів за допомогою ШІ, що робить його цінним для підтримки якості та послідовності перекладів.
Приклад:
Скопіюйте код у буфер обміну
tags (string[])
Масив рядків для категоризації та організації словників. Теги надають додатковий контекст та можуть використовуватись для фільтрації, пошуку або впорядкування словників в редакторах та CMS системах.
Приклад:
Скопіюйте код у буфер обміну
format ('intlayer' | 'icu' | 'i18next')
Визначає форматувальник, який використовується для вмісту словника. Це дозволяє застосовувати різні синтаксиси форматування повідомлень.
'intlayer': Форматувальник Intlayer за замовчуванням.'icu': Використовує форматування повідомлень ICU.'i18next': Використовує форматування повідомлень i18next.
Приклад:
Скопіюйте код у буфер обміну
locale (LocalesValues)
Перетворює словник у словник для конкретної локалі, де кожне поле, вказане в content, автоматично перетворюється на вузол перекладу. Коли ця властивість встановлена:
- Словник розглядається як словник однієї локалі
- Кожне поле стає вузлом перекладу для тієї конкретної локалі
- Ви НЕ повинні використовувати вузли перекладу (
t()) уcontentпри використанні цієї властивості - Якщо ця властивість відсутня, словник буде розглядатися як багатомовний словник
Див. Оголошення вмісту по локалях в Intlayer для додаткової інформації.
Приклад:
Скопіюйте код у буфер обміну
schema (SchemaKeys)
Схема вмісту словника. Якщо встановлено, вміст буде перевірено на відповідність цій схемі. Це дозволяє вам нав'язати певну структуру для вмісту вашого словника, використовуючи користувацькі схеми валідації, визначені в вашій конфігурації Intlayer.
Приклад:
Скопіюйте код у буфер обміну
Скопіюйте код у буфер обміну
location ('local' | 'remote' | 'hybrid' | string)
Вказує розташування словника та контролює спосіб його синхронізації з CMS:
'local': Словник керується лише локально. Він не буде відправлений до віддаленого CMS. Використовуйте це для контенту, який має залишатися у вашій кодовій базі.'remote': Словник керується лише віддалено. Після відправки до CMS він буде від'єднаний від локального файлу. Під час завантаження контенту віддалений словник буде отримано з CMS. Файл.contentз розташуваннямremoteбуде проігноровано після початкової відправки.'hybrid': Словник керується як локально, так і віддалено. Після відправки до CMS він залишиться синхронізованим, зміни з локального файлу відправляються до CMS, а віддалені зміни можуть бути отримані назад у локальний файл.string(напр.,'plugin'): Словник керується плагіном або користувацьким джерелом. Коли ви спробуєте відправити його, система запитає вас, що робити.
Приклад:
Скопіюйте код у буфер обміну
fill (Заповнення)
Інструкції для автоматичного заповнення вмісту словника з зовнішніх джерел. Це можна налаштувати глобально в intlayer.config.ts або для окремого словника. Підтримує кілька форматів:
true: Увімкнути заповнення для всіх локалейfalse: Вимкнути заповнення для всіх локалейstring: Шлях до одного файлу або шаблону з зміннимиobject: Шляхи до файлів для кожної локалі
Приклади:
Скопіюйте код у буфер обміну
Доступні змінні:
{{locale}}– код локалі (наприкладfr,es){{fileName}}– назва файлу (наприкладexample){{key}}– ключ словника (наприкладexample)
Див. Налаштування автоматичного заповнення в Intlayer для отримання додаткової інформації.
priority (число)
Вказує пріоритет словника для вирішення конфліктів. Якщо кілька словників містять той самий ключ, словник з найбільшим числом пріоритету перекриє інші. Це корисно для керування ієрархіями контенту та переваженням значень.
Приклад:
Скопіюйте код у буфер обміну
item (число)
Використовується разом із Колекціями, це поле визначає позицію елемента в колекції. Воно дозволяє створювати впорядковані колекції локалізованих елементів, які можна вибирати за індексом під час виконання.
Приклад:
Скопіюйте код у буфер обміну
Див. Колекції для отримання додаткової інформації.
variant (рядок)
Використовується разом із Варіантами, це поле визначає іменовані альтернативи вмісту. Воно дозволяє перемикатися між різними варіантами одного й того самого ключа словника під час виконання без зміни коду (наприклад, для A/B-тестування, сезонних банерів). Якщо не вказано, вважається варіантом за замовчуванням.
Приклад:
Скопіюйте код у буфер обміну
Див. Варіанти для отримання додаткової інформації.
meta (Record<string, string | number | boolean>)
Використовується разом із Динамічними Записами, це поле дозволяє оголошувати записи, керовані CMS, або довільні дані, отримані під час виконання за непрозорим ID. Ідентичність словника визначається довільним набором пар ключ-значення, оголошених у цьому полі meta.
Приклад:
Скопіюйте код у буфер обміну
Див. Динамічні Записи для отримання додаткової інформації.
Властивості CMS
version (string)
Ідентифікатор версії для віддалених словників. Допомагає відстежувати, яка версія словника використовується на даний момент; особливо корисно при роботі з віддаленими системами управління контентом.
importMode ('static' | 'dynamic' | 'fetch')
Режим імпорту визначає, як ваш словник імпортується у ваш додаток.
'static': Словник імпортується статично під час збірки. Це режим за замовчуванням.'dynamic': Словник імпортується динамічно під час виконання за допомогою API suspense.'fetch': Словник імпортується динамічно за допомогою API живої синхронізації.
Якщо встановлено, ця властивість перевизначає глобальний importMode, визначений у the dictionaryproperty ofintlayer.config.ts``.
Системні властивості (Автоматично згенеровані)
Ці властивості автоматично генеруються Intlayer і не повинні змінюватися вручну:
$schema (string)
JSON-схема, що використовується для валідації структури словника. Автоматично додається Intlayer для забезпечення цілісності словника.
id (string)
Для віддалених словників це унікальний ідентифікатор словника на віддаленому сервері. Використовується для отримання та керування віддаленим вмістом.
projectIds (string[])
Для віддалених словників цей масив містить ID проєктів, які можуть використовувати цей словник. Віддалений словник може бути спільно використаний кількома проєктами.
localId (LocalDictionaryId)
Унікальний ідентифікатор для локальних словників. Автоматично генерується Intlayer, щоб допомогти ідентифікувати словник і визначити, чи є він локальним або віддаленим, а також його розташування.
localIds (LocalDictionaryId[])
Для злитих словників цей масив містить ID усіх словників, які були об'єднані. Корисно для відстеження джерела злитого вмісту.
filePath (string)
Шлях до файлу локального словника, що вказує, з якого файлу .content було згенеровано словник. Допомагає з налагодженням та відстеженням джерела.
versions (string[])
Для віддалених словників цей масив містить усі доступні версії словника. Допомагає відстежувати, які версії доступні для використання.
filled (true)
Вказує, чи словник був автоматично заповнений з зовнішніх джерел. У разі конфліктів базові словники матимуть пріоритет над автоматично заповненими словниками.
location ('distant' | 'locale')
Вказує місцезнаходження словника:
'locale': Локальний словник (з файлів контенту)'distant': Віддалений словник (із зовнішнього джерела)
Типи вузлів контенту
Intlayer надає кілька спеціалізованих типів вузлів вмісту, які розширюють базові примітивні значення:
Перекладний контент (t)
Багатомовний контент, що змінюється залежно від локалі:
Скопіюйте код у буфер обміну
See Перекладний контент (t) Doc for more information.
Умовний контент (cond)
Контент, що змінюється залежно від булевих умов:
Скопіюйте код у буфер обміну
See Умовний контент (cond) Doc for more information.
Контент переліку (enu)
Контент, що змінюється залежно від значень переліку:
Скопіюйте код у буфер обміну
See Контент переліку (enu) Doc for more information.
Plural Content (plural)
Content that varies based on plural rules:
Скопіюйте код у буфер обміну
See Plural Content Doc for more information.
Вставний вміст (insert)
Вміст, який можна вставляти в інший вміст:
Скопіюйте код у буфер обміну
See Вставний вміст (insert) Doc for more information.
Вкладений вміст (nest)
Посилання на інші словники:
Скопіюйте код у буфер обміну
See Вкладений вміст (nest) Doc for more information.
Markdown-вміст (md)
Розширений текст у форматі Markdown:
Скопіюйте код у буфер обміну
See Markdown-вміст (md) Doc for more information.
HTML-вміст (html)
Багатий HTML-вміст, який може використовувати стандартні теги або власні компоненти:
Скопіюйте код у буфер обміну
See HTML-вміст (html) Doc for more information.
Гендерний вміст (gender)
Вміст, що змінюється залежно від гендеру:
Скопіюйте код у буфер обміну
See Гендерний вміст (gender) Doc for more information.
Вміст файлу (file)
Посилання на зовнішні файли:
Скопіюйте код у буфер обміну
See Вміст файлу (file) Doc for more information.
Створення файлів контенту
Базова структура файлу контенту
Файл контенту експортує об'єкт за замовчуванням, який відповідає типу Dictionary:
Скопіюйте код у буфер обміну
Файл вмісту в форматі JSON
Ви також можете створювати файли вмісту у форматі JSON:
Скопіюйте код у буфер обміну
Файл вмісту в форматі Markdown
Скопіюйте код у буфер обміну
Файл вмісту в форматі YAML
Скопіюйте код у буфер обміну
Файли вмісту для кожної локалі
Для словників по локалях вкажіть властивість locale:
Скопіюйте код у буфер обміну
Скопіюйте код у буфер обміну
Розширення файлів контенту
Intlayer дозволяє налаштовувати розширення файлів декларації контенту. Це налаштування надає гнучкість у керуванні проєктами великого масштабу та допомагає уникати конфліктів з іншими модулями.
Розширення за замовчуванням
За замовчуванням Intlayer відстежує всі файли з наведеними нижче розширеннями як файли декларацій контенту:
.content.json.content.json5.content.jsonc.content.ts.content.tsx.content.js.content.jsx.content.mjs.content.mjx.content.cjs.content.cjx.content.md.content.mdx.content.yaml.content.yml
Ці стандартні розширення підходять для більшості застосунків. Однак якщо у вас є спеціальні вимоги, ви можете визначити власні розширення, щоб оптимізувати процес збірки та зменшити ризик конфліктів з іншими компонентами.
Щоб налаштувати розширення файлів, які Intlayer використовує для ідентифікації файлів декларацій контенту, ви можете вказати їх у конфігураційному файлі Intlayer. Цей підхід корисний для проектів великого масштабу, де обмеження сфери процесу watch покращує продуктивність збірки.
Розширені концепції
Злиття словників
Коли декілька словників мають один і той самий ключ, Intlayer автоматично їх зливає. Поведінка злиття залежить від кількох факторів:
- Priority: Словники з більшими значеннями
priorityперекривають ті, що мають менші значення - Автозаповнення проти Бази: базові словники мають перевагу над автоматично заповненими словниками
- Розташування: локальні словники мають перевагу над віддаленими словниками (коли пріоритети рівні)
Безпека типів
Intlayer забезпечує повну підтримку TypeScript для файлів контенту:
Скопіюйте код у буфер обміну
Вкладення вузлів
Ви можете без проблем вкладати функції одна в одну.
Приклад:
Скопіюйте код у буфер обміну
import { t, enu, cond, nest, md, type Dictionary } from "intlayer";
const getName = async () => "John Doe";
export default {
key: "page",
content: {
// `getIntlayer('page','en').hiMessage` повертає `['Hi', ' ', 'John Doe']`
hiMessage: [
t({
uk: "Привіт",
en: "Hi",
fr: "Salut",
es: "Hola",
}),
" ",
getName(),
],
// Композитний контент, що вкладає умову, перелік (enumeration) та багатомовний контент
// `getIntlayer('page','en').advancedContent(true)(10)` повертає 'Multiple items found'
advancedContent: cond({
true: enu({
"0": t({
uk: "Не знайдено жодного елемента",
en: "No items found",
... (rest of file continues)
"0": t({
uk: "Жодних елементів не знайдено",
en: "No items found",
fr: "Aucun article trouvé",
es: "No se encontraron artículos",
}),
"1": t({
uk: "Знайдено один елемент",
en: "One item found",
fr: "Un article trouvé",
es: "Se encontró un artículo",
}),
">1": t({
uk: "Знайдено кілька елементів",
en: "Multiple items found",
fr: "Plusieurs articles trouvés",
es: "Se encontraron múltiples artículos",
}),
}),
false: t({
uk: "Немає дійсних даних",
en: "No valid data available",
fr: "Aucune donnée valide disponible",
es: "No hay datos válidos disponibles",
}),
}),
},
} satisfies Dictionary;Найкращі практики
Конвенції найменувань:
- Використовуйте kebab-case для ключів словника (
"about-page-meta") - Групуйте пов'язаний контент під одним префіксом ключа
- Використовуйте kebab-case для ключів словника (
Організація контенту:
- Зберігайте пов'язаний контент разом у тому ж словнику
- Використовуйте вкладені об'єкти для організації складних структур контенту
- Використовуйте теги для категоризації
- Використовуйте
fill, щоб автоматично заповнювати відсутні переклади
Продуктивність:
- Налаштуйте конфігурацію контенту, щоб обмежити область відстежуваних файлів
- Використовуйте live dictionaries лише коли потрібні оновлення в реальному часі (наприклад, A/B тестування тощо)
- Переконайтеся, що плагін трансформації збірки (
@intlayer/swc, or@intlayer/babel) увімкнений, щоб оптимізувати словник під час збірки