@sheet-i18n/cli ✨

A CLI tool for efficient translation management using Google Sheets, with a focus on developer experience (DX).

Features

• ✨ Initialize CLI configuration for translation workflows.
• 👀 Watch files or directories for changes.
• 📤 Register translation data to Google Sheets.
• 🛠️ Built with TypeScript for type safety.

Core Concepts 🌟

😭 General Translation Workflow

The traditional process of managing translations with Google Spreadsheets often includes these steps:

1. Translator identifies the text to be translated from the page (without developer involvement).
2. Translator adds the translation data to a Google Spreadsheet.
3. Developer creates a script to locally download the translation data from the sheet.
4. Developer inspects the translation data, matches it with the code, and finds the corresponding values in the source code (this can be time-consuming).
5. If discrepancies exist between the spreadsheet and the code, developers request changes from the translator.
6. Once resolved, the developer applies the translations using an internationalization (intl) library.
7. For additional translations, developers manually import and apply them in the code.
8. Results are checked on the page, and any errors prompt a repeat of the cycle.

This process is lengthy and redundant. Translators often lack visibility into how text is structured in code, especially when developers split strings, need to insert variables on the text, or add line breaks (<br/>). As a result, the translation burden falls back to the developers.

☺️ Developer-Centric Translation Workflow

This CLI streamlines the process by shifting the focus to developers:

1. Developers identify and mark variables or text for translation directly in the code.
2. Run the CLI to register changes (it automatically adds translations using Google Translate with support for Google Spreadsheets).
3. Translators inspect and refine the translations for improved fluency and meaning on the Google Sheet.
4. Developers import the confirmed translation data, completing the process.

With this approach, unnecessary back-and-forth is eliminated, and translations align seamlessly with code.

🚀 Initial Setup with CLI

@sheet-i18n/cli provides a fully automated setup for React applications.
Once installed, you can bootstrap the required i18n context, store, and folder structure by simply running:

npx sheet-i18n init

This will automatically generate:

• A preconfigured i18nStore using @sheet-i18n/react
• A ready-to-use i18nContext.ts that exports IntlProvider, useTranslation, and getTranslation
• Example locale JSON files (e.g., en.json, ko.json)
• The sheet.config.json file for managing your CLI behavior and Google Sheets credentials

💡 All files will be created in the recommended structure (e.g. src/i18n, src/locales), and safely skipped if they already exist.

---

✅ What You No Longer Have to Do Manually

• You don’t need to manually initiate I18nStore or set up the React context.
• You don’t need to manually prepare locale JSON templates.
• You don’t need to manually configure sheet.config.json.

Just run the init command and you’re ready to use useTranslation() in your components.

---

🗂️ Example Output:

📦 your-project/
├── 📄 .gitignore                      # Automatically appends 'sheet.config.json' to ignore list
├── 📄 sheet.config.json              # CLI configuration file (contains Google Sheet credentials & options)
└── 📁 src/
    └── 📁 i18n/
        ├── 📄 i18nContext.tsx        # React context for IntlProvider, useTranslation, and getTranslation
        ├── 📄 i18nStore.ts           # Initializes I18nStore with supported locales and translation data
        ├── 📄 en.json                # Placeholder for English translation strings
        └── 📄 ko.json                # Placeholder for Korean translation strings

✅ The CLI automatically creates this structure after running npx sheet-i18n init.
🛡️ If sheet.config.json or src/i18n already exist, the CLI will skip the creation of these files.

after running npx sheet-i18n init, you can mount the IntlProvider in your app.

Mount Intl Context Provider in your App

import React from 'react';
import I18nContextProvider from './i18n/i18nContext';

const App = () => {
  const [locale, setLocale] = useState('en');

  return (
    <I18nContextProvider currentLocale={locale}>
      <YourComponent />
    </I18nContextProvider>
  );
};

Use Translations

// YourComponent.tsx
import React from 'react';
import { useTranslation } from './i18n/i18nContext';

const YourComponent = () => {
  const { t } = useTranslation('header');

  return (
    <div>
      <button>{t('login')}</button>
      <button>{t('logout')}</button>
    </div>
  );
};

That's it!

your translations are now ready to use in your application.

⚙️ sheet.config.json

The CLI requires a sheet.config.json file in the root of your project. Run sheet-i18n init to generate this file automatically.

Example sheet.config.json:

{
  "watchEntry": "src",
  "detectExtensions": ["tsx", "ts", "jsx", "js"],

  "googleSheetConfig": {
    "credentials": {
      "sheetId": "YOUR_GOOGLE_SHEET_ID",
      "clientEmail": "YOUR_CLIENT_EMAIL",
      "privateKey": "YOUR_PRIVATE_KEY"
    },
    "defaultLocale": "en",
    "supportedLocales": ["en", "fr", "es"],
    "ignoredSheets": ["BASE"],
    "importPath": "./src/locales"
  }
}

1. File change monitoring configuration

Option	Type	Required	Description
watchEntry	string		Entry path to monitor file changes, relative to the current working directory. Default: "src".
detectExtensions	string[]		List of file extensions to watch. Default: ["jsx", "js", "tsx", "ts"].

2. Register command configuration

📄 googleSheetConfig Options

Option	Type	Required	Description
credentials.sheetId	string	✅	The same ID as spreadsheetId (for API auth).
credentials.clientEmail	string	✅	Client email from your Google Service Account credentials.
credentials.privateKey	string	✅	Private key from your Google Service Account credentials.
defaultLocale	string	✅	The default language/locale used in the sheet's header row.
supportedLocales	string[]	✅	Array of all supported locale codes (e.g., ["en", "ko"]). Default is [defaultLocale].
headerStartRowNumber	number		Row number where sheet headers begin. Default: 1.
ignoredSheets	string[]		Titles of sheets to ignore during register/import (e.g., ["BASE"]).
importPath	string		Directory path to export translation JSON files. Default is current working directory.

Commands

🎬 init

npx sheet-i18n init

Sets up the sheet.config.json file in your project. This configuration file is required for all other commands.

👀 watch

npx sheet-i18n watch

Monitors files or directories for changes and logs relevant updates. When watch mode is started, the CLI will detect changes of "useTranslation" and "t" calls of "@sheet-i18n/react" package.

//translationContext.tsx
import { createI18nContext } from 'sheet-i18n/react';

export const { IntlProvider, useTranslation } = createI18nContext(i18nStore);


// Component.tsx
import { useTranslation } from '../translationContext'

...

function Component (){
  // The arguments of useTranslation function = sheetTitle
  const { t } = useTranslation('environment');
  ...

  // The arguments of t function = translation key
  return (
      <>
          <SettingItem label={t('over')}>
          <SettingItem label={t('under')}>
      </>
  )
}

The watched result is

Detected Translations:

📄 [Sheet Title]: environment
 - over
 - under

# You can proceed using the shortcuts below:
 - Press <Shift + R> to register the detected changes.
 - Press <Ctrl + C> to cancel the watch command.

📤 register

npx sheet-i18n register [options]

Registers translation data to Google Sheets.

Remarkable features:

1. The register command collects the current sheets in Google Spreadsheets. If there are sheets in your local changes that do not exist in the current list, it prompts you to create the missing sheets.

2. It updates rows and adds "translation" entries using the GOOGLETRANSLATE function supported by Google Spreadsheets for automated translations.

3. After registering, it asks whether you want to update the locale JSON data locally. It then exports the JSON data to the importPath specified in sheet.config.json (default is the current working directory).

Options:

• -s, --scope <scope>
  Define the scope of the registration process:

  • diff: Only scans translation keys that have been modified in the Git history (based on git diff).
  • total: Scans the entire directory for all translation keys and updates the spreadsheet, regardless of Git changes.
  • select: User selection mode which allows you to choose the sheets to register.

• Default: diff

---

📄 Detailed description of the scope option:

Scope: diff

• The CLI identifies changes in translation keys by comparing the current state of the codebase with the latest Git commit.
• It only processes translation keys added, removed, or modified since the last commit.
• This is useful for incremental updates, ensuring only new or updated keys are registered.

Example:

# diff is the default scope. So you can omit the --scope option.
npx sheet-i18n register

Scope: total

• The CLI scans the entire specified directory for all translation keys from the directory path you provide.
• This is useful for full synchronization, ensuring all keys are registered in the spreadsheet.
• However, it may take longer to process large directories. So, use with caution.

Example:

npx sheet-i18n register --scope total

Scope: select

• The CLI prompts you to manually select which sheets you want to update.

• Once the selection is made, only the chosen sheets will have their translation data updated in the Google Spreadsheet.

• This mode is especially useful for partial updates, allowing you to skip scanning the entire directory and focus on specific sheets.

• It’s also helpful in cases where you’ve committed changes without registering translation data during development — instead of syncing all translations, you can update only the relevant sheets as needed.

Example:

npx sheet-i18n register --scope select

📄 import

npx sheet-i18n import

Exports translation data from Google Sheets to local export directory. The configuration of export command is based on sheet.config.json on your root.

{
  "googleSheetConfig": {
    "credentials": {
      "sheetId": "YOUR_GOOGLE_SHEET_ID",
      "clientEmail": "YOUR_CLIENT_EMAIL",
      "privateKey": "YOUR_PRIVATE_KEY"
    },
    "defaultLocale": "The base language of your application in sheet header",
    "ignoredSheets": ["BASE"],
    "importPath": "The path of export directory of translation data. (default: current working directory)"
  }
}