Автоматическое заполнение файлов объявления контента переводов

Автоматическое заполнение файлов объявления контента в вашей CI — это способ ускорить рабочий процесс разработки.

Понимание поведения

Команда fill включает два режима:

• Complete: Автоматически заполняет все недостающее содержимое для каждой локали и редактирует текущий файл или другой файл, если он указан. То есть режим complete пропустит перевод существующего содержимого, если оно уже переведено.
• Review: Автоматически заполняет все содержимое для каждой локали и генерирует для конкретного файла или другого файла, если он указан.

Команда fill будет обрабатывать все ваши файлы объявления содержимого локали. То есть она не будет обрабатывать ваше удаленное содержимое из CMS. CMS включает собственное управление переводами. Если вы используете плагины, такие как @intlayer/sync-json-plugin, Intlayer преобразует файлы JSON в файлы объявления содержимого локали. То есть они будут обработаны командой fill.

Новые сгенерированные файлы включают инструкцию filled в качестве метаданных словаря. Эта инструкция будет использоваться Intlayer для определения того, был ли файл автоматически заполнен или нет, и пропустит этот файл от повторного перевода, если она присутствует.

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

• Из вашего .content.{ts|js|json} → инструкция fill
• Из вашего файла конфигурации .intlayer.config.ts → инструкция dictionary.fill
• По умолчанию будет установлено значение true

Для файлов объявления содержимого для каждой локали инструкция true будет заменена на ./{{fileName}}.fill.content.json. Это потому, что файл объявления содержимого для каждой локали не может получать дополнительное локализованное содержимое. Поэтому он будет генерировать новый файл, чтобы не перезаписать существующий файл.

Поведение по умолчанию

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

Глобальные параметры конфигурации

1. fill: true (по умолчанию) - Автоматически заполнить все локали и отредактировать текущий файл
2. fill: false - Отключить автоматическое заполнение для этого файла контента
3. fill: "./relative/path/to/file" - Создать/обновить указанный файл без редактирования текущего, указав относительный путь, разрешенный на основе расположения текущего файла
4. fill: "/absolute/path/to/file" - Создать/обновить указанный файл без редактирования текущего, указав относительный путь, разрешенный на основе расположения базовой директории (поле baseDir в файле конфигурации .intlayer.config.ts)
5. fill: "C:\absolute\path\to\file" - Создать/обновить указанный файл без редактирования текущего, указав абсолютный путь, разрешенный на основе вашей операционной системы
6. fill: { [key in Locales]?: string } - Создать/обновить указанный файл для каждой локали

Изменения поведения в v7

В v7 поведение команды fill было обновлено:

• fill: true - Перезаписывает текущий файл с заполненным содержимым для всех локалей
• fill: "path/to/file" - Заполняет указанный файл без изменения текущего файла
• fill: false - Полностью отключает автоматическое заполнение

При использовании опции пути для записи в другой файл механизм заполнения работает через отношение master-slave между файлами объявления содержимого. Основной файл (master) служит источником истины, и при его обновлении Intlayer автоматически применит эти изменения к производным (заполненным) файлам объявления, указанным в пути.

Кастомизация по локалям

Вы также можете кастомизировать поведение для каждой локали, используя объект:

const config: IntlayerConfig = {
  content: {
    internationalization: {
      locales: [Locales.ENGLISH, Locales.FRENCH, Locales.POLISH],
      defaultLocale: Locales.ENGLISH,
      requiredLocales: [Locales.ENGLISH], // Рекомендуется, чтобы избежать Property 'pl' is missing in type '{ en: string; xxx } on your t function if
    },
  },
  dictionary: {
    fill: {
      en: true, // Заполнить и отредактировать текущий файл для английского языка
      fr: "./translations/fr.json", // Создать отдельный файл для французского языка
      es: false, // Отключить заполнение для испанского языка
    },
  },
};

Это позволяет вам иметь разные поведения заполнения для разных локалей в одном проекте.

import { Locales, type Dictionary } from "intlayer";

const exampleContent = {
  key: "example",
  locale: Locales.ENGLISH,
  fill: "./example.content.json",
  content: {
    contentExample: "This is an example of content",
  },
} satisfies Dictionary;

export default exampleContent;

Вот файл объявления содержимого для каждой локали с использованием инструкции fill.

Затем, когда вы выполните следующую команду:

npx intlayer fill --file 'src/components/example/example.content.ts'

Intlayer автоматически создаст производный файл объявления в src/components/example/example.content.json, заполняя все локали, которые еще не объявлены в основном файле.

{
  "key": "example",
  "content": {
    "contentExample": {
      "nodeType": "translation",
      "translation": {
        "fr": "Ceci est un exemple de contenu",
        "es": "Este es un ejemplo de contenido",
      },
    },
  },
}

После этого оба файла объявления будут объединены в один словарь, доступный с помощью стандартного хука useIntlayer("example") (react) / композабла (vue).

Глобальная конфигурация

Вы можете настроить глобальную конфигурацию автозаполнения в файле intlayer.config.ts.

import { type IntlayerConfig, Locales } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
    defaultLocale: Locales.ENGLISH,
    requiredLocales: [Locales.ENGLISH, Locales.FRENCH],
  },
  dictionary: {
    // Автогенерация отсутствующих переводов для всех словарей
    fill: "./{{fileName}}Filled.content.ts",
    //
    // fill: "/messages/{{locale}}/{{key}}/{{fileName}}.content.json",
    //
    // fill: true, // автогенерация отсутствующих переводов для всех словарей, как при использовании "./{{fileName}}.content.json"
    //
    // fill: {
    //   en: "./{{fileName}}.en.content.json",
    //   fr: "./{{fileName}}.fr.content.json",
    //   es: "./{{fileName}}.es.content.json",
    // },
  },
};

export default config;

Вы по-прежнему можете настраивать каждый словарь отдельно, используя поле fill в файлах содержимого. Intlayer сначала рассмотрит конфигурацию каждого словаря, а затем вернётся к глобальной конфигурации.

Формат автозаполненного файла

Рекомендуемый формат для автоматически заполняемых файлов деклараций, JSON, который помогает избежать ограничений форматирования. Однако Intlayer также поддерживает форматы .ts, .js, .mjs, .cjs и другие.

const exampleContent = {
  key: "example",
  autoFill: "./example.filled.content.ts",
  content: {
    // Ваше содержимое
  },
};

Это сгенерирует файл по адресу:

src/components/example/example.filled.content.ts

Генерация файлов .js, .ts и подобных работает следующим образом:

• Если файл уже существует, Intlayer будет парсить его с помощью AST (Абстрактного синтаксического дерева), чтобы найти каждое поле и вставить отсутствующие переводы.
• Если файл не существует, Intlayer сгенерирует его, используя шаблон файла декларации содержимого по умолчанию.

Абсолютные пути

Поле autoFill также поддерживает абсолютные пути.

const exampleContent = {
  key: "example",
  autoFill: "/messages/example.content.json",
  content: {
    // Ваше содержимое
  },
};

Это сгенерирует файл по адресу:

/messages/example.content.json

Автоматическая генерация файлов деклараций содержимого для каждого локаля

Поле autoFill также поддерживает генерацию файлов деклараций содержимого для каждого локаля.

const exampleContent = {
  key: "example",
  autoFill: {
    fr: "./example.fr.content.json",
    es: "./example.es.content.json",
  },
  content: {
    // Ваше содержимое
  },
};

Это сгенерирует два отдельных файла:

• src/components/example/example.fr.content.json
• src/components/example/example.es.content.json

В этом случае, если объект не содержит все локали, Intlayer пропускает генерацию оставшихся локалей.

Фильтрация автозаполнения для конкретной локали

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

const exampleContent = {
  key: "example",
  autoFill: {
    fr: "./example.fr.content.json",
  },
  content: {
    // Ваше содержимое
  },
};

Это сгенерирует только файл перевода на французский язык.

Переменные пути

Вы можете использовать переменные внутри пути autoFill для динамического определения целевых путей для сгенерированных файлов.

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

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

const exampleContent = {
  key: "example",
  autoFill: "/messages/{{locale}}/{{key}}.content.json",
  content: {
    // Ваше содержимое
  },
};

Это сгенерирует:

• /messages/fr/example.content.json
• /messages/es/example.content.json

const exampleContent = {
  key: "example",
  autoFill: "./{{fileName}}.content.json",
  content: {
    // Ваше содержимое
  },
};

Это сгенерирует:

• ./index.content.json
• ./index.content.json