Бакеты

Настройка бакетов в Lingo.dev CLI

Введение

В файле i18n.json свойство buckets определяет:

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

Настройка бакетов — важный этап при создании пайплайна перевода с помощью Lingo.dev CLI.

Типы бакетов

Lingo.dev CLI поддерживает широкий спектр стандартных форматов файлов (и некоторые нестандартные). Каждый из этих форматов связан с определённым типом бакета.

Типы бакетов обычно совпадают с форматами файлов, но это не всегда однозначное соответствие. Например, бакеты "json" и "json-dictionary" оба работают с локализуемым контентом в JSON-файлах, но CLI ожидает разную структуру файлов, поэтому бакеты считаются разными.

Режим вывода

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

Причина такого различия в том, что оба варианта наиболее логичны в зависимости от типа бакета. Нет универсального решения, подходящего для всех типов бакетов.

Например, при использовании бакета CSV файлы .csv изменяются напрямую. Это связано с тем, что обычно в CSV-файлах локализованный контент для каждой локали хранится в одном файле, в отдельных столбцах:

KEY,en,es
welcome_message,Welcome to our application,Bienvenido a nuestra aplicación

А при использовании бакета Markdown локализованный контент выводится в отдельные файлы, потому что не принято хранить все языковые версии в одном файле.

Это важно понимать по нескольким причинам:

  • Не сразу очевидно, что разные bucket'ы ведут себя по-разному.
  • Нужно по-разному задавать шаблоны include и exclude в зависимости от того, как выводятся файлы.

Создание bucket'ов

Чтобы создать bucket, добавьте запись в объект buckets в файле i18n.json:

{
  "buckets": {
    "json": {}
  }
}

Каждый ключ должен соответствовать одному из поддерживаемых типов bucket'ов, а значение должно быть объектом с валидной конфигурацией для этого bucket'а.

Свойство buckets должно содержать хотя бы одну валидную запись.

Включение файлов

Минимально bucket должен иметь свойство include, которое определяет контент для локализации:

{
  "buckets": {
    "json": {
      "include": []
    }
  }
}

Это свойство должно быть массивом строк.

Каждая строка может быть одной из следующих:

  • путь к файлу (например, "some/dir/labels.json")
  • glob-шаблон (например, "some/dir/*.json")

Эти значения всегда указываются относительно файла i18n.json.

Плейсхолдер [locale]

Когда bucket выводит локализованный контент в отдельные файлы (то есть не изменяет существующий файл), в шаблонах include обязательно должен быть специальный плейсхолдер [locale]:

{
  "buckets": {
    "json": {
      "include": ["[locale]/*.mdx"]
    }
  }
}

Этот плейсхолдер заменяется во время выполнения и влияет на то, где CLI:

  • ищет исходный контент
  • выводит локализованный контент

Например, если исходная локаль "en", а целевая локаль "es", то [locale]/*.mdx находит все MDX-файлы в директории en/ и выводит локализованные файлы в директорию es/.

Позиция плейсхолдера [locale] не важна, то есть все эти шаблоны валидны:

  • content/[locale]/*.mdx
  • [locale]/*.mdx
  • *.[locale].mdx

Рекурсивные glob-шаблоны

Lingo.dev CLI не поддерживает рекурсивные glob-шаблоны. Это значит, что шаблоны вроде "**/*.json" не работают. Если попытаться настроить рекурсивный glob-шаблон, возникнет ошибка.

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

В шаблонах include расширения файлов не имеют значения. Lingo.dev CLI попытается обработать любые указанные файлы в зависимости от типа bucket'а, независимо от расширения.

Исключение файлов

В дополнение к шаблонам include, bucket'ы также поддерживают шаблоны exclude для исключения путей к файлам или glob-шаблонов из локализации:

{
  "buckets": {
    "json": {
      "include": ["[locale]/*.mdx"],
      "exclude": ["[locale]/ignored/*.mdx"],
    }
  }
}

Эти шаблоны работают по тем же правилам, что и шаблоны include.

Особенности bucket'ов

У некоторых bucket'ов есть фичи, которых нет у других. Обычно это связано с тем, что эти фичи логичны только для определённых bucket'ов.

К особенностям bucket'ов относятся:

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