🌍 GemPages i18n CLI Tool

A command-line tool for managing internationalization (i18n) operations, including generating locale files from Google Sheets and creating untranslated text lists.

Features

• 📄 Generate Locale Files: Fetch translation data from Google Sheets and generate JSON locale files (per sheet)
• 🔀 Generate Merged Locale Files: Merge all sheets into single JSON files per language
• 📊 Generate Untranslated Lists: Convert JSON files to Excel spreadsheets for translation tracking

Prerequisites

• Node.js 18 or higher
• Google Sheets API key (for locale file generation)
• Access to Google Spreadsheet with translation data

Installation

Install from npm

# Install globally
npm install -g @unpijs/i18n-cli

# Or use with npx (no install required)
npx @unpijs/i18n-cli

Local Development

git clone https://github.com/pin705/gempage-i18n-cli.git
cd gempage-i18n-cli
npm install
npm run build

Usage

Interactive Mode

Run the CLI tool in interactive mode:

# If installed globally
gp-i18n

# Or using npx
npx @unpijs/i18n-cli

The tool will present you with a menu:

1. 📄 Generate locale files from Google Sheets (per sheet)

   • Generates separate folders for each sheet
   • You'll be prompted to enter:
     • Google Sheets API key
     • Spreadsheet ID (found in the Google Sheet URL)
     • Sheet names (comma-separated)
     • Output directory

2. 🔀 Generate merged locale files (all sheets → one file per language)

   • Merges all sheets into single JSON files per language (e.g., cn.json, es.json, vi.json)
   • Useful for projects that need all translations in one file per language
   • You'll be prompted to enter:
     • Google Sheets API key
     • Spreadsheet ID
     • Sheet names (comma-separated)
     • Output directory (default: ./locales)

3. 📊 Generate untranslated text list (JSON → XLSX)

   • You'll be prompted to enter:
     • Path to input JSON file
     • Output Excel file name

Programmatic Usage

You can also use the modules directly in your code:

import { generateLocaleFiles } from '@unpijs/i18n-cli/dist/generate-locale.js';
import { generateMergedLocaleFiles } from '@unpijs/i18n-cli/dist/generate-merged-locale.js';
import { generateUntranslatedXlsx } from '@unpijs/i18n-cli/dist/generate-untranslated.js';

// Generate locale files (per sheet)
await generateLocaleFiles({
  apiKey: 'YOUR_API_KEY',
  spreadsheetId: 'YOUR_SPREADSHEET_ID',
  sheets: ['Builder', 'Dashboard', 'Element'],
  outputDir: './output',
});

// Generate merged locale files (all sheets → one file per language)
await generateMergedLocaleFiles({
  apiKey: 'YOUR_API_KEY',
  spreadsheetId: 'YOUR_SPREADSHEET_ID',
  sheets: ['Builder', 'Control Search keywork'],
  outputDir: './locales',
});

// Generate untranslated Excel
await generateUntranslatedXlsx({
  inputFile: './input.json',
  outputFile: './untranslated.xlsx',
});

Getting a Google Sheets API Key

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Google Sheets API
4. Create credentials (API Key)
5. Copy the API key for use with this tool

Google Sheet Format

The tool expects Google Sheets with the following structure:

| Column A (ignored) | Column B (en) | Column C (cn) | Column D (es) | Column E (vi) | | ------------------ | ------------- | ------------- | ------------- | --------------- | | (any data) | English text | Chinese text | Spanish text | Vietnamese text |

• The first row is treated as headers
• Column B should contain 'en' (English) as the base language
• Other columns contain translations for different languages
• The tool will generate separate JSON files for each language

Output Structure

Locale Files (per sheet)

output/
├── Builder/
│   ├── Builder_cn.json
│   ├── Builder_es.json
│   └── Builder_vi.json
├── Dashboard/
│   ├── Dashboard_cn.json
│   ├── Dashboard_es.json
│   └── Dashboard_vi.json
└── ...

Merged Locale Files

locales/
├── cn.json
├── es.json
└── vi.json

Untranslated Excel

The generated Excel file will have the following columns:

• en: English text (source)
• cn: Chinese translation (empty, to be filled)
• es: Spanish translation (empty, to be filled)
• location: File location reference (if available)

Examples

Example 1: Generate Locale Files (per sheet)

? What would you like to do? 📄 Generate locale files from Google Sheets (per sheet)
? Enter your Google Sheets API key: AIzaSyBRgv3k-pBWKeTJh96iqxmyYjNDZl1voRI
? Enter the Google Spreadsheet ID: 1bSk7e7JvbDGZc7XY6ufzzQjIRBgJA0ayaxZFQf3B-Vw
? Enter sheet names (comma-separated): Builder, Dashboard, Element
? Enter output directory: ./output

✅ Generated 9 locale files:
   - ./output/Builder/Builder_cn.json
   - ./output/Builder/Builder_es.json
   - ./output/Builder/Builder_vi.json
   ...

Example 2: Generate Merged Locale Files

? What would you like to do? 🔀 Generate merged locale files (all sheets → one file per language)
? Enter your Google Sheets API key: AIzaSyBRgv3k-pBWKeTJh96iqxmyYjNDZl1voRI
? Enter the Google Spreadsheet ID: 1bSk7e7JvbDGZc7XY6ufzzQjIRBgJA0ayaxZFQf3B-Vw
? Enter sheet names (comma-separated): Builder, Control Search keywork
? Enter output directory: ./locales

✅ Generated 3 merged locale files:
   - ./locales/cn.json
   - ./locales/es.json
   - ./locales/vi.json

Example 3: Generate Untranslated List

? What would you like to do? 📊 Generate untranslated text list (JSON → XLSX)
? Enter path to input JSON file: ./translations.json
? Enter output Excel file name: untranslated.xlsx

✅ Generated untranslated Excel file: untranslated.xlsx
   Total entries: 247

Development

# Run in development mode
npm run dev

# Build
npm run build

# Run built version
npm start

Publishing

This package uses GitHub Actions for automatic publishing to npm. When you push to main branch with a new version, it will automatically publish.

Auto-publish (Recommended)

1. Update version in package.json:

   # Patch version (1.0.0 -> 1.0.1)
   npm version patch
      
   # Minor version (1.0.0 -> 1.1.0)
   npm version minor
      
   # Major version (1.0.0 -> 2.0.0)
   npm version major

2. Push to GitHub:

   git push && git push --tags

3. GitHub Actions will automatically:

   • Build the project
   • Check if version is new
   • Publish to npm

Manual publish

npm login
npm publish --access public

Setup GitHub Actions (for maintainers)

1. Create an npm access token at https://www.npmjs.com/settings/YOUR_USERNAME/tokens
   • Choose "Granular Access Token"
   • Enable "Allow publishing without 2FA"
2. Add the token to GitHub Secrets:
   • Go to https://github.com/pin705/gempage-i18n-cli/settings/secrets/actions
   • Add secret with name NPM_TOKEN

License

MIT

Author

GemPages