CSV для каждой локали

AI-перевод CSV-файлов с отдельными файлами для каждой локали с помощью Lingo.dev CLI

Что такое CSV для каждой локали?

CSV для каждой локали — это подход к переводу, при котором для каждой локали создаётся отдельный CSV-файл, а не все локали хранятся в одном CSV-файле с несколькими столбцами. Такой формат удобен, если у вас есть структурированные данные с несколькими столбцами (например, каталоги товаров, пользовательские данные или системы управления контентом), где каждая строка — это отдельная запись, а столбцы — разные поля.

Например:

id,name,description,created,enabled,sort
1,Welcome,Welcome to our application,2024-01-01,true,1
2,Save,Save your changes,2024-01-01,true,2
3,Error,An error occurred,2024-01-01,true,3

В отличие от стандартного CSV бакета, который хранит все локали в одном файле со столбцами вроде KEY,en,es, бакет csv-per-locale поддерживает отдельные файлы для каждой локали, сохраняя исходную структуру CSV со всеми столбцами.

Что такое Lingo.dev CLI?

Lingo.dev CLI — это бесплатный open-source CLI для перевода приложений и контента с помощью AI. Он создан, чтобы заменить традиционные системы управления переводами и легко интегрируется в существующие пайплайны.

Подробнее см. в разделе Обзор.

О данном руководстве

В этом руководстве объясняется, как переводить CSV-файлы с помощью бакета csv-per-locale и Lingo.dev CLI.

Вы узнаете, как:

  • Создать проект с нуля
  • Настроить пайплайн перевода с отдельными CSV-файлами для каждой локали
  • Генерировать переводы с помощью AI
  • Использовать заблокированные и игнорируемые ключи

Необходимые условия

Для работы с Lingo.dev CLI убедитесь, что установлен Node.js v18+:

❯ node -v
v22.17.0

Шаг 1. Настройка проекта

В директории вашего проекта создайте файл i18n.json:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {}
}

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

Чтобы узнать больше о доступных свойствах, смотрите i18n.json.

Шаг 2. Настройте исходную локаль

Исходная локаль — это оригинальный язык и регион, на которых был написан ваш контент. Чтобы настроить исходную локаль, укажите свойство locale.source в файле i18n.json:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {}
}

Исходная локаль должна быть указана в виде языкового тега BCP 47.

Полный список кодов локалей, поддерживаемых Lingo.dev CLI, смотрите в разделе Поддерживаемые коды локалей.

Шаг 3. Настройте целевые локали

Целевые локали — это языки и регионы, на которые вы хотите перевести свой контент. Чтобы настроить целевые локали, укажите свойство locale.targets в файле i18n.json:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {}
}

Шаг 4. Создайте исходный контент

Если вы ещё не сделали этого, создайте CSV-файл для вашей исходной локали. В файле должны быть:

  • Заголовочная строка с названиями столбцов
  • Одна или несколько строк с данными
  • Любые необходимые столбцы (названия столбцов не ограничены)

CSV-файл должен находиться по пути, который содержит исходную локаль (например, как имя директории en/ или как часть имени файла data.en.csv).

Примечание: В отличие от стандартного CSV bucket, вам не нужен столбец "KEY" или столбец, совпадающий с исходной локалью. Bucket csv-per-locale рассматривает каждую строку как отдельную запись и переводит весь текстовый контент в CSV, сохраняя структуру.

Шаг 5. Создайте bucket

  1. В файле i18n.json добавьте объект "csv-per-locale" в объект buckets:

    {
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "csv-per-locale": {}
  }
}

  2. В объекте "csv-per-locale" определите массив из одного или нескольких шаблонов include:

    {
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "csv-per-locale": {
      "include": ["./[locale]/example.csv"]
    }
  }
}

    Эти шаблоны определяют, какие файлы переводить.

    Сами шаблоны:

    • должны содержать [locale] как плейсхолдер для выбранной локали
    • могут указывать на пути к файлам (например, "[locale]/data.csv")
    • могут использовать звёздочки как плейсхолдеры-джокеры (например, "[locale]/*.csv")

    Рекурсивные glob-шаблоны (например, **/*.csv) не поддерживаются.

  3. При желании вы можете настроить lockedKeys и ignoredKeys:

    {
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "csv-per-locale": {
      "include": ["./[locale]/example.csv"],
      "lockedKeys": ["locked_key_1"],
      "ignoredKeys": ["ignored_key_1"]
    }
  }
}
    • lockedKeys: Ключи (значения в первом столбце, обычно это ID), которые не нужно переводить
    • ignoredKeys: Ключи, которые не должны появляться в файлах целевой локали

Шаг 6. Настройте LLM

Lingo.dev CLI использует большие языковые модели (LLM) для перевода контента с помощью ИИ. Чтобы использовать одну из этих моделей, вам нужен API-ключ от поддерживаемого провайдера.

Чтобы быстро начать работу, рекомендуем использовать Lingo.dev Engine — нашу собственную облачную платформу, которая предоставляет 10 000 бесплатных токенов в месяц:

  1. Зарегистрируйтесь в Lingo.dev.

  2. Выполните следующую команду:

    npx lingo.dev@latest login

    Откроется ваш браузер по умолчанию и появится запрос на авторизацию.

  3. Следуйте инструкциям.

Шаг 7. Сгенерируйте переводы

В каталоге, где находится файл i18n.json, выполните следующую команду:

npx lingo.dev@latest run

Эта команда:

  1. Читает файл i18n.json.
  2. Находит файлы, которые нужно перевести.
  3. Извлекает переводимый контент из CSV-файлов.
  4. Использует настроенную LLM для перевода извлечённого контента.
  5. Записывает переведённый контент обратно в отдельные CSV-файлы для каждой целевой локали.

При первом создании переводов создаётся файл i18n.lock. Этот файл отслеживает, какой контент уже переведён, чтобы избежать лишних повторных переводов при следующих запусках.

Пример

en/example.csv (до перевода)

id,name,description,created,enabled,sort
1,Welcome,Welcome to our application,2024-01-01,true,1
2,Save,Save your changes,2024-01-01,true,2
3,Error,An error occurred,2024-01-01,true,3
4,Success,Operation completed successfully,2024-01-01,true,4
5,Loading,Please wait while we load your data,2024-01-01,true,5

es/example.csv (после перевода)

id,name,description,created,enabled,sort
1,Bienvenida,Bienvenido a nuestra aplicación,2024-01-01,true,1
2,Guardar,Guarda tus cambios,2024-01-01,true,2
3,Error,Ha ocurrido un error,2024-01-01,true,3
4,Éxito,Operación completada con éxito,2024-01-01,true,4
5,Cargando,Por favor espera mientras cargamos tus datos,2024-01-01,true,5

i18n.json

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "csv-per-locale": {
      "include": ["./[locale]/example.csv"],
      "lockedKeys": ["locked_key_1"],
      "ignoredKeys": ["ignored_key_1"]
    }
  }
}

i18n.lock

version: 1
checksums:
  e8b273672f895de0944f0a2317670d7c:
    0/name: 1308168cca4fa5d8d7a0cf24e55e93fc
    0/description: 8de4bc8832b11b380bc4cbcedc16e48b
    1/name: f7a2929f33bc420195e59ac5a8bcd454
    1/description: 8de4bc8832b11b380bc4cbcedc16e48b
    2/name: d3d99b147cc363dc6db8a48e8a13d4c1
    2/description: 7cd986af1fe5e89abe7ecffba5413110

Отличия от CSV bucket

Bucket csv-per-locale отличается от стандартного bucket csv по нескольким параметрам:

  • Структура файлов: csv-per-locale использует отдельные файлы для каждой локали (например, en/example.csv, es/example.csv), а csv — один файл с несколькими колонками (например, KEY,en,es).

  • Требования к колонкам: csv-per-locale не требует колонки "KEY" или колонок с названиями локалей. Можно использовать любую структуру колонок, подходящую для ваших данных.

  • Сценарии использования: csv-per-locale отлично подходит для структурированных данных, например, товарных каталогов, CMS или баз данных, где каждая строка — это запись с несколькими полями. Стандартный bucket csv больше подходит для простых таблиц переводов ключ-значение.

  • Изменения файлов: Оба bucket изменяют файлы напрямую, но csv-per-locale создаёт отдельные файлы для каждой локали, а csv добавляет новые колонки в существующий файл.