CSV

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

В CSV-таблице переводов исходный текст и все переводы хранятся в одном файле: одна строка на сообщение, один столбец на локаль. Обработчик файлов csv заполняет ячейки целевых локалей и записывает результат по исходному пути. Он меняет только ячейки целевых локалей и добавляет столбец, если у локали его нет. Подробнее — в разделе Какие строки переводятся. Остальные столбцы, порядок строк, кавычки и окончания строк остаются без изменений. Метка порядка байтов UTF-8 в начале файла не сохраняется: результат записывается без неё. Если табличный редактор определяет UTF-8 по этой метке, может потребоваться импортировать файл с явным указанием UTF-8.

Как устроить таблицу #

Заголовком считается первая строка, которая не пуста и содержит не только пробельные символы. В одном столбце хранится ключ, который определяет каждую строку, в другом — исходный текст. У каждой целевой локали свой столбец:

csv
id,en,notes,de
checkout.title,Complete your order,Shown on the last step,Bestellung abschließen
checkout.pay,"Pay now, or later",,
  • Столбцы локалей. Столбец относится к локали, если его заголовок совпадает с кодом локали без учёта регистра: de и DE обозначают столбец немецкого языка, а de-DE — другую локаль. Заголовок столбца исходного текста — это sourceLocale из вашей конфигурации.
  • Столбец ключей. По умолчанию имя столбца ключей указано в первой ячейке заголовка. Чтобы использовать другой столбец, задайте keyColumn в записи файла. Если ключом служит исходный текст, столбец исходного текста может одновременно быть столбцом ключей.
  • Остальные столбцы. Столбцы, которые не содержат ключей и не относятся к локалям, например notes, сохраняются байт в байт и никогда не отправляются на перевод.
  • Синтаксис. Ячейки разделяются запятыми. Ячейка с запятой, кавычкой или переносом строки заключается в двойные кавычки. Кавычка внутри неё записывается дважды (""). Файлы с разделителями в виде точки с запятой или табуляции не поддерживаются.

Как настроить перевод CSV #

CSV-файл выбирается только записью в files, в которой шаблон заканчивается на .csv или задано "format": "csv". В первом случае формат определяется автоматически. Запись с "format": "csv" выбирает только файлы .csv. Общий шаблон, например data/**/*, без указания этого формата никогда не выбирает CSV-файлы. Так существующая запись не начнёт перезаписывать посторонние файлы данных. Регистр расширения имеет значение: файл с именем strings.CSV не переводится, поэтому переименуйте его в strings.csv.

json
{
  "sourceLocale": "en",
  "targetLocales": ["de", "fr"],
  "files": [{ "pattern": "i18n/strings.csv", "keyColumn": "id" }]
}

Для каждой локали результат записывается в тот же файл, поэтому targetPath для этого формата не допускается. Строки CSV не сопоставляются с настройками ключей, поэтому lockedKeys, preservedKeys и ignoredKeys тоже не допускаются. Одна и та же конфигурация работает в CLI и GitHub App.

Какие строки переводятся #

СтрокаРезультат
Есть ключ и исходный текстПереводится для локалей, ячейки которых пусты или содержат устаревший перевод.
Есть ключ, ячейка исходного текста пустаСохраняется как есть. Ячейки локалей не меняются.
Есть исходный текст, ячейка ключа пуста или содержит только пробелыСохраняется как есть и не переводится. Чтобы перевести строку, задайте ей ключ.
Ключ и исходный текст пусты либо строка пустаяСохраняется как есть, в том числе если строка содержит только пробелы.

Ячейка локали, содержащая только пробелы, считается пустой. Заполненная ячейка используется повторно, если исходный текст строки не изменился с последнего push. Если исходный текст строки меняется, все ячейки локалей в ней переводятся заново. У строки, добавленной после последнего push, заполненные ячейки сохраняются, а переводятся только пустые. Строка с изменённым ключом считается новой. Заполненные ячейки также сохраняются при первом push файла, при использовании --force в CLI и при выполнении команды GitHub App, в которой указаны файлы без --force. То же правило действует, если в ранее отправленном файле нет единственного столбца исходного текста или столбца ключей для сравнения, например после переименования одного из них. Команда GitHub App с --force заново переводит каждую строку файла.

Без перевода копируется текст, состоящий только из цифр ASCII от 0 до 9, например 100. То же правило действует для URL, который начинается с // или содержит схему из букв, цифр или знаков подчёркивания, за которой следует ://, а после // — адрес, который начинается с localhost или содержит хотя бы один символ, точку и ещё не менее двух символов, например https://lingo.dev/docs. Также без перевода копируются ИД из 22 символов, состоящий только из букв и цифр и содержащий хотя бы одну прописную букву, одну строчную букву и одну цифру, а также дата или дата и время в формате ISO 8601, например 2024-01-15 или 2024-01-15T10:00:00Z. Исходный текст заменяет содержимое всех ячеек целевых локалей в той же строке. Строка не отправляется на перевод, и плата за неё не взимается. Другие значения переводятся: например, 1.5, 100%, адрес почты или дата в другом формате, например 15.01.2024. Также переводятся ссылки mailto: и tel:, URL с другими символами в схеме, например git+ssh://, и URL, адрес которых не начинается с localhost и не содержит точки, соответствующей этим условиям, например https://intranet или https://a.b.

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

Ошибки #

В следующих случаях обработка файла завершается с ошибкой ещё до начала перевода и начисления платы, а причина указывается в сообщении:

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

Исправьте файл и повторите push. CLI выводит сообщение один раз под именем файла, а не для каждой локали. Если весь запуск завершается с ошибкой, сообщение повторяется в итоговой строке Run failed:. GitHub App показывает его в результатах проверки.

Как исправить существующий перевод #

Чтобы изменить конкретную формулировку, отредактируйте ячейку. Чтобы заново получить один перевод, очистите эту ячейку, оставьте остальную строку без изменений и выполните обычный push:

sh
lingo push --wait

Команда --force в CLI повторно использует заполненные ячейки, как и для каталогов строк Apple. --key не ограничивает область обработки CSV-файла: CLI останавливает push с ошибкой, а GitHub App пропускает файл. Команда purge в CLI пропускает файл, потому что исходный файл и результат находятся по одному пути. Перед коммитом проверьте все изменения в файле.