Using Google Sheets to localize your app
Tags: ios, android, mobile, tutorial
Published: 2023-01-24 10:39:54

If you're building a mobile app, chances are that you need to manage translations for multiple languages. There are many paid platforms that you can use to do this, but in this post I want to show you a free open source alternative: [Localeasy](https://github.com/wvteijlingen/localeasy).

With [Localeasy](https://github.com/wvteijlingen/localeasy) you can use Google Sheets to store and manage your app translations. This has many benefits such as easy user management, change tracking, comments, no limits on contributors, and best of all: it's free of charge!

In this post I will show you how you to integrate Localeasy with your project. For this example we will use two languages: English and Dutch.

## Creating a Google sheet

The first step is to create a new Google Sheet which will contain all translations in all the languages that you support. So let's hop over to sheets.google.com and create a new spreadsheet.  I won't go into the details of how to create the sheet, but it should look something like this:

| key | en | nl | comment |
|-----|----|----|---------|
| welcome_title | Hello world! | Hallo wereld! | copy for welcome screen |
| welcome_button | Continue | Volgende | copy for button on welcome screen |

- The `key` column will hold the key of the translation.
- The `en` and `nl` columns will hold the English and Dutch translations respectively.
- The `comment` column can be used to add an optional comment to the row.

Make sure you create a public sharing link for the sheet, so that Localeasy can access it. (If you don't want to do this, you can also use OAuth to give access to specific users, but it requires a bit more setup)

## Installing the Localeasy CLI

Use homebrew to install the Localeasy CLI.
```bash
> brew install wvteijlingen/tap/localeasy
```

## Integrating Localeasy with your codebase

One the CLI is installed, navigate to your project directory and run `localeasy init` to create a project configuration json file.

```bash
> cd ~/my-project
> localeasy init
```

This command creates a `localeasy.json` configuration file in your project directory. This file contains two keys that need to be configured:

- `sheet`: The URL of the Google Sheet that contains the translations. Copy and paste the URL of your sheet from your browser into this property.
- `locales`: An object containing all languages that you want to support. Every key under `locales` must match a column in your Google Sheet. Every value is an output path for the translations in that language.

In our example with two languages, the configuration file would look like this:

```jsonc
{
  "sheet": "https://docs.google.com/spreadsheets/d/123/edit#gid=456",
  "locales": {
    // For iOS
    "en": "Supporting Files/Shared/en.lproj/Localizable.strings",
    "nl": "Supporting Files/Shared/nl.lproj/Localizable.strings"
    
    // For Android
    "en": "app/src/main/res/values/strings.xml",
    "nl": "app/src/main/res/values-nl/strings.xml"
  }
}
```

## Pulling translations

Now that the sheet and the `localeasy.json` file are set up, we can download the translations. To do this you can use the `localeasy pull` command. Make sure you run this in the directory that contains the `localeasy.json` file.

```bash
> cd ~/my-project
> localeasy pull
```

## That's it!

The process of managing your translations is now much easier. Just make a change to the Google sheet, run `localeasy pull` in your local working copy, and Localeasy will take care of the rest!