Intlayer Compiler | Автоматизированное извлечение контента для i18n

Что такое Intlayer Compiler?

Intlayer Compiler - это мощный инструмент, разработанный для автоматизации процесса интернационализации (i18n) в ваших приложениях. Он сканирует ваш исходный код (JSX, TSX, Vue, Svelte) на предмет объявлений контента, извлекает их и автоматически генерирует необходимые файлы словарей. Это позволяет вам хранить контент вместе с компонентами, в то время как Intlayer управляет и синхронизирует ваши словари.

Почему стоит использовать Intlayer Compiler?

• Автоматизация: устраняет необходимость вручную копировать и вставлять контент в словари.
• Скорость: оптимизированное извлечение контента обеспечивает быструю сборку.
• Опыт разработчика: храните объявления контента прямо там, где они используются, что улучшает поддерживаемость.
• Живые обновления: поддержка Hot Module Replacement (HMR) для мгновенной обратной связи во время разработки.

См. блог-пост Compiler vs. Declarative i18n для более глубокого сравнения.

Почему не использовать Intlayer Compiler?

Хотя компилятор предлагает отличный опыт "работает из коробки", он также вводит некоторые компромиссы, о которых вы должны знать:

• Эвристическая неоднозначность: Компилятор должен угадывать, что является пользовательским контентом, а что - логикой приложения (например, className="active", коды состояния, ID продуктов). В сложных кодовых базах это может привести к ложным срабатываниям или пропущенным строкам, которые требуют ручных аннотаций и исключений.
• Только статическое извлечение: Извлечение на основе компилятора полагается на статический анализ. Строки, которые существуют только во время выполнения (коды ошибок API, поля CMS и т.д.), не могут быть обнаружены или переведены компилятором в одиночку, поэтому вам все еще нужна дополнительная стратегия i18n времени выполнения.

Для более глубокого архитектурного сравнения см. блог-пост Compiler vs. Declarative i18n.

В качестве альтернативы, для автоматизации процесса i18n при сохранении полного контроля над контентом, Intlayer также предоставляет команду автоматического извлечения intlayer extract (см. документацию CLI) или команду Intlayer: extract content to Dictionary из расширения Intlayer VS Code (см. документацию расширения VS Code).

Использование

npm install vite-intlayer

import { defineConfig } from "vite";import { intlayer, intlayerCompiler } from "vite-intlayer";export default defineConfig({ plugins: [   intlayer(),   intlayerCompiler(), // Добавляет плагин компилятора ],});

# Для Vuenpm install @intlayer/vue-compiler# Для Sveltenpm install @intlayer/svelte-compiler

npm install @intlayer/babel

const { intlayerExtractBabelPlugin, intlayerOptimizeBabelPlugin, getExtractPluginOptions, getOptimizePluginOptions,} = require("@intlayer/babel");module.exports = { presets: ["next/babel"], plugins: [   // Извлечение контента из компонентов в словари   [intlayerExtractBabelPlugin, getExtractPluginOptions()],   // Оптимизация импорта путем замены useIntlayer на прямой импорт словарей   [intlayerOptimizeBabelPlugin, getOptimizePluginOptions()], ],};

Пользовательская конфигурация

Чтобы настроить поведение компилятора, вы можете обновить файл intlayer.config.ts в корне вашего проекта.

import { type IntlayerConfig, Locales } from "intlayer";const config: IntlayerConfig = {  compiler: {    /**     * Указывает, должен ли компилятор быть включен.     * Установите значение 'build-only', чтобы пропустить компилятор во время разработки и ускорить запуск.     */    enabled: true,    /**     * Определяет путь к выходным файлам. Заменяет `outputDir`.     *     * - Пути, начинающиеся с `./`, разрешаются относительно каталога компонента.     * - Пути, начинающиеся с `/`, разрешаются относительно корня проекта (`baseDir`).     *     * - Включение переменной `{{locale}}` в путь позволит создавать словари, разделенные по языкам.     *     * Примеры:     * ```ts     * {     *   // Создавать многоязычные файлы .content.ts рядом с компонентом     *   output: ({ fileName, extension }) => `./${fileName}${extension}`,     *     *   // output: './{{fileName}}{{extension}}', // Эквивалентное использование строки шаблона     * }     * ```     *     * ```ts     * {     *   // Создавать централизованные JSON-файлы по языкам в корне проекта     *   output: ({ key, locale }) => `/locales/${locale}/${key}.content.json`,     *     *   // output: '/locales/{{locale}}/{{key}}.content.json', // Эквивалентное использование строки шаблона     * }     * ```     *     * Список переменных:     *   - `fileName`: Имя файла.     *   - `key`: Ключ контента.     *   - `locale`: Язык контента.     *   - `extension`: Расширение файла.     *   - `componentFileName`: Имя файла компонента.     *   - `componentExtension`: Расширение файла компонента.     *   - `format`: Формат словаря.     *   - `componentFormat`: Формат словаря компонента.     *   - `componentDirPath`: Путь к каталогу компонента.     */    output: ({ fileName, extension }) => `./${fileName}${extension}`,    /**     * Указывает, должны ли компоненты сохраняться после трансформации.     * Таким образом, компилятор можно запустить только один раз для трансформации приложения, а затем удалить.     */    saveComponents: false,    /**     * Вставить только контент в сгенерированный файл. Полезно для JSON-вывода i18next или ICU MessageFormat для каждого языка.     *     * - `output: ({ locale, key }) => `./locale/${locale}/${key}.json`,`     */    noMetadata: false,    /**     * Префикс ключа словаря     */    dictionaryKeyPrefix: "", // Добавьте необязательный префикс для извлеченных ключей словаря  },};

Справочник по конфигурации компилятора

Следующие свойства могут быть настроены в блоке compiler вашего файла intlayer.config.ts:

• enabled:

  • Тип: boolean | 'build-only'
  • По умолчанию: true
  • Описание: Указывает, должен ли компилятор быть включен.

• dictionaryKeyPrefix:

  • Тип: string
  • По умолчанию: ''
  • Описание: Префикс для извлеченных ключей словаря.

• transformPattern:

  • Тип: string | string[]
  • По умолчанию: ['**/*.{js,ts,mjs,cjs,jsx,tsx,vue,svelte}', '!**/node_modules/**']
  • Описание: (Устарело: вместо этого используйте build.traversePattern) Шаблоны для обхода кода для оптимизации.

• excludePattern:

  • Тип: string | string[]
  • По умолчанию: ['**/node_modules/**']
  • Описание: (Устарело: вместо этого используйте build.traversePattern) Шаблоны для исключения из оптимизации.

• output:

  • Тип: FilePathPattern
  • По умолчанию: ({ key }) => 'compiler/${key}.content.json'
  • Описание: Определяет путь к выходным файлам. Заменяет outputDir. Поддерживает динамические переменные, такие как {{locale}}, {{key}}, {{fileName}}, {{extension}}, {{format}}, {{dirPath}}, {{componentFileName}}, {{componentExtension}}, и {{componentFormat}}. Может быть задано как строка в формате 'my/{{var}}/path' или как функция.
  • Примечание: Пути ./**/* разрешаются относительно компонента. Пути /**/* разрешаются относительно baseDir Intlayer.
  • Примечание: Если язык определен в пути, словари будут генерироваться для каждого языка.
  • Пример: output: ({ locale, key }) => 'compiler/${locale}/${key}.json'

• noMetadata:

  • Тип: boolean
  • По умолчанию: false
  • Описание: Указывает, должны ли метаданные сохраняться в файле. Если true, компилятор не будет сохранять метаданные словарей (ключ, оболочка содержимого). Полезно для вывода JSON i18next или ICU MessageFormat для каждой локали.
  • Примечание: Полезно при использовании с плагином loadJSON.
  • Пример: Если true: json { "key": "value" } Если false: json { "key": "value", "content": { "key": "value" } }

• saveComponents:

  • Тип: boolean
  • По умолчанию: false
  • Описание: Указывает, должны ли компоненты сохраняться после трансформации.

Заполнить недостающие переводы

Intlayer предоставляет инструмент CLI, который поможет вам заполнить недостающие переводы. Вы можете использовать команду intlayer для тестирования и заполнения недостающих переводов в вашем коде.

npx intlayer test         # Проверить наличие недостающих переводов

npx intlayer fill         # Заполнить недостающие переводы

Извлечение

Intlayer предоставляет инструмент CLI для извлечения контента из вашего кода. Вы можете использовать команду intlayer extract, чтобы извлечь контент из вашего кода.

npx intlayer extract

Для получения более подробной информации обратитесь к документации CLI