CSV
Переводите CSV-таблицу, где все локали хранятся в отдельных столбцах одного файла, а столбец ключей выбираете вы.
В CSV-таблице переводов исходный текст и все переводы хранятся в одном файле: одна строка на сообщение, один столбец на локаль. Обработчик файлов csv заполняет ячейки целевых локалей и записывает результат по исходному пути. Он меняет только ячейки целевых локалей и добавляет столбец, если у локали его нет. Подробнее — в разделе Какие строки переводятся. Остальные столбцы, порядок строк, кавычки и окончания строк остаются без изменений. Метка порядка байтов UTF-8 в начале файла не сохраняется: результат записывается без неё. Если табличный редактор определяет UTF-8 по этой метке, может потребоваться импортировать файл с явным указанием UTF-8.
Как устроить таблицу #
Заголовком считается первая строка, которая не пуста и содержит не только пробельные символы. В одном столбце хранится ключ, который определяет каждую строку, в другом — исходный текст. У каждой целевой локали свой столбец:
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.
{
"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:
lingo push --waitКоманда --force в CLI повторно использует заполненные ячейки, как и для каталогов строк Apple. --key не ограничивает область обработки CSV-файла: CLI останавливает push с ошибкой, а GitHub App пропускает файл. Команда purge в CLI пропускает файл, потому что исходный файл и результат находятся по одному пути. Перед коммитом проверьте все изменения в файле.