CSV

Translate a CSV table that keeps every locale in its own column of one file, keyed by a column you choose.

A CSV translation table keeps the source text and every translation in one file: one row per message, one column per locale. The csv file handler fills the target-locale cells of that file and writes the result back to the source path. It writes only the target-locale cells, and adds a column when a locale has none, as Which rows are translated describes. Other columns, row order, quoting and line endings stay as they were. A UTF-8 byte order mark at the start of the file is not kept: the written file starts without one, so a spreadsheet app that relies on the mark to detect UTF-8 may need the file imported as UTF-8.

Lay out the table #

The first line that is not blank or whitespace-only is the header. One column holds a key that identifies each row, one column holds the source text, and each target locale has its own column:

csv
id,en,notes,de
checkout.title,Complete your order,Shown on the last step,Bestellung abschließen
checkout.pay,"Pay now, or later",,
  • Locale columns. A column belongs to a locale when its header is the locale code, matched without regard to case: de and DE are the German column, but de-DE is a different locale. The source column's header is the sourceLocale from your configuration.
  • Key column. By default, the first header cell names the key column. Set keyColumn in the file's entry to use another column. The key column can be the source column itself, when the source text is the key.
  • Other columns. Columns that are neither the key nor a locale, such as notes, are kept byte for byte and never sent for translation.
  • Syntax. Cells are separated by commas. A cell that contains a comma, a quote or a line break is enclosed in double quotes, and a quote inside it is written twice (""). Semicolon- or tab-separated files are not supported.

Configure CSV translation #

A CSV file belongs only to a files entry whose pattern ends in .csv, where the format is inferred, or that sets "format": "csv", and an entry with "format": "csv" selects only .csv files. A broad pattern such as data/**/* without that format never selects a CSV file, so an existing entry does not start rewriting unrelated data files. The extension is case-sensitive: a file named strings.CSV is not translated, so rename it to strings.csv.

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

The file is its own target for every locale, so targetPath is rejected for this format. CSV rows are not matched against key controls, so lockedKeys, preservedKeys and ignoredKeys are rejected too. The same configuration works in the CLI and the GitHub App.

Which rows are translated #

RowResult
Key and source textTranslated where its locale cell is empty or out of date.
Key, empty source cellKept as it is; its locale cells are not changed.
Source text, key cell empty or only spacesKept as it is and not translated. Give it a key to translate it.
Empty key and empty source, or a blank lineKept as it is, including a line of only spaces.

A locale cell that holds only spaces counts as empty. A filled cell is reused while its row's source text is unchanged since the last push. When the source text of a row changes, every locale cell of that row is translated again. A row added since the last push keeps its filled cells, and only its empty cells are translated; a row whose key changed counts as added. Filled cells are also kept on the first push of the file, with CLI --force, on a GitHub App command that names files without --force, and when the previously pushed file has no single source or key column to compare against, for example after one of them was renamed. A GitHub App command with --force translates every row of the file again.

Some source text is copied instead of translated: only the ASCII digits 0 to 9, such as 100; a URL that starts with // or with a scheme made of letters, digits or underscores followed by ://, when the address after // starts with localhost or has at least one character, a dot and at least two more characters, such as https://lingo.dev/docs; a 22-character ID made only of letters and digits, with at least one upper-case letter, one lower-case letter and one digit; and an ISO 8601 date or date and time, such as 2024-01-15 or 2024-01-15T10:00:00Z. The source text is written into every target-locale cell of its row, replacing what the cell held, and the row is not sent for translation or billed. Other values, such as 1.5, 100%, an email address or a date in another form, such as 15.01.2024, are translated. So are mailto: and tel: links, URLs whose scheme has other characters, such as git+ssh://, and URLs whose address does not start with localhost and has no such dot, such as https://intranet or https://a.b.

When a target locale has no column, the column is added at the end of the header. Several new columns are added in alphabetical order of their locale codes. Every row is then padded with empty cells so the table stays rectangular. Rows are never reordered, added or removed.

Errors #

The file fails before anything is translated or billed, and the message names the problem, when:

  • the configured keyColumn is not in the header, or the first header cell is empty and no keyColumn is set;
  • two rows have the same key, because their translations would land in the wrong rows;
  • the header has no column for the source locale;
  • the key column is also a target locale's column;
  • the header names the configured keyColumn, the source locale or a target locale more than once;
  • a row has more cells than the header;
  • a quoted cell is never closed;
  • text follows a closing quote in the same cell.

Fix the file and push again. The CLI lists the message once under the file, not once per locale, and when the whole run fails, the closing Run failed: line repeats it. The GitHub App shows it in the check run.

Correct an existing translation #

For an exact wording change, edit the cell. To regenerate one translation, clear that cell, keep the rest of the row, and run a plain push:

sh
lingo push --wait

CLI --force reuses filled cells, as it does for Apple String Catalogs. --key does not narrow a CSV file: the CLI stops the push with an error, and the GitHub App skips the file. CLI purge skips the file because its source and output share a path. Review the whole file diff before committing it.