📊

Google Sheets Integration

Sync translations with Google Sheets for team collaboration

Overview

Google Sheets integration allows translators, planners, and developers to work on translations together. You can sync local JSON files and Google Sheets bi-directionally.

✓Real-time collaboration with teammates

✓Easy translation workflow for non-developers

✓Safe sync with incremental updates

✓Provides a force sync option

Initial Setup

Create Google Cloud Project

Google Cloud ConsoleGo to
Create a new project or select an existing one

Enable Google Sheets API

Go to 'APIs & Services' > 'Library'
Search "Google Sheets API"
Click 'Enable'

Create Service Account

Go to 'APIs & Services' > 'Credentials'
Create credentials > Select 'Service account'
Enter service account name (e.g., i18n-sync)
Role: Select 'Editor'
Click 'Done'

Download credentials JSON

Click the service account you created
Go to the 'Keys' tab
Add key > Create new key
Select JSON type
Save the downloaded JSON file to the project root (e.g., credentials.json)

⚠️ Caution: Never commit the credentials.json file to Git! Add it to .gitignore.

Create and Share Google Sheets

Google SheetsCreate a new spreadsheet in
Copy the Spreadsheet ID from the URL (e.g., 1abc...xyz)
Click the 'Share' button
Add the service account email (client_email in credentials.json)
Grant 'Editor' permissions

Update Config File

Add Google Sheets information to the i18nexus.config.json file:

{
  "languages": ["en", "ko"],
  "defaultLanguage": "ko",
  "localesDir": "./locales",
  "sourcePattern": "app/**/*.{ts,tsx}",
  "googleSheets": {
    "spreadsheetId": "YOUR_SPREADSHEET_ID",
    "credentialsPath": "./credentials.json",
    "sheetName": "Translations"
  }
}

i18n-upload: Local to Sheets

Uploads local translation files to Google Sheets. Existing data in Sheets will be completely replaced.

Basic Usage

npx i18n-upload --spreadsheet-id "YOUR_ID" --credentials "./credentials.json"

Command Options

--spreadsheet-id

Google Sheets Spreadsheet ID

--credentials

Path to the service account credentials JSON file

--sheet-name

Sheet name (Default: "Translations")

⚠️Precautions

•Upload completely replaces existing data in Sheets
•Back up your Sheets data first if it's important
•Generally used only once at the beginning of a project

i18n-download: Sheets to Local

Downloads translations from Google Sheets to local files. Uses an incremental update method to preserve existing translations.

Basic Usage

npx i18n-download --spreadsheet-id "YOUR_ID" --credentials "./credentials.json"

How it works

1.Reads all translations from Google Sheets
2.Reads existing translations from local files
3.Update with translations from Sheets, but preserve local-only translations
4.Saves the merged result to local files

✓Safe Incremental Updates

i18n-download fetches only the changes from Sheets while preserving existing translations:

✓Keys existing in Sheets: Values updated
✓Local-only keys: Kept as is
✓New keys in Sheets: Added locally

i18n-download-force: Force Sync

Completely overwrites local translation files with data from Google Sheets.

Basic Usage

npx i18n-download-force --spreadsheet-id "YOUR_ID" --credentials "./credentials.json"

Difference from regular download

i18n-download

•Incremental Update
•Preserve Local Translations
•Safe

i18n-download-force

•Full Overwrite
•Delete Local Translations
•Caution Needed

⚠️Warning

•This command completely overwrites local translation files
•All local-only translations will be deleted
•Use only when Sheets is your Single Source of Truth

Workflow Example

Initial Setup and Upload

# 1. Extract translation keys from code
npx i18n-extractor -p "app/**/*.tsx" -d "./locales"

# 2. Upload local translations to Google Sheets
npx i18n-upload --spreadsheet-id "YOUR_ID"

# 3. Team members start translation work in Google Sheets

Routine Sync

# 1. Developer: Extract keys after adding new features
npx i18n-extractor

# 2. Developer: Upload new keys to Sheets
npx i18n-upload --spreadsheet-id "YOUR_ID"

# 3. Translator: Work on translations in Google Sheets

# 4. Developer: Download translations to local after completion
npx i18n-download --spreadsheet-id "YOUR_ID"

# 5. Commit changes to Git
git add locales/
git commit -m "Update translations"

CI/CD Integration

# .github/workflows/sync-translations.yml
name: Sync Translations

on:
  schedule:
    - cron: '0 2 * * *'  # 매일 오전 2시
  workflow_dispatch:  # 수동 실행 가능

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Download translations
        run: |
          npx i18n-download \\
            --spreadsheet-id "\${{ secrets.SHEET_ID }}" \\
            --credentials ./credentials.json
      
      - name: Create PR if changes
        uses: peter-evans/create-pull-request@v5
        with:
          title: "Update translations from Sheets"
          commit-message: "chore: sync translations"

Best Practices

✅Use incremental download first

Use i18n-download in most cases. It safely fetches only the changes.

✅Manage credentials securely

Add credentials.json to .gitignore and manage it with environment variables or secrets.

# .gitignore
credentials.json
*.credentials.json

✅Maintain Sheets Structure

The first row of Google Sheets must be language codes, and the first column must be translation keys. Do not change this structure.

💡Regular Sync

Sync periodically to keep translations up-to-date.

Troubleshooting

Error: Permission denied

Solution:

Check if the Google Sheet is shared with the service account email
Check if 'Editor' permission is granted

Error: API not enabled

Solution:

Check if the Google Sheets API is enabled in the Google Cloud Console
Check if the correct project is selected

Error: Credentials not found

Solution:

Check if the credentials.json file is in the correct path
Try the file path as an absolute path

Next Steps

🔍i18n-extractor →

Learn how to extract translation keys

⚡Full Workflow →

View full CLI tool workflow