Sheetspeare NPM

Sheetspeare - Google Spreadsheet Translation Loader CLI

Sheetspeare is a powerful CLI tool that allows you to manage translations for your application using Google Spreadsheets. It simplifies the process of loading translation files from a Google Spreadsheet and keeping them in sync with your codebase. Say goodbye to manual copy-pasting and tedious translation management!

Installation

Install the package using npm:

npm install --save-dev sheetspeare

Setup

To start using Sheetspeare, follow these steps:

Setup a Google project:

Go to the Google Developers Console
Select your project or create a new one (and then select it)
Enable the Sheets API for your project
In the sidebar on the left, select Enabled APIs & Services
Click the blue "Enable APIs and Services" button in the top bar
Search for "sheets"
Click on "Google Sheets API"
click the blue "Enable" button

Create a Google Service Account:

In the sidebar on the left, select APIs & Services > Credentials
Click blue "+ CREATE CREDENTIALS" and select "Service account" option
Enter name, description, click "CREATE"
You can skip permissions, click "CONTINUE"
Click "+ CREATE KEY" button
Select the "JSON" key type option
Click "Create" button
your JSON key file is generated and downloaded to your machine (it is the only copy!) Keep it in a safe place. we will use it the following steps.
click "DONE"
note your service account's email address (also available in the JSON key file)

For more details on how to setup the Google Service Account and Project visit the authentication section of the google-spreadsheet package documentation

Create a Google Spreadsheet:

Create a new Google Spreadsheet and share it with your service account using the email noted above. Note the Google Spreadsheet id from the URL https://docs.google.com/spreadsheets/d/{spreadsheetId}/edit.... It is needed in the following steps.

Setup Environment Variables:

From the downloaded JSON key file, set the following environment variables:

SERVICE_ACCOUNT_EMAIL="client_email" SERVICE_ACCOUNT_PRIVATE_KEY="private_key"

Or add them to your dotenv file:

# .env
SERVICE_ACCOUNT_EMAIL="client_email"
SERVICE_ACCOUNT_PRIVATE_KEY="private_key"

Initialize the project:

Run the following command to initialize the project:

npx sheetspeare init

A .sheetspearerc.json config file will be added which stores the configuration for the project.

Usage

The Sheetspeare CLI offers the following commands:

init: Initialize the Google Spreadsheet connection and create a configuration file.
pull: Pull translations from the Google Spreadsheet and update the locale files in your project.
push: Push updated translations from your project's locale files back to the Google Spreadsheet.
help: Show the help menu and available commands.

Configuration

After running the init command, Sheetspeare will create a configuration file named .sheetspearerc.json in your project's root directory. You can manually edit this file if you need to change the default settings.

{
  "locales": ["en", "es", ...],
  "spreadsheetId": "...",
  "path": "src/locales"
}

spreadsheetId: The ID of the Google Spreadsheet containing the translations.
path: The path to the directory containing the locale files.
locales: An array of locale codes to pull from the Google Spreadsheet. The locale files under the path directory will be named using these locale codes.

Note: This CLI is supports cosmiconfig config formats. You may move the configuration to other supported formats such as .sheetspearerc.js or even to your package.json file under sheetspeare property and it will be loaded automatically.

Contributing

We welcome contributions to Sheetspeare! If you find any bugs, have suggestions for improvements, or want to add new features, feel free to open an issue or submit a pull request on GitHub: GitHub Repository