What you’ll need #️⃣

This guide uses Microsoft Excel files in XLS or XLSX format (format specification).

  • A spreadsheet with one string per row on the first sheet. Localazy ignores all other sheets.
  • A header row. Localazy reads the first row as a header by default.
  • Localazy CLI installed

Set up the Localazy configuration file #️⃣

Localazy does not store formatting, number formats, or formulas. It reads the cell text only. Before you upload, tell the CLI which column holds the key, which columns hold the text, and which columns to skip. You do this with the columns feature.

Type Meaning
key The key. Required, one column.
key:1, key:2 A key split across two columns.
content The text to translate. Required. One column for single-language files, many columns for multilingual files.
comment A note for the translator. Optional, one column.
- Skip this column.

The CLI reads the column types from left to right. The default is columns=key,content.

Single-language file #️⃣

One file holds one language. The CLI takes the language from your Localazy project settings, not from the header text.

Example sheet (translations/en.xlsx):

key comment line en
dashboard.title Shown on the home screen 12 Welcome back
dashboard.cta Button label 14 Start a project

Create a localazy.json file in your project root:

{
  "writeKey": "your-write-key",
  "readKey": "your-read-key",
  "upload": {
    "type": "excel",
    "files": "translations/en.xlsx",
    "features": ["columns=key,comment,-,content"]
  },
  "download": {
    "files": "translations/${lang}.xlsx"
  }
}

The CLI reads column A as the key, column B as the comment, skips column C, and reads column D as the English text. Downloaded files have two columns: key and the language code.

Multilingual file #️⃣

One file holds all languages, one column per language. The header cell of each content column must contain a language code. The CLI takes the language from the header, not from the project settings.

Example sheet (translations/strings.xlsx):

key en de fr comment
dashboard.title Welcome back Shown on the home screen
dashboard.cta Start a project Button label 
{
  "writeKey": "your-write-key",
  "readKey": "your-read-key",
  "upload": {
    "type": "excel",
    "files": "translations/strings.xlsx",
    "features": ["multilingual", "columns=key,content,comment"]
  },
  "download": {
    "files": "translations/${file}"
  }
}

With multilingual, content covers every column between key and comment. Here that is columns B to D, read as English, German, and French. Empty target cells upload as untranslated.

Upload source files #️⃣

localazy upload

The CLI reads the spreadsheet with the column mapping from localazy.json and uploads the strings to your Localazy project.

Download translated files #️⃣

localazy download

The CLI downloads the translations and writes them to the path in the download section. The output keeps the XLS or XLSX format of the input file.

Next steps #️⃣

  • Translate the strings in Localazy, then run localazy download again.
  • Downloaded files contain the key column and one column per language. Column order, comments, skipped columns, and cell formatting from the input file are not kept.
  • If the first column is both the key and the source text, add source_is_key to features.
  • If your file has no header row, add no_header to features. Multilingual files always need a header.
  • To change how language codes appear in the output header, add lang_format=locale_name (or another format) to features. See the Excel format documentation for the list.
  • Plurals: use key suffixes such as key[one] and key[other] with plural_postfix_br, or ICU syntax in one cell with plural_icu. See plurals in the Excel format.
  • Arrays: use key[0], key[1] with array_br.
  • Contact us at team@localazy.com if you have trouble integrating.