Бакеты

Введение

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

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

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

Типы bucket'ов

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

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

Режим вывода

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

Причина этой разницы в поведении заключается в том, что каждый вариант имеет смысл в зависимости от bucket'а. Нет единого правильного варианта, который подошёл бы для всех типов bucket'ов.

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

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

С другой стороны, при использовании bucket'а Markdown локализованный контент выводится в отдельные файлы, так как не принято хранить все локализованные варианты в одном файле.

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

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

Создание бакетов

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

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

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

Свойство buckets должно содержать как минимум одну корректную запись.

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

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

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

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

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

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

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

Заполнитель `[locale]`

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

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

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

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

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

Позиция заполнителя [locale] не имеет значения, поэтому все эти шаблоны являются корректными:

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

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

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

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

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

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

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

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

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

Особенности, специфичные для бакетов

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

Особенности, специфичные для бакетов, включают:

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