📥

i18n-download

Safely downloads translations from Google Sheets to local

Overview

i18n-downloadis a CLI tool that downloads translations from Google Sheets to local JSON files. It preserves existing translations using an incremental update method and merges safely.

✓Preserve Existing Local Translations

✓Safely Merge Only Changes from Sheets

✓Automatic Conflict Resolution

✓Display Detailed Change Log

Basic Usage

Use Config File

If Google Sheets information is set in i18nexus.config.json:

npx i18n-download

Use Command Line Options

npx i18n-download \
  --spreadsheet-id "YOUR_SPREADSHEET_ID" \
  --credentials "./credentials.json"

How it works

Fetch Sheets Data

Reads all translation data from Google Sheets.

Read Local Data

Reads existing local translation files.

Smart Merge

Intelligently merges two data sources:

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

Save File

Saves merged results to local files and displays change log.

Command Options

--spreadsheet-idString

Google Sheets Spreadsheet ID (required)

--credentialsString

Google Cloud service account credentials JSON file path (required)

--sheet-nameString

Sheet name to read (default: "Translations")

--locales-dirString

Directory to save translation files (default: "./locales")

Example Output

$ npx i18n-download --spreadsheet-id "1abc...xyz"

📥 Downloading translations from Google Sheets...

📊 Reading from Sheets...
   Spreadsheet: "i18n Translations"
   Sheet: "Translations"
   ✓ Found 130 translation keys
   Languages: ko, en

📁 Reading local files...
   ✓ locales/ko.json (125 keys)
   ✓ locales/en.json (125 keys)

🔄 Merging translations...
   ✓ Updated: 3 keys
   ✓ Added: 5 new keys
   ✓ Preserved: 122 local keys

💾 Saving files...
   ✓ locales/ko.json (130 keys)
   ✓ locales/en.json (130 keys)

✅ Download complete!
   Total keys: 130
   Changes: +5 new, ~3 updated

Safety Features

Prevent Data Loss

✓
Preserve Local Translations
Translation keys that exist only locally are never deleted.
✓
Automatic Conflict Resolution
If the same key exists in both, Sheets value takes priority.
✓
Backup Recommended
Using version control like Git allows you to restore to a previous state at any time.

i18n-download vs i18n-download-force

📥i18n-download

✓Incremental Update
✓Preserve Local Translations
✓Safe Merge
✓Use Regularly

💡 Use this in most cases

🔄i18n-download-force

•Full Overwrite
•Delete Local Translations
•Sheets = Single Source of Truth
•Use with Caution

⚠️ Use Only in Special Cases

Best Practices

✅Download Regularly

Download regularly after translators complete their work to keep translations up-to-date.

✅Git Commit

After downloading, commit changes to Git to share with team members.

✅Review Changes

Review the change log output after downloading to check for unexpected changes.

Next Steps

🔄i18n-download-force →

Learn about force sync option

📤i18n-upload →

How to Upload Local Translations to Sheets