Файл контента

Что такое файл контента?

Файл контента в Intlayer, это файл, содержащий определения словарей.
Эти файлы объявляют текстовое содержимое вашего приложения, переводы и ресурсы.
Файлы контента обрабатываются Intlayer для генерации словарей.

Словари будут конечным результатом, который ваше приложение импортирует с помощью хука useIntlayer.

Ключевые понятия

Словарь

Словарь, это структурированная коллекция контента, организованная по ключам. Каждый словарь содержит:

• Ключ: уникальный идентификатор словаря
• Контент: фактические значения контента (текст, числа, объекты и т.д.)
• Метаданные: дополнительная информация, такая как заголовок, описание, теги и т.д.

Файл контента

Пример файла контента:

import { type ReactNode } from "react";
import {
  t,
  enu,
  plural,
  cond,
  nest,
  md,
  insert,
  file,
  type Dictionary,
} from "intlayer";

interface Content {
  imbricatedContent: {
    imbricatedContent2: {
      stringContent: string; // строковый контент
      numberContent: number; // числовой контент
      booleanContent: boolean; // булевый контент
      javaScriptContent: string; // контент JavaScript
    };
  };
  multilingualContent: string; // мультиязычный контент
  quantityContent: string;
  pluralContent: string; // контент с количеством
  conditionalContent: string; // условный контент
  markdownContent: never; // markdown контент (никогда не используется)
  htmlContent: never; // HTML контент
  externalContent: string; // внешний контент
  insertionContent: string; // контент с вставкой
  nestedContent: string; // вложенный контент
  fileContent: string; // контент из файла
  jsxContent: ReactNode; // JSX контент
}

export default {
  key: "page", // ключ словаря
  content: {
    imbricatedContent: {
      imbricatedContent2: {
        stringContent: "Hello World",
        numberContent: 123,
        booleanContent: true,
        javaScriptContent: `${process.env.NODE_ENV}`,
      },
    },
    multilingualContent: t({
      ru: "Русский контент",
      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 является универсальным и позволяет усилить форматирование вашего словаря

Узлы содержимого

Узлы содержимого являются строительными блоками содержимого словаря. Они могут быть:

• Примитивные значения: строки, числа, булевы значения, null, undefined
• Типизированные узлы: специальные типы содержимого, такие как переводы, условия, markdown и т.д.
• Функции: динамическое содержимое, которое может быть вычислено во время выполнения см. Получение функций
• Множественное число: См. Множественное число См. Множественное число
• Вложенное содержимое: ссылки на другие словари

Типы содержимого

Intlayer поддерживает различные типы содержимого через типизированные узлы:

• Содержимое перевода: Многоязычный текст с локализованными значениями см. Содержимое перевода
• Условное содержимое: Содержимое, зависящее от булевых выражений см. Условное содержимое
• Перечисляемое содержимое: Содержимое, изменяющееся в зависимости от перечисляемых значений см. Перечисляемое содержимое
• Вставляемое содержимое: Содержимое, которое можно вставлять в другое содержимое см. Вставляемое содержимое
• Содержимое Markdown: Форматированный текст в формате Markdown см. Содержимое Markdown
• HTML-содержимое: Богатое HTML-содержимое с необязательными пользовательскими компонентами см. HTML-содержимое
• Вложенное содержимое: Ссылки на другие словари см. Вложенное содержимое
• Содержимое по полу: Содержимое, зависящее от пола см. Содержимое по полу
• Содержимое файла: Ссылки на внешние файлы см. Содержимое файла

Структура словаря

Словарь в Intlayer определяется типом Dictionary и содержит несколько свойств, которые управляют его поведением:

Обязательные свойства

key (строка)

Идентификатор словаря. Если несколько словарей имеют одинаковый ключ, Intlayer автоматически объединит их.

Используйте соглашение об именовании в стиле kebab-case (например, "about-page-meta").

Content (строка | число | булево | объект | массив | функция)

Свойство content содержит фактические данные словаря и поддерживает:

• Примитивные значения: строки, числа, булевы значения, null, undefined
• Типизированные узлы: специальные типы содержимого с использованием вспомогательных функций Intlayer
• Вложенные объекты: сложные структуры данных
• Массивы: коллекции содержимого
• Функции: динамическая оценка содержимого

Необязательные свойства

title (string)

Читаемое человеком название словаря, которое помогает идентифицировать его в редакторах и системах управления контентом (CMS). Это особенно полезно при работе с большим количеством словарей или при использовании интерфейсов управления контентом.

Пример:

{  key: "about-page-meta",  title: "Метаданные страницы «О нас»",  content: { /* ... */ }}

description (string)

Подробное описание, объясняющее назначение словаря, рекомендации по использованию и любые особые замечания. Это описание также используется как контекст для генерации переводов с помощью ИИ, что важно для поддержания качества и согласованности переводов.

Пример:

{  key: "about-page-meta",  description: [    "Этот словарь управляет метаданными страницы «О нас»",    "Рассмотрите лучшие практики для SEO:",    "- Заголовок должен содержать от 50 до 60 символов",    "- Описание должно содержать от 150 до 160 символов",  ].join('\n'),  content: { /* ... */ }}

tags (string[])

Массив строк для категоризации и организации словарей. Теги предоставляют дополнительный контекст и могут использоваться для фильтрации, поиска или организации словарей в редакторах и системах управления контентом.

Пример:

{  key: "about-page-meta",  tags: ["metadata", "about-page", "seo"],  content: { /* ... */ }}

format ('intlayer' | 'icu' | 'i18next')

Указывает форматтер, который будет использоваться для содержимого словаря. Это позволяет использовать различные синтаксисы форматирования сообщений.

• 'intlayer': Форматтер Intlayer по умолчанию.
• 'icu': Использует форматирование сообщений ICU.
• 'i18next': Использует форматирование сообщений i18next.

Пример:

{  key: "my-dictionary",  format: "icu",  content: {    message: "Hello {name}, you have {count, plural, one {# message} other {# messages}}"  }}

format ('intlayer' | 'icu' | 'i18next')

Указывает форматтер для использования содержимого словаря. Это позволяет использовать различные синтаксисы форматирования сообщений.

• 'intlayer': Форматтер Intlayer по умолчанию.
• 'icu': Использует форматирование сообщений ICU.
• 'i18next': Использует форматирование сообщений i18next.

Пример:

{  key: "my-dictionary",  format: "icu",  content: {    message: "Hello {name}, you have {count, plural, one {# message} other {# messages}}"  }}

locale (LocalesValues)

Преобразует словарь в словарь для каждого локаля, где каждое поле, объявленное в содержимом, автоматически преобразуется в узел перевода. Когда это свойство установлено:

• Словарь рассматривается как словарь для одного языка (локали)
• Каждое поле становится узлом перевода для этой конкретной локали
• НЕ следует использовать узлы перевода (t()) в содержимом при использовании этого свойства
• Если свойство отсутствует, словарь будет рассматриваться как многоязычный

См. Объявление контента по локалям в Intlayer для получения дополнительной информации.

Пример:

// Словарь для одной локали{  "key": "about-page",  "locale": "en",  "content": {    "title": "About Us", // Это становится узлом перевода для 'en'    "description": "Learn more about our company"  }}

schema (SchemaKeys)

Схема содержимого словаря. Если установлена, содержимое будет проверено на соответствие этой схеме. Это позволяет вам навязать определённую структуру для содержимого вашего словаря, используя пользовательские схемы валидации, определённые в вашей конфигурации Intlayer.

Пример:

import { z } from "zod";export default {  schemas: {    "seo-metadata": z.object({      title: z.string().min(50).max(60),      description: z.string().min(150).max(160),    }),  },};

import { type Dictionary } from "intlayer";const aboutPageMetaContent = {  key: "about-page-meta",  schema: "seo-metadata",  content: {    title: "About Our Company - Learn More About Us",    description: "Discover our company's mission, values, and team.",  },} satisfies Dictionary;export default aboutPageMetaContent;

location ('local' | 'remote' | 'hybrid' | string)

Указывает расположение словаря и управляет тем, как он синхронизируется с CMS:

• 'local': Словарь управляется только локально. Он не будет отправлен в удалённый CMS. Используйте это для контента, который должен оставаться в вашей кодовой базе.
• 'remote': Словарь управляется только удалённо. После отправки в CMS он будет отсоединён от локального файла. Во время загрузки контента удалённый словарь будет получен из CMS. Файл .content с расположением remote будет проигнорирован после первоначальной отправки.
• 'hybrid': Словарь управляется как локально, так и удалённо. После отправки в CMS он останется синхронизированным, изменения из локального файла отправляются в CMS, а удалённые изменения могут быть получены обратно в локальный файл.
• string (например, 'plugin'): Словарь управляется плагином или пользовательским источником. Когда вы попытаетесь отправить его, система спросит вас, что делать.

Пример:

{  key: "about-page",  location: "local", // Контент остаётся только в вашей кодовой базе  content: {    title: "About Us"  }}

autoFill (AutoFill)

Инструкции по автоматическому заполнению содержимого словаря из внешних источников. Это можно настроить глобально в intlayer.config.ts или для каждого словаря отдельно. Поддерживаются несколько форматов:

• true: Включить авто-заполнение для всех локалей
• string: Путь к одному файлу или шаблон с переменными
• object: Пути к файлам для каждой локали

Примеры:

// Включить для всех локалей{  "autoFill": true}// Один файл{  "autoFill": "./translations/aboutPage.content.json"}// Шаблон с переменными{  "autoFill": "/messages/{{locale}}/{{key}}/{{fileName}}.content.json"}// Точная настройка для каждой локали{  "autoFill": {    "en": "./translations/en/aboutPage.content.json",    "fr": "./translations/fr/aboutPage.content.json",    "es": "./translations/es/aboutPage.content.json"  }}

Доступные переменные:

• {{locale}} – Код локали (например, fr, es)
• {{fileName}} – Имя файла (например, example)
• {{key}} – Ключ словаря (например, example)

Подробнее смотрите в разделе Конфигурация автозаполнения в Intlayer.

priority (число)

Указывает приоритет словаря для разрешения конфликтов. Когда несколько словарей содержат одинаковый ключ, словарь с наивысшим числовым приоритетом переопределит остальные. Это полезно для управления иерархией контента и переопределениями.

Пример:

// Базовый словарь{  key: "welcome-message",  priority: 1,  content: { message: "Welcome!" }}// Словарь-переопределение{  key: "welcome-message",  priority: 10,  content: { message: "Добро пожаловать в наш премиум-сервис!" }}// Это переопределит базовый словарь

Свойства CMS

version (строка)

Идентификатор версии для удалённых словарей. Помогает отслеживать, какая версия словаря в данный момент используется, особенно полезно при работе с удалёнными системами управления контентом.

importMode ('static' | 'dynamic' | 'fetch')

Режим импорта определяет, как ваш словарь импортируется в ваше приложение.

• 'static': Словарь импортируется статически во время сборки. Это режим по умолчанию.
• 'dynamic': Словарь импортируется динамически во время выполнения с использованием API suspense.
• 'fetch': Словарь импортируется динамически с использованием API живой синхронизации.

Если установлено, это свойство переопределяет глобальный importMode, определённый в the dictionaryproperty ofintlayer.config.ts``.

Системные свойства (Автоматически сгенерированные)

Эти свойства автоматически генерируются Intlayer и не должны изменяться вручную:

$schema (string)

JSON-схема, используемая для валидации структуры словаря. Автоматически добавляется Intlayer для обеспечения целостности словаря.

id (string)

Для удалённых словарей это уникальный идентификатор словаря на удалённом сервере. Используется для получения и управления удалённым контентом.

localId (LocalDictionaryId)

Уникальный идентификатор для локальных словарей. Автоматически генерируется Intlayer для помощи в идентификации словаря и определения, является ли он локальным или удалённым, а также его расположения.

localIds (LocalDictionaryId[])

Для объединённых словарей этот массив содержит идентификаторы всех словарей, которые были объединены вместе. Полезно для отслеживания источника объединённого содержимого.

filePath (string)

Путь к файлу локального словаря, указывающий, из какого файла .content был сгенерирован словарь. Помогает при отладке и отслеживании источника.

versions (string[])

Для удалённых словарей этот массив содержит все доступные версии словаря. Помогает отслеживать, какие версии доступны для использования.

autoFilled (true)

Указывает, был ли словарь автоматически заполнен из внешних источников. В случае конфликтов базовые словари имеют приоритет над автоматически заполненными.

location ('distant' | 'locale')

Указывает расположение словаря:

• 'locale': Локальный словарь (из файлов контента)
• 'distant': Удалённый словарь (из внешнего источника)

Типы узлов контента

Intlayer предоставляет несколько специализированных типов узлов контента, которые расширяют базовые примитивные значения:

Переводимый контент (t)

Многоязычный контент, который варьируется в зависимости от локали:

import { t } from "intlayer";// TypeScript/JavaScriptmultilingualContent: t({  en: "Welcome to our website",  fr: "Bienvenue sur notre site web",  es: "Bienvenido a nuestro sitio web",});

См. Переводимый контент (t) Документация для получения дополнительной информации.

Условный контент (cond)

Контент, который меняется в зависимости от булевых условий:

import { cond } from "intlayer";conditionalContent: cond({  true: "User is logged in",  false: "Please log in to continue",});

См. Условный контент (cond) Документация для получения дополнительной информации.

Перечисляемый контент (enu)

Контент, который меняется в зависимости от перечисленных значений:

import { enu } from "intlayer";statusContent: enu({  pending: "Ваш запрос находится в ожидании",  approved: "Ваш запрос был одобрен",  rejected: "Ваш запрос был отклонён",});

См. Перечисляемый контент (enu) Документация для получения дополнительной информации.

Множественное число (plural)

Контент, который варьируется в зависимости от правил множественного числа:

import { plural } from "intlayer";pluralContent: plural({  one: "One car",  other: "{{count}} cars",});

См. Множественное число документацию для получения дополнительной информации.

Вставляемый контент (insert)

Контент, который можно вставлять в другой контент:

import { insert } from "intlayer";insertionContent: insert("Этот текст можно вставить куда угодно");

См. Вставляемый контент (insert) Документация для получения дополнительной информации.

Вложенный контент (nest)

Ссылки на другие словари:

import { nest } from "intlayer";nestedContent: nest("about-page");

См. Вложенный контент (nest) Документация для получения дополнительной информации.

Контент в формате Markdown (md)

Форматированный текст в формате Markdown:

import { md } from "intlayer";markdownContent: md(  "# Добро пожаловать\n\nЭто **жирный** текст с [ссылками](https://example.com)");

См. Контент в формате Markdown (md) Документация для получения дополнительной информации.

HTML-контент (html)

Богатый HTML-контент, который может использовать стандартные теги или пользовательские компоненты:

import { html, file, t } from "intlayer";// Встроенный HTMLhtmlContent: html("<p>Hello <strong>World</strong></p>");// По-локальный HTML из внешних файловlocalizedHtmlContent: t({  en: html(file("./content.en.html")),  ru: html(file("./content.ru.html")),});

См. HTML-контент (html) Документация для получения дополнительной информации.

Контент по половому признаку (gender)

Контент, который меняется в зависимости от пола:

import { gender } from "intlayer";genderContent: gender({  male: "Он разработчик",  female: "Она разработчик",  other: "Они разработчики",});

См. Контент по половому признаку (gender) Документация для получения дополнительной информации.

Контент из файла (file)

Ссылки на внешние файлы:

import { file } from "intlayer";fileContent: file("./path/to/content.txt");

См. Контент из файла (file) Документация для получения дополнительной информации.

Создание файлов контента

Основная структура файла контента

Файл контента экспортирует объект по умолчанию, который соответствует типу Dictionary:

// example.content.tsimport { t, cond, nest, md, insert, file } from "intlayer";export default {  key: "welcome-page",  title: "Содержание страницы приветствия",  description:    "Контент для главной страницы приветствия, включая секцию героя и функции",  tags: ["страница", "приветствие", "главная"],  content: {    hero: {      title: t({        en: "Welcome to Our Platform",        fr: "Bienvenue sur Notre Plateforme",        es: "Bienvenido a Nuestra Plataforma",      }),      subtitle: t({        en: "Build amazing applications with ease",        fr: "Construisez des applications incroyables avec facilité",        es: "Construye aplicaciones increíbles con facilidad",      }),      cta: cond({        true: t({          en: "Get Started",          fr: "Commencer",          es: "Comenzar",        }),        false: t({          en: "Sign Up",          fr: "S'inscrire",          es: "Registrarse",        }),      }),    },    features: [      {        title: t({          ru: "Простота использования",          en: "Easy to Use",          fr: "Facile à Utiliser",          es: "Fácil de Usar",        }),        description: t({          ru: "Интуитивно понятный интерфейс для всех уровней навыков",          en: "Intuitive interface for all skill levels",          fr: "Interface intuitive pour tous les niveaux",          es: "Interfaz intuitiva para todos los niveles",        }),      },    ],    documentation: nest("documentation"),    readme: file("./README.md"),  },} satisfies Dictionary;

JSON Content File

You can also create content files in JSON format:

{  "key": "welcome-page",  "title": "Содержание главной страницы приветствия",  "description": "Содержимое главной страницы приветствия",  "tags": ["page", "welcome"],  "content": {    "hero": {      "title": {        "nodeType": "translation",        "translation": {          "en": "Добро пожаловать на нашу платформу",          "fr": "Bienvenue sur Notre Plateforme"        }      },      "subtitle": {        "nodeType": "translation",        "translation": {          "en": "Создавайте удивительные приложения с легкостью",          "fr": "Construisez des applications incroyables avec facilité"        }      }    }  }}

Markdown Content File

---key: welcome-pagelocale: entitle: Welcome Page Contentdescription: Content for the main welcome pagetags:  - page  - welcome---# Welcome to Our Platform## Build amazing applications with ease

YAML Content File

key: welcome-pagetitle: Welcome Page Contentdescription: Content for the main welcome pagelocale: "en"tags:  - page  - welcomecontent:  hero:    title: Welcome to Our Platform    subtitle: Build amazing applications with ease

Файлы контента для каждого локаля

Для словарей, специфичных для локали, укажите свойство locale:

// welcome-page.en.content.tsexport default {  key: "welcome-page",  locale: "en",  content: {    hero: {      title: "Добро пожаловать на нашу платформу",      subtitle: "Создавайте удивительные приложения с легкостью",    },  },} satisfies Dictionary;

// welcome-page.fr.content.tsexport default {  key: "welcome-page",  locale: "fr",  content: {    hero: {      title: "Bienvenue sur Notre Plateforme",      subtitle: "Construisez des applications incroyables avec facilité",    },  },} satisfies Dictionary;

Расширения файлов контента

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. Этот подход полезен для крупных проектов, где ограничение области наблюдения улучшает производительность сборки.

Расширенные концепции

Объединение словарей

Когда несколько словарей имеют одинаковый ключ, Intlayer автоматически объединяет их. Поведение при объединении зависит от нескольких факторов:

• Приоритет: словари с более высоким значением priority переопределяют словари с более низким значением
• Автозаполнение против базового: базовые словари имеют приоритет над автозаполненными словарями
• Расположение: локальные словари имеют приоритет над удалёнными словарями (при равенстве приоритетов)

Типобезопасность

Intlayer предоставляет полную поддержку TypeScript для файлов контента:

// Определите тип вашего контентаinterface WelcomePageContent {  hero: {    title: string;    subtitle: string;    cta: string;  };  features: Array<{    title: string;    description: string;  }>;}// Используйте его в вашем словареexport default {  key: "welcome-page",  content: {    // TypeScript обеспечит автозаполнение и проверку типов    hero: {      title: "Welcome",      subtitle: "Build amazing apps",      cta: "Get Started",    },  },} satisfies Dictionary<WelcomePageContent>;

Вложенность узлов

Вы можете без проблем вкладывать функции друг в друга.

Пример:

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({
        en: "Hi",
        fr: "Salut",
        es: "Hola",
      }),
      " ",
      getName(),
    ],
    // Композитный контент, вкладывающий условие, перечисление и многоязычный контент
    // `getIntlayer('page','en').advancedContent(true)(10)` возвращает 'Multiple items found'
    advancedContent: cond({
      true: enu({
        "0": t({
          en: "No items found",
          fr: "Aucun article trouvé",
          es: "No se encontraron artículos",
        }),
        "1": t({
          en: "One item found",
          fr: "Un article trouvé",
          es: "Se encontró un artículo",
        }),
        ">1": t({
          en: "Multiple items found",
          fr: "Plusieurs articles trouvés",
          es: "Se encontraron múltiples artículos",
        }),
      }),
      false: t({
        en: "No valid data available",
        fr: "Aucune donnée valide disponible",
        es: "No hay datos válidos disponibles",
      }),
    }),
  },
} satisfies Dictionary;

Лучшие практики

1. Соглашения об именах:

   • Используйте kebab-case для ключей словаря ("about-page-meta")
   • Группируйте связанный контент под одним префиксом ключа

2. Организация контента:

   • Держите связанный контент вместе в одном словаре
   • Используйте вложенные объекты для организации сложных структур контента
   • Используйте теги для категоризации
   • Используйте autoFill для автоматического заполнения отсутствующих переводов

3. Производительность:

   • Настройте конфигурацию контента, чтобы ограничить область отслеживаемых файлов
   • Используйте живые словари только тогда, когда необходимы обновления в реальном времени (например, A/B тестирование и т.д.)
   • Убедитесь, что плагин трансформации сборки (@intlayer/swc или @intlayer/babel) включен для оптимизации словаря во время сборки