Main menu

Importing spreadsheets

Spreadsheets can be imported as comma separated values

CSV files can have many different structures, so for Loco to understand them they should take a specific form.

  • Translation columns must have a valid locale code header (optionally after a label)
  • The ID column must be called "Asset ID" (because "id" is the code for Indonesian)
  • Fields under the heading "notes" or "description" will import as asset notes
  • Fields under the heading "context" will import as asset context
  • Fields are expected to be comma-separated by default. (See csv-separator)

Example CSV structure

The following structure is how Loco exports CSV files, hence it accepts the same exact format for import:

Asset ID English, en French, fr Spanish, es Notes
hello Hello world Bonjour tout le monde Hola mundo This is a welcome message
goodbye So long! Au revoir Adiós This is a parting message

The table shown is formatted for legibility. The raw CSV source of your file would look like this:

Asset ID,"English, en","French, fr","Spanish, es",Notes
hello,Hello world,Bonjour tout le monde,Hola mundo,This is a welcome message
goodbye,So long!,Au revoir,Adiós,This is a parting message

Double quotes are only required around cell values when they contain a separator character (comma) or a double quote (which must be escaped). However, you may find it simpler to just quote all values like Loco's CSV export does.

The presence of the "Asset ID" column ensures your translations are mapped to language agnostic IDs instead of the source text. e.g. { hello => Hello world } (English) and { hello => Hola mundo } (Spanish) are both mapped to the ID "hello".

The full names of the languages are included for human-readability and are actually ignored by Loco's CSV parser. This example would work just the same with column headers simply as "en", "fr" and "es".

Asset aliases

CSV files can import or update asset aliases that you've defined in your project settings. Loco exports them after the locale columns to avoid breaking backward compatibility, but you can put them in any order as long as they come after the Asset ID. Column headers must use the short name of the alias (not the descriptive label). For example:

Asset ID myCustomID English, en
hello HelloWorld Hello world!

Be warned that (as with Loco's own ID column) asset aliases should not be named such that they are also valid locale codes.

Comment lines

Loco's CSV importer ignores rows beginning with a ' (single quote) that come before the column headers. You'll notice such lines as comments in CSV files exported from Loco, for example:

"'Exported by: Admin"
"'Exported at: Mon, 11 Nov 2019 10:48:12 +0000"
"Asset ID","English, en"
...

Comment rows may be quoted as shown, but are not permitted after the headers.

Importing glossary pairs

Loco's CSV parser will accept simple key/value pairs in files without a header row. For example:

Hello world,Bonjour tout le monde
So long,Au revoir

- or with ID indexing you could import a single language, as follows:

hello,Hello world
goodbye,So long

This works for files with exactly two columns, whose first row cannot be mistaken for a valid header row containing locale codes.

Tab separated values

Loco's CSV importer also accepts tab-separated files. When uploading, name the file with a .tsv extension, or post to the /api/import/tsv endpoint if using the Import API.

Troubleshooting CSV imports

If Loco responds with an error like "Invalid CSV structure" then it's likely your file is not prepared as expected. Here are a few things to check:

  • Does your structure look like our example?
    The Loco CSV importer expects assets in rows with translations in distinct columns. Any other layout will produce unexpected results.

  • Is it comma separated?
    Other field separators (such as semicolons or tabs) aren't detected automatically and will result in lines being split into columns incorrectly. Via the Import API you can specify csv-separator as per the corresponding export option.

  • Does it have correct column headers?
    Check your CSV file has column headers like our example and the data in each column is correctly aligned with them. Be warned that "ID" is the language code for Indonesian, so make sure you enter "Asset ID" as shown.

  • Is it UTF-8 encoded?
    Loco expects your file to be UTF-8 encoded, so check that your spreadsheet or text editing software is producing the correct encoding. File editing outside Loco is a common cause of wrongly encoded imports. Make sure any scripts handling API data are Unicode safe.

  • Are values quoted/escaped?
    Field values that contain a literal comma must be quoted, and literal quotes in fields must be double quoted. e.g. Two columns with raw values foo,bar and "baz" would be escaped as: "foo,bar","""baz"""

You should always be able to re-import a CSV file that was exported from Loco. Before reporting a bug, please check you haven't modified your file with other software, or corrupted its encoding by accident.

Last updated by